Mercurial > repos > guerler > hhblits

comparison lib/python3.8/site-packages/pip/_internal/utils/deprecation.py @ 0:9e54283cc701 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit d12c32a45bcd441307e632fca6d9af7d60289d44"
author guerler
date Mon, 27 Jul 2020 03:47:31 -0400
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:9e54283cc701
1 """
2 A module that implements tooling to enable easy warnings about deprecations.
3 """
4
5 # The following comment should be removed at some point in the future.
6 # mypy: disallow-untyped-defs=False
7
8 from __future__ import absolute_import
9
10 import logging
11 import warnings
12
13 from pip._vendor.packaging.version import parse
14
15 from pip import __version__ as current_version
16 from pip._internal.utils.typing import MYPY_CHECK_RUNNING
17
18 if MYPY_CHECK_RUNNING:
19 from typing import Any, Optional
20
21
22 DEPRECATION_MSG_PREFIX = "DEPRECATION: "
23
24
25 class PipDeprecationWarning(Warning):
26 pass
27
28
29 _original_showwarning = None # type: Any
30
31
32 # Warnings <-> Logging Integration
33 def _showwarning(message, category, filename, lineno, file=None, line=None):
34 if file is not None:
35 if _original_showwarning is not None:
36 _original_showwarning(
37 message, category, filename, lineno, file, line,
38 )
39 elif issubclass(category, PipDeprecationWarning):
40 # We use a specially named logger which will handle all of the
41 # deprecation messages for pip.
42 logger = logging.getLogger("pip._internal.deprecations")
43 logger.warning(message)
44 else:
45 _original_showwarning(
46 message, category, filename, lineno, file, line,
47 )
48
49
50 def install_warning_logger():
51 # type: () -> None
52 # Enable our Deprecation Warnings
53 warnings.simplefilter("default", PipDeprecationWarning, append=True)
54
55 global _original_showwarning
56
57 if _original_showwarning is None:
58 _original_showwarning = warnings.showwarning
59 warnings.showwarning = _showwarning
60
61
62 def deprecated(reason, replacement, gone_in, issue=None):
63 # type: (str, Optional[str], Optional[str], Optional[int]) -> None
64 """Helper to deprecate existing functionality.
65
66 reason:
67 Textual reason shown to the user about why this functionality has
68 been deprecated.
69 replacement:
70 Textual suggestion shown to the user about what alternative
71 functionality they can use.
72 gone_in:
73 The version of pip does this functionality should get removed in.
74 Raises errors if pip's current version is greater than or equal to
75 this.
76 issue:
77 Issue number on the tracker that would serve as a useful place for
78 users to find related discussion and provide feedback.
79
80 Always pass replacement, gone_in and issue as keyword arguments for clarity
81 at the call site.
82 """
83
84 # Construct a nice message.
85 # This is eagerly formatted as we want it to get logged as if someone
86 # typed this entire message out.
87 sentences = [
88 (reason, DEPRECATION_MSG_PREFIX + "{}"),
89 (gone_in, "pip {} will remove support for this functionality."),
90 (replacement, "A possible replacement is {}."),
91 (issue, (
92 "You can find discussion regarding this at "
93 "https://github.com/pypa/pip/issues/{}."
94 )),
95 ]
96 message = " ".join(
97 template.format(val) for val, template in sentences if val is not None
98 )
99
100 # Raise as an error if it has to be removed.
101 if gone_in is not None and parse(current_version) >= parse(gone_in):
102 raise PipDeprecationWarning(message)
103
104 warnings.warn(message, category=PipDeprecationWarning, stacklevel=2)