Class: ActiveSupport::Deprecation

Inherits:
Object
  • Object
show all
Includes:
Behavior, Disallowed, InstanceDelegator, MethodWrapper, Reporting, Singleton
Defined in:
activesupport/lib/active_support/deprecation.rb,
activesupport/lib/active_support/deprecation/behaviors.rb,
activesupport/lib/active_support/deprecation/reporting.rb,
activesupport/lib/active_support/deprecation/disallowed.rb,
activesupport/lib/active_support/deprecation/deprecators.rb,
activesupport/lib/active_support/deprecation/proxy_wrappers.rb,
activesupport/lib/active_support/deprecation/method_wrappers.rb,
activesupport/lib/active_support/deprecation/constant_accessor.rb,
activesupport/lib/active_support/deprecation/instance_delegator.rb

Overview

Deprecation specifies the API used by Rails to deprecate methods, instance variables, objects, and constants. It’s also available for gems or applications.

For a gem, use Deprecation.new to create a Deprecation object and store it in your module or class (in order for users to be able to configure it).

module MyLibrary
  def self.deprecator
    @deprecator ||= ActiveSupport::Deprecation.new("2.0", "MyLibrary")
  end
end

For a Railtie or Engine, you may also want to add it to the application’s deprecators, so that the application’s configuration can be applied to it.

module MyLibrary
  class Railtie < Rails::Railtie
    initializer "deprecator" do |app|
      app.deprecators[:my_library] = MyLibrary.deprecator
    end
  end
end

With the above initializer, configuration settings like the following will affect MyLibrary.deprecator:

# in config/environments/test.rb
config.active_support.deprecation = :raise

Defined Under Namespace

Modules: Behavior, DeprecatedConstantAccessor, Disallowed, InstanceDelegator, MethodWrapper, Reporting Classes: DeprecatedConstantProxy, DeprecatedInstanceVariableProxy, DeprecatedObjectProxy, DeprecationProxy, Deprecators

Constant Summary collapse

DEFAULT_BEHAVIORS =

Default warning behaviors per Rails.env.

{
  raise: ->(message, callstack, deprecator) do
    e = DeprecationException.new(message)
    e.set_backtrace(callstack.map(&:to_s))
    raise e
  end,

  stderr: ->(message, callstack, deprecator) do
    $stderr.puts(message)
    $stderr.puts callstack.join("\n  ") if deprecator.debug
  end,

  log: ->(message, callstack, deprecator) do
    logger =
        if defined?(Rails.logger) && Rails.logger
          Rails.logger
        else
          require "active_support/logger"
          ActiveSupport::Logger.new($stderr)
        end
    logger.warn message
    logger.debug callstack.join("\n  ") if deprecator.debug
  end,

  notify: ->(message, callstack, deprecator) do
    ActiveSupport::Notifications.instrument(
      "deprecation.#{deprecator.gem_name.underscore.tr("/", "_")}",
      message: message,
      callstack: callstack,
      gem_name: deprecator.gem_name,
      deprecation_horizon: deprecator.deprecation_horizon,
    )
  end,

  silence: ->(message, callstack, deprecator) { },
}

Instance Attribute Summary collapse

Attributes included from Disallowed

#disallowed_warnings

Attributes included from Reporting

#gem_name, #silenced

Attributes included from Behavior

#debug

Instance Method Summary collapse

Methods included from MethodWrapper

#deprecate_methods

Methods included from Reporting

#allow, #begin_silence, #deprecation_warning, #end_silence, #silence, #warn

Methods included from Behavior

#behavior, #behavior=, #disallowed_behavior, #disallowed_behavior=

Methods included from InstanceDelegator

included

Methods included from Singleton

#duplicable?

Constructor Details

#initialize(deprecation_horizon = "7.2", gem_name = "Rails") ⇒ Deprecation

It accepts two parameters on initialization. The first is a version of library and the second is a library name.

ActiveSupport::Deprecation.new('2.0', 'MyLibrary')



67
68
69
70
71
72
73
74
75
 
# File 'activesupport/lib/active_support/deprecation.rb', line 67

def initialize(deprecation_horizon = "7.2", gem_name = "Rails")
  self.gem_name = gem_name
  self.deprecation_horizon = deprecation_horizon
  # By default, warnings are not silenced and debugging is off.
  self.silenced = false
  self.debug = false
  @silence_counter = Concurrent::ThreadLocalVar.new(0)
  @explicitly_allowed_warnings = Concurrent::ThreadLocalVar.new(nil)
end

Instance Attribute Details

#deprecation_horizon ⇒ Object

The version number in which the deprecated behavior will be removed, by default.



61
62
63
 
# File 'activesupport/lib/active_support/deprecation.rb', line 61

def deprecation_horizon
  @deprecation_horizon
end