deprecation.py

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

from __future__ import annotations

import logging
import warnings
from typing import Any, TextIO

from pip._vendor.packaging.version import parse

from pip import __version__ as current_version  # NOTE: tests patch this name.

DEPRECATION_MSG_PREFIX = "DEPRECATION: "

class PipDeprecationWarning(Warning):
    include_source: bool = False

_original_showwarning: Any = None

# Warnings <-> Logging Integration
def _showwarning(
    message: Warning | str,
    category: type[Warning],
    filename: str,
    lineno: int,
    file: TextIO | None = None,
    line: str | None = None,
) -> 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")
        if isinstance(message, PipDeprecationWarning) and message.include_source:
            logger.warning("%s (%s:%s)", message, filename, lineno)
        else:
            logger.warning(message)
    else:
        _original_showwarning(message, category, filename, lineno, file, line)

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

def deprecated(
    *,
    reason: str,
    replacement: str | None,
    gone_in: str | None,
    feature_flag: str | None = None,
    issue: int | None = None,
    stacklevel: int = 2,
    include_source: bool = False,
) -> 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.
    stacklevel:
        How many frames up the call stack to attribute the warning to.
        Defaults to 2 (the caller of deprecated()).
    include_source:
        If True, include the source filename and line number in the warning
        output. Useful when the warning originates from external code.
    """

# 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)

warning = PipDeprecationWarning(message)
    warning.include_source = include_source
    warnings.warn(warning, stacklevel=stacklevel)

docroot: /home/induvedam/public_html

curdir: /opt/imunify360/venv/lib/python3.11/site-packages/pip/_internal/utils

	.	4096
	..	4096
X	__init__.py	0
	__pycache__	4096
X	_jaraco_text.py	3350
X	_log.py	1015
X	appdirs.py	1681
X	compat.py	2514
X	compatibility_tags.py	6630
X	datetime.py	868
X	deprecation.py	4319
X	direct_url_helpers.py	3363
X	egg_link.py	2459
X	entrypoints.py	3324
X	filesystem.py	6812
X	filetypes.py	689
X	glibc.py	3726
X	hashes.py	5040
X	logging.py	13414
X	misc.py	23704
X	packaging.py	1601
X	pylock.py	9358
X	retry.py	1461
X	subprocess.py	8983
X	temp_dir.py	9307
X	unpacking.py	13584
X	urls.py	1601
X	virtualenv.py	3455
X	wheel.py	4468