"""Provide basic warnings used by setuptools modules. Using custom classes (other than ``UserWarning``) allow users to set ``PYTHONWARNINGS`` filters to run tests and prepare for upcoming changes in setuptools. """ import os import warnings from datetime import date from inspect import cleandoc from textwrap import indent from typing import Optional, Tuple _DueDate = Tuple[int, int, int] # time tuple _INDENT = 8 * " " _TEMPLATE = f"""{80 * '*'}\n{{details}}\n{80 * '*'}""" class SetuptoolsWarning(UserWarning): """Base class in ``setuptools`` warning hierarchy.""" @classmethod def emit( cls, summary: Optional[str] = None, details: Optional[str] = None, due_date: Optional[_DueDate] = None, see_docs: Optional[str] = None, see_url: Optional[str] = None, stacklevel: int = 2, **kwargs, ): """Private: reserved for ``setuptools`` internal use only""" # Default values: summary_ = summary or getattr(cls, "_SUMMARY", None) or "" details_ = details or getattr(cls, "_DETAILS", None) or "" due_date = due_date or getattr(cls, "_DUE_DATE", None) docs_ref = see_docs or getattr(cls, "_SEE_DOCS", None) docs_url = docs_ref and f"https://setuptools.pypa.io/en/latest/{docs_ref}" see_url = see_url or getattr(cls, "_SEE_URL", None) due = date(*due_date) if due_date else None text = cls._format(summary_, details_, due, see_url or docs_url, kwargs) if due and due < date.today() and _should_enforce(): raise cls(text) warnings.warn(text, cls, stacklevel=stacklevel + 1) @classmethod def _format( cls, summary: str, details: str, due_date: Optional[date] = None, see_url: Optional[str] = None, format_args: Optional[dict] = None, ): """Private: reserved for ``setuptools`` internal use only""" today = date.today() summary = cleandoc(summary).format_map(format_args or {}) possible_parts = [ cleandoc(details).format_map(format_args or {}), ( f"\nBy {due_date:%Y-%b-%d}, you need to update your project and remove " "deprecated calls\nor your builds will no longer be supported." if due_date and due_date > today else None ), ( "\nThis deprecation is overdue, please update your project and remove " "deprecated\ncalls to avoid build errors in the future." if due_date and due_date < today else None ), (f"\nSee {see_url} for details." if see_url else None), ] parts = [x for x in possible_parts if x] if parts: body = indent(_TEMPLATE.format(details="\n".join(parts)), _INDENT) return "\n".join([summary, "!!\n", body, "\n!!"]) return summary class InformationOnly(SetuptoolsWarning): """Currently there is no clear way of displaying messages to the users that use the setuptools backend directly via ``pip``. The only thing that might work is a warning, although it is not the most appropriate tool for the job... See pypa/packaging-problems#558. """ class SetuptoolsDeprecationWarning(SetuptoolsWarning): """ Base class for warning deprecations in ``setuptools`` This class is not derived from ``DeprecationWarning``, and as such is visible by default. """ def _should_enforce(): enforce = os.getenv("SETUPTOOLS_ENFORCE_DEPRECATION", "false").lower() return enforce in ("true", "on", "ok", "1")