net-imap 0.4.12 → 0.5.5

data/lib/net/imap/config.rb

@@ -0,0 +1,402 @@
+# frozen_string_literal: true
+
+require_relative "config/attr_accessors"
+require_relative "config/attr_inheritance"
+require_relative "config/attr_type_coercion"
+
+module Net
+  class IMAP
+
+    # Net::IMAP::Config <em>(available since +v0.4.13+)</em> stores
+    # configuration options for Net::IMAP clients.  The global configuration can
+    # be seen at either Net::IMAP.config or Net::IMAP::Config.global, and the
+    # client-specific configuration can be seen at Net::IMAP#config.
+    #
+    # When creating a new client, all unhandled keyword arguments to
+    # Net::IMAP.new are delegated to Config.new.  Every client has its own
+    # config.
+    #
+    #   debug_client = Net::IMAP.new(hostname, debug: true)
+    #   quiet_client = Net::IMAP.new(hostname, debug: false)
+    #   debug_client.config.debug?  # => true
+    #   quiet_client.config.debug?  # => false
+    #
+    # == Inheritance
+    #
+    # Configs have a parent[rdoc-ref:Config::AttrInheritance#parent] config, and
+    # any attributes which have not been set locally will inherit the parent's
+    # value.  Every client creates its own specific config.  By default, client
+    # configs inherit from Config.global.
+    #
+    #   plain_client = Net::IMAP.new(hostname)
+    #   debug_client = Net::IMAP.new(hostname, debug: true)
+    #   quiet_client = Net::IMAP.new(hostname, debug: false)
+    #
+    #   plain_client.config.inherited?(:debug)  # => true
+    #   debug_client.config.inherited?(:debug)  # => false
+    #   quiet_client.config.inherited?(:debug)  # => false
+    #
+    #   plain_client.config.debug?  # => false
+    #   debug_client.config.debug?  # => true
+    #   quiet_client.config.debug?  # => false
+    #
+    #   # Net::IMAP.debug is delegated to Net::IMAP::Config.global.debug
+    #   Net::IMAP.debug = true
+    #   plain_client.config.debug?  # => true
+    #   debug_client.config.debug?  # => true
+    #   quiet_client.config.debug?  # => false
+    #
+    #   Net::IMAP.debug = false
+    #   plain_client.config.debug = true
+    #   plain_client.config.inherited?(:debug)  # => false
+    #   plain_client.config.debug?  # => true
+    #   plain_client.config.reset(:debug)
+    #   plain_client.config.inherited?(:debug)  # => true
+    #   plain_client.config.debug?  # => false
+    #
+    # == Versioned defaults
+    #
+    # The effective default configuration for a specific +x.y+ version of
+    # +net-imap+ can be loaded with the +config+ keyword argument to
+    # Net::IMAP.new.  Requesting default configurations for previous versions
+    # enables extra backward compatibility with those versions:
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.3)
+    #   client.config.sasl_ir                  # => false
+    #   client.config.responses_without_block  # => :silence_deprecation_warning
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.4)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :silence_deprecation_warning
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.5)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :warn
+    #
+    #   client = Net::IMAP.new(hostname, config: :future)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :frozen_dup
+    #
+    # The versioned default configs inherit certain specific config options from
+    # Config.global, for example #debug:
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.4)
+    #   Net::IMAP.debug = false
+    #   client.config.debug?  # => false
+    #
+    #   Net::IMAP.debug = true
+    #   client.config.debug?  # => true
+    #
+    # Use #load_defaults to globally behave like a specific version:
+    #   client = Net::IMAP.new(hostname)
+    #   client.config.sasl_ir              # => true
+    #   Net::IMAP.config.load_defaults 0.3
+    #   client.config.sasl_ir              # => false
+    #
+    # === Named defaults
+    # In addition to +x.y+ version numbers, the following aliases are supported:
+    #
+    # [+:default+]
+    #   An alias for +:current+.
+    #
+    #   >>>
+    #   *NOTE*: This is _not_ the same as Config.default.  It inherits some
+    #   attributes from Config.global, for example: #debug.
+    # [+:current+]
+    #   An alias for the current +x.y+ version's defaults.
+    # [+:next+]
+    #   The _planned_ config for the next +x.y+ version.
+    # [+:future+]
+    #   The _planned_ eventual config for some future +x.y+ version.
+    #
+    # For example, to disable all currently deprecated behavior:
+    #   client = Net::IMAP.new(hostname, config: :future)
+    #   client.config.response_without_args     # => :frozen_dup
+    #   client.responses.frozen?                # => true
+    #   client.responses.values.all?(&:frozen?) # => true
+    #
+    # == Thread Safety
+    #
+    # *NOTE:* Updates to config objects are not synchronized for thread-safety.
+    #
+    class Config
+      # Array of attribute names that are _not_ loaded by #load_defaults.
+      DEFAULT_TO_INHERIT = %i[debug].freeze
+      private_constant :DEFAULT_TO_INHERIT
+
+      # The default config, which is hardcoded and frozen.
+      def self.default; @default end
+
+      # The global config object.  Also available from Net::IMAP.config.
+      def self.global; @global if defined?(@global) end
+
+      # A hash of hard-coded configurations, indexed by version number or name.
+      def self.version_defaults; @version_defaults end
+      @version_defaults = {}
+
+      # :call-seq:
+      #  Net::IMAP::Config[number] -> versioned config
+      #  Net::IMAP::Config[symbol] -> named config
+      #  Net::IMAP::Config[hash]   -> new frozen config
+      #  Net::IMAP::Config[config] -> same config
+      #
+      # Given a version number, returns the default configuration for the target
+      # version.  See Config@Versioned+defaults.
+      #
+      # Given a version name, returns the default configuration for the target
+      # version.  See Config@Named+defaults.
+      #
+      # Given a Hash, creates a new _frozen_ config which inherits from
+      # Config.global.  Use Config.new for an unfrozen config.
+      #
+      # Given a config, returns that same config.
+      def self.[](config)
+        if    config.is_a?(Config)         then config
+        elsif config.nil? && global.nil?   then nil
+        elsif config.respond_to?(:to_hash) then new(global, **config).freeze
+        else
+          version_defaults.fetch(config) do
+            case config
+            when Numeric
+              raise RangeError, "unknown config version: %p" % [config]
+            when Symbol
+              raise KeyError, "unknown config name: %p" % [config]
+            else
+              raise TypeError, "no implicit conversion of %s to %s" % [
+                config.class, Config
+              ]
+            end
+          end
+        end
+      end
+
+      include AttrAccessors
+      include AttrInheritance
+      include AttrTypeCoercion
+
+      # The debug mode (boolean).  The default value is +false+.
+      #
+      # When #debug is +true+:
+      # * Data sent to and received from the server will be logged.
+      # * ResponseParser will print warnings with extra detail for parse
+      #   errors.  _This may include recoverable errors._
+      # * ResponseParser makes extra assertions.
+      #
+      # *NOTE:* Versioned default configs inherit #debug from Config.global, and
+      # #load_defaults will not override #debug.
+      attr_accessor :debug, type: :boolean
+
+      # method: debug?
+      # :call-seq: debug? -> boolean
+      #
+      # Alias for #debug
+
+      # Seconds to wait until a connection is opened.
+      #
+      # If the IMAP object cannot open a connection within this time,
+      # it raises a Net::OpenTimeout exception.
+      #
+      # See Net::IMAP.new.
+      #
+      # The default value is +30+ seconds.
+      attr_accessor :open_timeout, type: Integer
+
+      # Seconds to wait until an IDLE response is received, after
+      # the client asks to leave the IDLE state.
+      #
+      # See Net::IMAP#idle and Net::IMAP#idle_done.
+      #
+      # The default value is +5+ seconds.
+      attr_accessor :idle_response_timeout, type: Integer
+
+      # Whether to use the +SASL-IR+ extension when the server and \SASL
+      # mechanism both support it.  Can be overridden by the +sasl_ir+ keyword
+      # parameter to Net::IMAP#authenticate.
+      #
+      # <em>(Support for +SASL-IR+ was added in +v0.4.0+.)</em>
+      #
+      # ==== Valid options
+      #
+      # [+false+ <em>(original behavior, before support was added)</em>]
+      #   Do not use +SASL-IR+, even when it is supported by the server and the
+      #   mechanism.
+      #
+      # [+true+ <em>(default since +v0.4+)</em>]
+      #   Use +SASL-IR+ when it is supported by the server and the mechanism.
+      attr_accessor :sasl_ir, type: :boolean
+
+      # Controls the behavior of Net::IMAP#login when the +LOGINDISABLED+
+      # capability is present.  When enforced, Net::IMAP will raise a
+      # LoginDisabledError when that capability is present.
+      #
+      # <em>(Support for +LOGINDISABLED+ was added in +v0.5.0+.)</em>
+      #
+      # ==== Valid options
+      #
+      # [+false+ <em>(original behavior, before support was added)</em>]
+      #   Send the +LOGIN+ command without checking for +LOGINDISABLED+.
+      #
+      # [+:when_capabilities_cached+]
+      #   Enforce the requirement when Net::IMAP#capabilities_cached? is true,
+      #   but do not send a +CAPABILITY+ command to discover the capabilities.
+      #
+      # [+true+ <em>(default since +v0.5+)</em>]
+      #   Only send the +LOGIN+ command if the +LOGINDISABLED+ capability is not
+      #   present.  When capabilities are unknown, Net::IMAP will automatically
+      #   send a +CAPABILITY+ command first before sending +LOGIN+.
+      #
+      attr_accessor :enforce_logindisabled, type: [
+        false, :when_capabilities_cached, true
+      ]
+
+      # Controls the behavior of Net::IMAP#responses when called without any
+      # arguments (+type+ or +block+).
+      #
+      # ==== Valid options
+      #
+      # [+:silence_deprecation_warning+ <em>(original behavior)</em>]
+      #   Returns the mutable responses hash (without any warnings).
+      #   <em>This is not thread-safe.</em>
+      #
+      # [+:warn+ <em>(default since +v0.5+)</em>]
+      #   Prints a warning and returns the mutable responses hash.
+      #   <em>This is not thread-safe.</em>
+      #
+      # [+:frozen_dup+ <em>(planned default for +v0.6+)</em>]
+      #   Returns a frozen copy of the unhandled responses hash, with frozen
+      #   array values.
+      #
+      #   Note that calling IMAP#responses with a +type+ and without a block is
+      #   not configurable and always behaves like +:frozen_dup+.
+      #
+      #   <em>(+:frozen_dup+ config option was added in +v0.4.17+)</em>
+      #
+      # [+:raise+]
+      #   Raise an ArgumentError with the deprecation warning.
+      #
+      # Note: #responses_without_args is an alias for #responses_without_block.
+      attr_accessor :responses_without_block, type: [
+        :silence_deprecation_warning, :warn, :frozen_dup, :raise,
+      ]
+
+      alias responses_without_args  responses_without_block  # :nodoc:
+      alias responses_without_args= responses_without_block= # :nodoc:
+
+      ##
+      # :attr_accessor: responses_without_args
+      #
+      # Alias for responses_without_block
+
+      # Creates a new config object and initialize its attribute with +attrs+.
+      #
+      # If +parent+ is not given, the global config is used by default.
+      #
+      # If a block is given, the new config object is yielded to it.
+      def initialize(parent = Config.global, **attrs)
+        super(parent)
+        update(**attrs)
+        yield self if block_given?
+      end
+
+      # :call-seq: update(**attrs) -> self
+      #
+      # Assigns all of the provided +attrs+ to this config, and returns +self+.
+      #
+      # An ArgumentError is raised unless every key in +attrs+ matches an
+      # assignment method on Config.
+      #
+      # >>>
+      #   *NOTE:*  #update is not atomic.  If an exception is raised due to an
+      #   invalid attribute value, +attrs+ may be partially applied.
+      def update(**attrs)
+        unless (bad = attrs.keys.reject { respond_to?(:"#{_1}=") }).empty?
+          raise ArgumentError, "invalid config options: #{bad.join(", ")}"
+        end
+        attrs.each do send(:"#{_1}=", _2) end
+        self
+      end
+
+      # :call-seq:
+      #   with(**attrs) -> config
+      #   with(**attrs) {|config| } -> result
+      #
+      # Without a block, returns a new config which inherits from self.  With a
+      # block, yields the new config and returns the block's result.
+      #
+      # If no keyword arguments are given, an ArgumentError will be raised.
+      #
+      # If +self+ is frozen, the copy will also be frozen.
+      def with(**attrs)
+        attrs.empty? and
+          raise ArgumentError, "expected keyword arguments, none given"
+        copy = new(**attrs)
+        copy.freeze if frozen?
+        block_given? ? yield(copy) : copy
+      end
+
+      # :call-seq: load_defaults(version) -> self
+      #
+      # Resets the current config to behave like the versioned default
+      # configuration for +version+.  #parent will not be changed.
+      #
+      # Some config attributes default to inheriting from their #parent (which
+      # is usually Config.global) and are left unchanged, for example: #debug.
+      #
+      # See Config@Versioned+defaults and Config@Named+defaults.
+      def load_defaults(version)
+        [Numeric, Symbol, String].any? { _1 === version } or
+          raise ArgumentError, "expected number or symbol, got %p" % [version]
+        update(**Config[version].defaults_hash)
+      end
+
+      # :call-seq: to_h -> hash
+      #
+      # Returns all config attributes in a hash.
+      def to_h; data.members.to_h { [_1, send(_1)] } end
+
+      protected
+
+      def defaults_hash
+        to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
+      end
+
+      @default = new(
+        debug: false,
+        open_timeout: 30,
+        idle_response_timeout: 5,
+        sasl_ir: true,
+        enforce_logindisabled: true,
+        responses_without_block: :warn,
+      ).freeze
+
+      @global = default.new
+
+      version_defaults[:default] = Config[default.send(:defaults_hash)]
+      version_defaults[:current] = Config[:default]
+
+      version_defaults[0] = Config[:current].dup.update(
+        sasl_ir: false,
+        responses_without_block: :silence_deprecation_warning,
+        enforce_logindisabled: false,
+      ).freeze
+      version_defaults[0.0] = Config[0]
+      version_defaults[0.1] = Config[0]
+      version_defaults[0.2] = Config[0]
+      version_defaults[0.3] = Config[0]
+
+      version_defaults[0.4] = Config[0.3].dup.update(
+        sasl_ir: true,
+      ).freeze
+
+      version_defaults[0.5] = Config[:current]
+
+      version_defaults[0.6] = Config[0.5].dup.update(
+        responses_without_block: :frozen_dup,
+      ).freeze
+      version_defaults[:next] = Config[0.6]
+      version_defaults[:future] = Config[:next]
+
+      version_defaults.freeze
+    end
+  end
+end

