codekingpro/portable-devtools

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