pip._internal.utils.deprecation Namespace Reference

Data Structures
class	PipDeprecationWarning

Functions
None	_showwarning (Union[Warning, str] message, Type[Warning] category, str filename, int lineno, Optional[TextIO] file=None, Optional[str] line=None)
None	install_warning_logger ()
None	deprecated (*str reason, Optional[str] replacement, Optional[str] gone_in, Optional[str] feature_flag=None, Optional[int] issue=None)

Variables
str	DEPRECATION_MSG_PREFIX = "DEPRECATION: "

Detailed Description

A module that implements tooling to enable easy warnings about deprecations.

Function Documentation

_showwarning()

None _showwarning ( Union[Warning, str]  message, Type[Warning]  category, str  filename, int  lineno, Optional[TextIO]   file = None, Optional[str]   line = None  )

protected

Definition at line 24 of file deprecation.py.

) -> None:
    if file is not None:
        if _original_showwarning is not None:
            _original_showwarning(message, category, filename, lineno, file, line)
    elif issubclass(category, PipDeprecationWarning):
        # We use a specially named logger which will handle all of the
        # deprecation messages for pip.
        logger = logging.getLogger("pip._internal.deprecations")
        logger.warning(message)
    else:
        _original_showwarning(message, category, filename, lineno, file, line)
 
 

References i.

deprecated()

None deprecated	(	*str	reason,
		Optional[str]	replacement,
		Optional[str]	gone_in,
		Optional[str]	feature_flag = None,
		Optional[int]	issue = None
	)

Helper to deprecate existing functionality.

reason:
    Textual reason shown to the user about why this functionality has
    been deprecated. Should be a complete sentence.
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 an error if pip's current version is greater than or equal to
    this.
feature_flag:
    Command-line flag of the form --use-feature={feature_flag} for testing
    upcoming functionality.
issue:
    Issue number on the tracker that would serve as a useful place for
    users to find related discussion and provide feedback.

Definition at line 55 of file deprecation.py.

) -> None:
    """Helper to deprecate existing functionality.
 
    reason:
        Textual reason shown to the user about why this functionality has
        been deprecated. Should be a complete sentence.
    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 an error if pip's current version is greater than or equal to
        this.
    feature_flag:
        Command-line flag of the form --use-feature={feature_flag} for testing
        upcoming functionality.
    issue:
        Issue number on the tracker that would serve as a useful place for
        users to find related discussion and provide feedback.
    """
 
    # Determine whether or not the feature is already gone in this version.
    is_gone = gone_in is not None and parse(current_version) >= parse(gone_in)
 
    message_parts = [
        (reason, f"{DEPRECATION_MSG_PREFIX}{{}}"),
        (
            gone_in,
            "pip {} will enforce this behaviour change."
            if not is_gone
            else "Since pip {}, this is no longer supported.",
        ),
        (
            replacement,
            "A possible replacement is {}.",
        ),
        (
            feature_flag,
            "You can use the flag --use-feature={} to test the upcoming behaviour."
            if not is_gone
            else None,
        ),
        (
            issue,
            "Discussion can be found at https://github.com/pypa/pip/issues/{}",
        ),
    ]
 
    message = " ".join(
        format_str.format(value)
        for value, format_str in message_parts
        if format_str is not None and value is not None
    )
 
    # Raise as an error if this behaviour is deprecated.
    if is_gone:
        raise PipDeprecationWarning(message)
 
    warnings.warn(message, category=PipDeprecationWarning, stacklevel=2)

References i.

install_warning_logger()

None install_warning_logger

(

)

Definition at line 44 of file deprecation.py.

def install_warning_logger() -> None:
    # Enable our Deprecation Warnings
    warnings.simplefilter("default", PipDeprecationWarning, append=True)
 
    global _original_showwarning
 
    if _original_showwarning is None:
        _original_showwarning = warnings.showwarning
        warnings.showwarning = _showwarning
 
 

References i.

Variable Documentation

DEPRECATION_MSG_PREFIX

str DEPRECATION_MSG_PREFIX = "DEPRECATION: "

Definition at line 13 of file deprecation.py.