data/lib/net/imap/data_encoding.rb

@@ -186,7 +186,7 @@ module Net
 
       # Ensure argument is 'number' or raise DataFormatError
       def ensure_number(num)
-        return if valid_number?(num)
+        return num if valid_number?(num)
 
         msg = "number must be unsigned 32-bit integer: #{num}"
         raise DataFormatError, msg
@@ -194,7 +194,7 @@ module Net
 
       # Ensure argument is 'nz_number' or raise DataFormatError
       def ensure_nz_number(num)
-        return if valid_nz_number?(num)
+        return num if valid_nz_number?(num)
 
         msg = "nz_number must be non-zero unsigned 32-bit integer: #{num}"
         raise DataFormatError, msg
@@ -202,7 +202,7 @@ module Net
 
       # Ensure argument is 'mod_sequence_value' or raise DataFormatError
       def ensure_mod_sequence_value(num)
-        return if valid_mod_sequence_value?(num)
+        return num if valid_mod_sequence_value?(num)
 
         msg = "mod_sequence_value must be unsigned 64-bit integer: #{num}"
         raise DataFormatError, msg

data/lib/net/imap/data_lite.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+# Some of the code in this file was copied from the polyfill-data gem.
+#
+# MIT License
+#
+# Copyright (c) 2023 Jim Gay, Joel Drapper, Nicholas Evans
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+module Net
+  class IMAP
+    data_or_object = RUBY_VERSION >= "3.2.0" ? ::Data : Object
+    class DataLite < data_or_object
+      def encode_with(coder) coder.map = to_h.transform_keys(&:to_s)        end
+      def init_with(coder) initialize(**coder.map.transform_keys(&:to_sym)) end
+    end
+
+    Data = DataLite
+  end
+end
+
+# :nocov:
+# Need to skip test coverage for the rest, because it isn't loaded by ruby 3.2+.
+return if RUBY_VERSION >= "3.2.0"
+
+module Net
+  class IMAP
+    # DataLite is a temporary substitute for ruby 3.2's +Data+ class.  DataLite
+    # is aliased as Net::IMAP::Data, so that code using it won't need to be
+    # updated when it is removed.
+    #
+    # See {ruby 3.2's documentation for Data}[https://docs.ruby-lang.org/en/3.2/Data.html].
+    #
+    # [When running ruby 3.1]
+    #    This class reimplements the API for ruby 3.2's +Data+, and should be
+    #    compatible for nearly all use-cases.  This reimplementation <em>will be
+    #    removed</em> in +net-imap+ 0.6, when support for ruby 3.1 is dropped.
+    #
+    #    _NOTE:_ +net-imap+ no longer supports ruby versions prior to 3.1.
+    # [When running ruby >= 3.2]
+    #    This class inherits from +Data+ and _only_ defines the methods needed
+    #    for YAML serialization.  This will be dropped when +psych+ adds support
+    #    for +Data+.
+    #
+    # Some of the code in this class was copied or adapted from the
+    # {polyfill-data gem}[https://rubygems.org/gems/polyfill-data], by Jim Gay
+    # and Joel Drapper, under the MIT license terms.
+    class DataLite
+      singleton_class.undef_method :new
+
+      TYPE_ERROR    = "%p is not a symbol nor a string"
+      ATTRSET_ERROR = "invalid data member: %p"
+      DUP_ERROR     = "duplicate member: %p"
+      ARITY_ERROR   = "wrong number of arguments (given %d, expected %s)"
+      private_constant :TYPE_ERROR, :ATTRSET_ERROR, :DUP_ERROR, :ARITY_ERROR
+
+      # Defines a new Data class.
+      #
+      # _NOTE:_ Unlike ruby 3.2's +Data.define+, DataLite.define only supports
+      # member names which are valid local variable names.  Member names can't
+      # be keywords (e.g: +next+ or +class+) or start with capital letters, "@",
+      # etc.
+      def self.define(*args, &block)
+        members = args.each_with_object({}) do |arg, members|
+          arg = arg.to_str unless arg in Symbol | String if arg.respond_to?(:to_str)
+          arg = arg.to_sym if     arg in String
+          arg in Symbol     or  raise TypeError,     TYPE_ERROR    % [arg]
+          arg in %r{=}      and raise ArgumentError, ATTRSET_ERROR % [arg]
+          members.key?(arg) and raise ArgumentError, DUP_ERROR     % [arg]
+          members[arg] = true
+        end
+        members = members.keys.freeze
+
+        klass = ::Class.new(self)
+
+        klass.singleton_class.undef_method :define
+        klass.define_singleton_method(:members) { members }
+
+        def klass.new(*args, **kwargs, &block)
+          if kwargs.size.positive?
+            if args.size.positive?
+              raise ArgumentError, ARITY_ERROR % [args.size, 0]
+            end
+          elsif members.size < args.size
+            expected = members.size.zero? ? 0 : 0..members.size
+            raise ArgumentError, ARITY_ERROR % [args.size, expected]
+          else
+            kwargs = Hash[members.take(args.size).zip(args)]
+          end
+          allocate.tap do |instance|
+            instance.__send__(:initialize, **kwargs, &block)
+          end.freeze
+        end
+
+        klass.singleton_class.alias_method :[], :new
+        klass.attr_reader(*members)
+
+        # Dynamically defined initializer methods are in an included module,
+        # rather than directly on DataLite (like in ruby 3.2+):
+        # * simpler to handle required kwarg ArgumentErrors
+        # * easier to ensure consistent ivar assignment order (object shape)
+        # * faster than instance_variable_set
+        klass.include(Module.new do
+          if members.any?
+            kwargs = members.map{"#{_1.name}:"}.join(", ")
+            params = members.map(&:name).join(", ")
+            ivars  = members.map{"@#{_1.name}"}.join(", ")
+            attrs  = members.map{"attrs[:#{_1.name}]"}.join(", ")
+            module_eval <<~RUBY, __FILE__, __LINE__ + 1
+              protected
+              def initialize(#{kwargs}) #{ivars} = #{params}; freeze end
+              def marshal_load(attrs)   #{ivars} = #{attrs};  freeze end
+            RUBY
+          end
+        end)
+
+        klass.module_eval do _1.module_eval(&block) end if block_given?
+
+        klass
+      end
+
+      ##
+      # singleton-method: new
+      # call-seq:
+      #   new(*args) -> instance
+      #   new(**kwargs) -> instance
+      #
+      # Constuctor for classes defined with ::define.
+      #
+      # Aliased as ::[].
+
+      ##
+      # singleton-method: []
+      # call-seq:
+      #   ::[](*args) -> instance
+      #   ::[](**kwargs) -> instance
+      #
+      # Constuctor for classes defined with ::define.
+      #
+      # Alias for ::new
+
+      ##
+      def members;     self.class.members                              end
+      def to_h(&block) block ? __to_h__.to_h(&block) : __to_h__        end
+      def hash;        [self.class, __to_h__].hash                     end
+      def ==(other)    self.class == other.class && to_h == other.to_h end
+      def eql?(other)  self.class == other.class && hash == other.hash end
+      def deconstruct; __to_h__.values                                 end
+
+      def deconstruct_keys(keys)
+        raise TypeError unless keys.is_a?(Array) || keys.nil?
+        return __to_h__ if keys&.first.nil?
+        __to_h__.slice(*keys)
+      end
+
+      def with(**kwargs)
+        return self if kwargs.empty?
+        self.class.new(**__to_h__.merge(kwargs))
+      end
+
+      def inspect
+        __inspect_guard__(self) do |seen|
+          return "#<data #{self.class}:...>" if seen
+          attrs = __to_h__.map {|kv| "%s=%p" % kv }.join(", ")
+          display = ["data", self.class.name, attrs].compact.join(" ")
+          "#<#{display}>"
+        end
+      end
+      alias_method :to_s, :inspect
+
+      private
+
+      def initialize_copy(source) super.freeze end
+      def marshal_dump; __to_h__ end
+
+      def __to_h__; Hash[members.map {|m| [m, send(m)] }] end
+
+      # Yields +true+ if +obj+ has been seen already, +false+ if it hasn't.
+      # Marks +obj+ as seen inside the block, so circuler references don't
+      # recursively trigger a SystemStackError (stack level too deep).
+      #
+      # Making circular references inside a Data object _should_ be very
+      # uncommon, but we'll support them for the sake of completeness.
+      def __inspect_guard__(obj)
+        preexisting = Thread.current[:__net_imap_data__inspect__]
+        Thread.current[:__net_imap_data__inspect__] ||= {}.compare_by_identity
+        inspect_guard = Thread.current[:__net_imap_data__inspect__]
+        if inspect_guard.include?(obj)
+          yield true
+        else
+          begin
+            inspect_guard[obj] = true
+            yield false
+          ensure
+            inspect_guard.delete(obj)
+          end
+        end
+      ensure
+        unless preexisting.equal?(inspect_guard)
+          Thread.current[:__net_imap_data__inspect__] = preexisting
+        end
+      end
+
+    end
+
+  end
+end
+# :nocov:

data/lib/net/imap/deprecated_client_options.rb

@@ -16,8 +16,8 @@ module Net
       #
       # ==== Obsolete arguments
       #
-      # Using obsolete arguments does not a warning.  Obsolete arguments will be
-      # deprecated by a future release.
+      # Use of obsolete arguments does not print a warning.  Obsolete arguments
+      # will be deprecated by a future release.
       #
       # If a second positional argument is given and it is a hash (or is
       # convertible via +#to_hash+), it is converted to keyword arguments.
@@ -83,10 +83,12 @@ module Net
         elsif deprecated.empty?
           super host, port: port_or_options
         elsif deprecated.shift
-          warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1
+          warn("DEPRECATED: Call Net::IMAP.new with keyword options",
+               uplevel: 1, category: :deprecated)
           super host, port: port_or_options, ssl: create_ssl_params(*deprecated)
         else
-          warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1
+          warn("DEPRECATED: Call Net::IMAP.new with keyword options",
+               uplevel: 1, category: :deprecated)
           super host, port: port_or_options, ssl: false
         end
       end
@@ -113,7 +115,8 @@ module Net
         elsif deprecated.first.respond_to?(:to_hash)
           super(**Hash.try_convert(deprecated.first))
         else
-          warn "DEPRECATED: Call Net::IMAP#starttls with keyword options", uplevel: 1
+          warn("DEPRECATED: Call Net::IMAP#starttls with keyword options",
+               uplevel: 1, category: :deprecated)
           super(**create_ssl_params(*deprecated))
         end
       end