|
jpayne@69
|
1 """Provide basic warnings used by setuptools modules.
|
|
jpayne@69
|
2
|
|
jpayne@69
|
3 Using custom classes (other than ``UserWarning``) allow users to set
|
|
jpayne@69
|
4 ``PYTHONWARNINGS`` filters to run tests and prepare for upcoming changes in
|
|
jpayne@69
|
5 setuptools.
|
|
jpayne@69
|
6 """
|
|
jpayne@69
|
7
|
|
jpayne@69
|
8 from __future__ import annotations
|
|
jpayne@69
|
9
|
|
jpayne@69
|
10 import os
|
|
jpayne@69
|
11 import warnings
|
|
jpayne@69
|
12 from datetime import date
|
|
jpayne@69
|
13 from inspect import cleandoc
|
|
jpayne@69
|
14 from textwrap import indent
|
|
jpayne@69
|
15 from typing import TYPE_CHECKING, Tuple
|
|
jpayne@69
|
16
|
|
jpayne@69
|
17 if TYPE_CHECKING:
|
|
jpayne@69
|
18 from typing_extensions import TypeAlias
|
|
jpayne@69
|
19
|
|
jpayne@69
|
20 _DueDate: TypeAlias = Tuple[int, int, int] # time tuple
|
|
jpayne@69
|
21 _INDENT = 8 * " "
|
|
jpayne@69
|
22 _TEMPLATE = f"""{80 * '*'}\n{{details}}\n{80 * '*'}"""
|
|
jpayne@69
|
23
|
|
jpayne@69
|
24
|
|
jpayne@69
|
25 class SetuptoolsWarning(UserWarning):
|
|
jpayne@69
|
26 """Base class in ``setuptools`` warning hierarchy."""
|
|
jpayne@69
|
27
|
|
jpayne@69
|
28 @classmethod
|
|
jpayne@69
|
29 def emit(
|
|
jpayne@69
|
30 cls,
|
|
jpayne@69
|
31 summary: str | None = None,
|
|
jpayne@69
|
32 details: str | None = None,
|
|
jpayne@69
|
33 due_date: _DueDate | None = None,
|
|
jpayne@69
|
34 see_docs: str | None = None,
|
|
jpayne@69
|
35 see_url: str | None = None,
|
|
jpayne@69
|
36 stacklevel: int = 2,
|
|
jpayne@69
|
37 **kwargs,
|
|
jpayne@69
|
38 ) -> None:
|
|
jpayne@69
|
39 """Private: reserved for ``setuptools`` internal use only"""
|
|
jpayne@69
|
40 # Default values:
|
|
jpayne@69
|
41 summary_ = summary or getattr(cls, "_SUMMARY", None) or ""
|
|
jpayne@69
|
42 details_ = details or getattr(cls, "_DETAILS", None) or ""
|
|
jpayne@69
|
43 due_date = due_date or getattr(cls, "_DUE_DATE", None)
|
|
jpayne@69
|
44 docs_ref = see_docs or getattr(cls, "_SEE_DOCS", None)
|
|
jpayne@69
|
45 docs_url = docs_ref and f"https://setuptools.pypa.io/en/latest/{docs_ref}"
|
|
jpayne@69
|
46 see_url = see_url or getattr(cls, "_SEE_URL", None)
|
|
jpayne@69
|
47 due = date(*due_date) if due_date else None
|
|
jpayne@69
|
48
|
|
jpayne@69
|
49 text = cls._format(summary_, details_, due, see_url or docs_url, kwargs)
|
|
jpayne@69
|
50 if due and due < date.today() and _should_enforce():
|
|
jpayne@69
|
51 raise cls(text)
|
|
jpayne@69
|
52 warnings.warn(text, cls, stacklevel=stacklevel + 1)
|
|
jpayne@69
|
53
|
|
jpayne@69
|
54 @classmethod
|
|
jpayne@69
|
55 def _format(
|
|
jpayne@69
|
56 cls,
|
|
jpayne@69
|
57 summary: str,
|
|
jpayne@69
|
58 details: str,
|
|
jpayne@69
|
59 due_date: date | None = None,
|
|
jpayne@69
|
60 see_url: str | None = None,
|
|
jpayne@69
|
61 format_args: dict | None = None,
|
|
jpayne@69
|
62 ) -> str:
|
|
jpayne@69
|
63 """Private: reserved for ``setuptools`` internal use only"""
|
|
jpayne@69
|
64 today = date.today()
|
|
jpayne@69
|
65 summary = cleandoc(summary).format_map(format_args or {})
|
|
jpayne@69
|
66 possible_parts = [
|
|
jpayne@69
|
67 cleandoc(details).format_map(format_args or {}),
|
|
jpayne@69
|
68 (
|
|
jpayne@69
|
69 f"\nBy {due_date:%Y-%b-%d}, you need to update your project and remove "
|
|
jpayne@69
|
70 "deprecated calls\nor your builds will no longer be supported."
|
|
jpayne@69
|
71 if due_date and due_date > today
|
|
jpayne@69
|
72 else None
|
|
jpayne@69
|
73 ),
|
|
jpayne@69
|
74 (
|
|
jpayne@69
|
75 "\nThis deprecation is overdue, please update your project and remove "
|
|
jpayne@69
|
76 "deprecated\ncalls to avoid build errors in the future."
|
|
jpayne@69
|
77 if due_date and due_date < today
|
|
jpayne@69
|
78 else None
|
|
jpayne@69
|
79 ),
|
|
jpayne@69
|
80 (f"\nSee {see_url} for details." if see_url else None),
|
|
jpayne@69
|
81 ]
|
|
jpayne@69
|
82 parts = [x for x in possible_parts if x]
|
|
jpayne@69
|
83 if parts:
|
|
jpayne@69
|
84 body = indent(_TEMPLATE.format(details="\n".join(parts)), _INDENT)
|
|
jpayne@69
|
85 return "\n".join([summary, "!!\n", body, "\n!!"])
|
|
jpayne@69
|
86 return summary
|
|
jpayne@69
|
87
|
|
jpayne@69
|
88
|
|
jpayne@69
|
89 class InformationOnly(SetuptoolsWarning):
|
|
jpayne@69
|
90 """Currently there is no clear way of displaying messages to the users
|
|
jpayne@69
|
91 that use the setuptools backend directly via ``pip``.
|
|
jpayne@69
|
92 The only thing that might work is a warning, although it is not the
|
|
jpayne@69
|
93 most appropriate tool for the job...
|
|
jpayne@69
|
94
|
|
jpayne@69
|
95 See pypa/packaging-problems#558.
|
|
jpayne@69
|
96 """
|
|
jpayne@69
|
97
|
|
jpayne@69
|
98
|
|
jpayne@69
|
99 class SetuptoolsDeprecationWarning(SetuptoolsWarning):
|
|
jpayne@69
|
100 """
|
|
jpayne@69
|
101 Base class for warning deprecations in ``setuptools``
|
|
jpayne@69
|
102
|
|
jpayne@69
|
103 This class is not derived from ``DeprecationWarning``, and as such is
|
|
jpayne@69
|
104 visible by default.
|
|
jpayne@69
|
105 """
|
|
jpayne@69
|
106
|
|
jpayne@69
|
107
|
|
jpayne@69
|
108 def _should_enforce():
|
|
jpayne@69
|
109 enforce = os.getenv("SETUPTOOLS_ENFORCE_DEPRECATION", "false").lower()
|
|
jpayne@69
|
110 return enforce in ("true", "on", "ok", "1")
|
