2014-08-31 01:52:28 +02:00
|
|
|
"""
|
2016-06-10 21:27:07 +02:00
|
|
|
A module that implements tooling to enable easy warnings about deprecations.
|
2014-08-31 01:52:28 +02:00
|
|
|
"""
|
|
|
|
from __future__ import absolute_import
|
|
|
|
|
|
|
|
import logging
|
|
|
|
import warnings
|
2017-09-02 13:32:48 +02:00
|
|
|
|
2017-09-02 12:40:48 +02:00
|
|
|
from pip._internal.utils.typing import MYPY_CHECK_RUNNING
|
2014-08-31 01:52:28 +02:00
|
|
|
|
2017-06-16 09:32:31 +02:00
|
|
|
if MYPY_CHECK_RUNNING:
|
2018-06-22 06:00:17 +02:00
|
|
|
from typing import Any, Optional # noqa: F401
|
2017-06-15 21:51:33 +02:00
|
|
|
|
2014-08-31 01:52:28 +02:00
|
|
|
|
|
|
|
class PipDeprecationWarning(Warning):
|
|
|
|
pass
|
|
|
|
|
|
|
|
|
2018-06-22 04:46:41 +02:00
|
|
|
class PipPendingDeprecationWarning(PipDeprecationWarning):
|
2015-04-07 07:37:08 +02:00
|
|
|
pass
|
|
|
|
|
|
|
|
|
2018-06-22 06:01:34 +02:00
|
|
|
_original_showwarning = None # type: Any
|
2014-08-31 01:52:28 +02:00
|
|
|
|
|
|
|
|
2018-06-22 04:46:41 +02:00
|
|
|
# Warnings <-> Logging Integration
|
2014-08-31 01:52:28 +02:00
|
|
|
def _showwarning(message, category, filename, lineno, file=None, line=None):
|
|
|
|
if file is not None:
|
2018-06-22 06:01:34 +02:00
|
|
|
if _original_showwarning is not None:
|
|
|
|
_original_showwarning(
|
2014-08-31 01:52:28 +02:00
|
|
|
message, category, filename, lineno, file, line,
|
|
|
|
)
|
2018-06-22 04:46:41 +02:00
|
|
|
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")
|
|
|
|
|
|
|
|
# PipPendingDeprecationWarnings still have at least 2
|
|
|
|
# versions to go until they are removed so they can just be
|
|
|
|
# warnings. Otherwise, they will be removed in the very next
|
|
|
|
# version of pip. We want these to be more obvious so we use the
|
|
|
|
# ERROR logging level.
|
|
|
|
if issubclass(category, PipPendingDeprecationWarning):
|
|
|
|
logger.warning(log_message)
|
2014-08-31 01:52:28 +02:00
|
|
|
else:
|
2018-06-22 04:46:41 +02:00
|
|
|
logger.error(log_message)
|
|
|
|
else:
|
2018-06-22 06:01:34 +02:00
|
|
|
_original_showwarning(
|
2018-06-22 04:46:41 +02:00
|
|
|
message, category, filename, lineno, file, line,
|
|
|
|
)
|
2014-08-31 01:52:28 +02:00
|
|
|
|
|
|
|
|
|
|
|
def install_warning_logger():
|
2016-02-09 00:29:11 +01:00
|
|
|
# Enable our Deprecation Warnings
|
|
|
|
warnings.simplefilter("default", PipDeprecationWarning, append=True)
|
|
|
|
|
2018-06-22 06:01:34 +02:00
|
|
|
global _original_showwarning
|
2014-08-31 01:52:28 +02:00
|
|
|
|
2018-06-22 06:01:34 +02:00
|
|
|
if _original_showwarning is None:
|
|
|
|
_original_showwarning = warnings.showwarning
|
2014-08-31 01:52:28 +02:00
|
|
|
warnings.showwarning = _showwarning
|
2018-06-22 06:00:17 +02:00
|
|
|
|
|
|
|
|
|
|
|
def deprecated(reason, replacement, issue=None, imminent=False):
|
|
|
|
# type: (str, Optional[str], Optional[int], bool) -> None
|
|
|
|
if imminent:
|
|
|
|
category = PipDeprecationWarning
|
|
|
|
else:
|
|
|
|
category = PipPendingDeprecationWarning
|
|
|
|
|
|
|
|
# Construct a nice message.
|
2018-07-06 01:11:19 +02:00
|
|
|
# This is purposely eagerly formatted as we want it to appear as if someone
|
|
|
|
# typed this entire message out.
|
|
|
|
message = "DEPRECATION: " + reason
|
2018-06-22 06:00:17 +02:00
|
|
|
if replacement is not None:
|
|
|
|
message += " An alternative is to {}.".format(replacement)
|
|
|
|
if issue is not None:
|
|
|
|
url = "https://github.com/pypa/pip/issues/" + str(issue)
|
|
|
|
message += " You can find discussion regarding this at {}.".format(url)
|
|
|
|
|
|
|
|
warnings.warn(message, category=category, stacklevel=2)
|