code: def deprecated(reason, replacement, gone_in, issue=None):
      # type: (str, Optional[str], Optional[str], Optional[int]) -> None
      
  
      # Construct a nice message.
      # This is purposely eagerly formatted as we want it to appear as if someone
      # typed this entire message out.
      message = "DEPRECATION: " + reason
      if replacement is not None:
          message += " A possible replacement is {}.".format(replacement)
      if issue is not None:
          url = "https://github.com/pypa/pip/issues/" + str(issue)
          message += " You can find discussion regarding this at {}.".format(url)
  
      # Raise as an error if it has to be removed.
      if gone_in is not None and parse(current_version) >= parse(gone_in):
          raise PipDeprecationWarning(message)
      warnings.warn(message, category=PipDeprecationWarning, stacklevel=2)
docs: Helper to deprecate existing functionality.
  
      reason:
          Textual reason shown to the user about why this functionality has
          been deprecated.
      replacement:
          Textual suggestion shown to the user about what alternative
          functionality they can use.
      gone_in:
          The version of pip does this functionality should get removed in.
          Raises errors if pip's current version is greater than or equal to
          this.
      issue:
          Issue number on the tracker that would serve as a useful place for
          users to find related discussion and provide feedback.
  
      Always pass replacement, gone_in and issue as keyword arguments for clarity
      at the call site.