Mercurial > repos > guerler > springsuite

comparison planemo/lib/python3.7/site-packages/pip/_internal/utils/deprecation.py @ 1:56ad4e20f292 draft

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