def warn_or_error(removal_version, deprecated_entity_description, hint=None,
                  deprecation_start_version=None,
                  stacklevel=3, frame_info=None, context=1, ensure_stderr=False):
  """Check the removal_version against the current pants version.

  Issues a warning if the removal version is > current pants version, or an error otherwise.

  :param string removal_version: The pantsbuild.pants version at which the deprecated entity
                                 will be/was removed.
  :param string deprecated_entity_description: A short description of the deprecated entity, that
                                            we can embed in warning/error messages.
  :param string hint: A message describing how to migrate from the removed entity.
  :param string deprecation_start_version: The pantsbuild.pants version at which the entity will
                                           begin to display a deprecation warning. This must be less
                                           than the `removal_version`. If not provided, the
                                           deprecation warning is always displayed.
  :param int stacklevel: The stacklevel to pass to warnings.warn.
  :param FrameInfo frame_info: If provided, use this frame info instead of getting one from
                               `stacklevel`.
  :param int context: The number of lines of source code surrounding the selected frame to display
                      in a warning message.
  :param bool ensure_stderr: Whether use warnings.warn, or use warnings.showwarning to print
                             directly to stderr.
  :raises DeprecationApplicationError: if the removal_version parameter is invalid.
  :raises CodeRemovedError: if the current version is later than the version marked for removal.
  """
  removal_semver = validate_deprecation_semver(removal_version, 'removal version')
  if deprecation_start_version:
    deprecation_start_semver = validate_deprecation_semver(
      deprecation_start_version, 'deprecation start version')
    if deprecation_start_semver >= removal_semver:
      raise InvalidSemanticVersionOrderingError(
        'The deprecation start version {} must be less than the end version {}.'
        .format(deprecation_start_version, removal_version))
    elif PANTS_SEMVER < deprecation_start_semver:
      return

  msg = 'DEPRECATED: {} {} removed in version {}.'.format(deprecated_entity_description,
      get_deprecated_tense(removal_version), removal_version)
  if hint:
    msg += '\n  {}'.format(hint)

  # We need to have filename and line_number for warnings.formatwarning, which appears to be the only
  # way to get a warning message to display to stderr. We get that from frame_info -- it's too bad
  # we have to reconstruct the `stacklevel` logic ourselves, but we do also gain the ability to have
  # multiple lines of context, which is neat.
  if frame_info is None:
    frame_info = _get_frame_info(stacklevel, context=context)
  _, filename, line_number, _, code_context, _ = frame_info
  if code_context:
    context_lines = ''.join(code_context)
  else:
    context_lines = '<no code context available>'

  if removal_semver > PANTS_SEMVER:
    if ensure_stderr:
      # No warning filters can stop us from printing this message directly to stderr.
      warning_msg = warnings.formatwarning(
        msg, DeprecationWarning, filename, line_number, line=context_lines)
      print(warning_msg, file=sys.stderr)
    else:
      # This output is filtered by warning filters.
      with _greater_warnings_context(context_lines):
        warnings.warn_explicit(
          message=DeprecationWarning(msg) if PY2 else msg,
          category=DeprecationWarning,
          filename=filename,
          lineno=line_number)
    return msg
  else:
    raise CodeRemovedError(msg)
Check the removal_version against the current pants version.

  Issues a warning if the removal version is > current pants version, or an error otherwise.

  :param string removal_version: The pantsbuild.pants version at which the deprecated entity
                                 will be/was removed.
  :param string deprecated_entity_description: A short description of the deprecated entity, that
                                            we can embed in warning/error messages.
  :param string hint: A message describing how to migrate from the removed entity.
  :param string deprecation_start_version: The pantsbuild.pants version at which the entity will
                                           begin to display a deprecation warning. This must be less
                                           than the `removal_version`. If not provided, the
                                           deprecation warning is always displayed.
  :param int stacklevel: The stacklevel to pass to warnings.warn.
  :param FrameInfo frame_info: If provided, use this frame info instead of getting one from
                               `stacklevel`.
  :param int context: The number of lines of source code surrounding the selected frame to display
                      in a warning message.
  :param bool ensure_stderr: Whether use warnings.warn, or use warnings.showwarning to print
                             directly to stderr.
  :raises DeprecationApplicationError: if the removal_version parameter is invalid.
  :raises CodeRemovedError: if the current version is later than the version marked for removal.