code: def deprecated(
      since,
      *,
      message="",
      name="",
      alternative="",
      pending=False,
      obj_type=None,
      addendum="",
      removal="",
  ):
      """
      Decorator to mark a function, a class, or a property as deprecated.
  
      When deprecating a classmethod, a staticmethod, or a property, the
      ``@deprecated`` decorator should go *under* ``@classmethod`` and
      ``@staticmethod`` (i.e., `deprecated` should directly decorate the
      underlying callable), but *over* ``@property``.
  
      When deprecating a class ``C`` intended to be used as a base class in a
      multiple inheritance hierarchy, ``C`` *must* define an ``__init__`` method
      (if ``C`` instead inherited its ``__init__`` from its own base class, then
      ``@deprecated`` would mess up ``__init__`` inheritance when installing its
      own (deprecation-emitting) ``C.__init__``).
  
      Parameters are the same as for `warn_deprecated`, except that *obj_type*
      defaults to 'class' if decorating a class, 'attribute' if decorating a
      property, and 'function' otherwise.
  
      Examples
      --------
      ::
  
          @deprecated('1.4.0')
          def the_function_to_deprecate():
              pass
      """
  
      def deprecate(
          obj,
          message=message,
          name=name,
          alternative=alternative,
          pending=pending,
          obj_type=obj_type,
          addendum=addendum,
      ):
          from matplotlib._api import classproperty
  
          if isinstance(obj, type):
              if obj_type is None:
                  obj_type = "class"
              func = obj.__init__
              name = name or obj.__name__
              old_doc = obj.__doc__
  
              def finalize(wrapper, new_doc):
                  try:
                      obj.__doc__ = new_doc
                  except (
                      AttributeError
                  ):  # Can't set on some extension objects.
                      pass
                  obj.__init__ = functools.wraps(obj.__init__)(wrapper)
                  return obj
  
          elif isinstance(obj, (property, classproperty)):
              if obj_type is None:
                  obj_type = "attribute"
              func = None
              name = name or obj.fget.__name__
              old_doc = obj.__doc__
  
              class _deprecated_property(type(obj)):
                  def __get__(self, instance, owner=None):
                      if (
                          instance is not None
                          or owner is not None
                          and isinstance(self, classproperty)
                      ):
                          emit_warning()
                      return super().__get__(instance, owner)
  
                  def __set__(self, instance, value):
                      if instance is not None:
                          emit_warning()
                      return super().__set__(instance, value)
  
                  def __delete__(self, instance):
                      if instance is not None:
                          emit_warning()
                      return super().__delete__(instance)
  
                  def __set_name__(self, owner, set_name):
                      nonlocal name
                      if name == "<lambda>":
                          name = set_name
  
              def finalize(_, new_doc):
                  return _deprecated_property(
                      fget=obj.fget,
                      fset=obj.fset,
                      fdel=obj.fdel,
                      doc=new_doc,
                  )
  
          else:
              if obj_type is None:
                  obj_type = "function"
              func = obj
              name = name or obj.__name__
              old_doc = func.__doc__
  
              def finalize(wrapper, new_doc):
                  wrapper = functools.wraps(func)(wrapper)
                  wrapper.__doc__ = new_doc
                  return wrapper
  
          def emit_warning():
              warn_deprecated(
                  since,
                  message=message,
                  name=name,
                  alternative=alternative,
                  pending=pending,
                  obj_type=obj_type,
                  addendum=addendum,
                  removal=removal,
              )
  
          def wrapper(*args, **kwargs):
              emit_warning()
              return func(*args, **kwargs)
  
          old_doc = inspect.cleandoc(old_doc or "").strip("\n")
  
          notes_header = "\nNotes\n-----"
          second_arg = " ".join(
              [
                  t.strip()
                  for t in (
                      message,
                      f"Use {alternative} instead."
                      if alternative
                      else "",
                      addendum,
                  )
                  if t
              ]
          )
          new_doc = (
              f"[*Deprecated*] {old_doc}\n"
              f"{notes_header if notes_header not in old_doc else ''}\n"
              f".. deprecated:: {since}\n"
              f"   {second_arg}"
          )
  
          if not old_doc:
              # This is to prevent a spurious 'unexpected unindent' warning from
              # docutils when the original docstring was blank.
              new_doc += r"\ "
  
          return finalize(wrapper, new_doc)
  
      return deprecate
  
file_path: catboost/contrib/python/matplotlib/py3/matplotlib/_api/deprecation.py
imports: import contextlib
  import functools
  import inspect
  import math
  import warnings
label_desc: Use image node_id 3 for calling a global function with example usage: deprecated(since) and returns: deprecate, finalize, func, obj, _deprecated_property, wrapper, super, super, super