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 8import os9import warnings10from datetime import date11from inspect import cleandoc12from textwrap import indent13from typing import Optional, Tuple14 15_DueDate = Tuple[int, int, int]  # time tuple16_INDENT = 8 * " "17_TEMPLATE = f"""{80 * '*'}\n{{details}}\n{80 * '*'}"""18 19 20class SetuptoolsWarning(UserWarning):21    """Base class in ``setuptools`` warning hierarchy."""22 23    @classmethod24    def emit(25        cls,26        summary: Optional[str] = None,27        details: Optional[str] = None,28        due_date: Optional[_DueDate] = None,29        see_docs: Optional[str] = None,30        see_url: Optional[str] = None,31        stacklevel: int = 2,32        **kwargs,33    ):34        """Private: reserved for ``setuptools`` internal use only"""35        # Default values:36        summary_ = summary or getattr(cls, "_SUMMARY", None) or ""37        details_ = details or getattr(cls, "_DETAILS", None) or ""38        due_date = due_date or getattr(cls, "_DUE_DATE", None)39        docs_ref = see_docs or getattr(cls, "_SEE_DOCS", None)40        docs_url = docs_ref and f"https://setuptools.pypa.io/en/latest/{docs_ref}"41        see_url = see_url or getattr(cls, "_SEE_URL", None)42        due = date(*due_date) if due_date else None43 44        text = cls._format(summary_, details_, due, see_url or docs_url, kwargs)45        if due and due < date.today() and _should_enforce():46            raise cls(text)47        warnings.warn(text, cls, stacklevel=stacklevel + 1)48 49    @classmethod50    def _format(51        cls,52        summary: str,53        details: str,54        due_date: Optional[date] = None,55        see_url: Optional[str] = None,56        format_args: Optional[dict] = None,57    ):58        """Private: reserved for ``setuptools`` internal use only"""59        today = date.today()60        summary = cleandoc(summary).format_map(format_args or {})61        possible_parts = [62            cleandoc(details).format_map(format_args or {}),63            (64                f"\nBy {due_date:%Y-%b-%d}, you need to update your project and remove "65                "deprecated calls\nor your builds will no longer be supported."66                if due_date and due_date > today67                else None68            ),69            (70                "\nThis deprecation is overdue, please update your project and remove "71                "deprecated\ncalls to avoid build errors in the future."72                if due_date and due_date < today73                else None74            ),75            (f"\nSee {see_url} for details." if see_url else None),76        ]77        parts = [x for x in possible_parts if x]78        if parts:79            body = indent(_TEMPLATE.format(details="\n".join(parts)), _INDENT)80            return "\n".join([summary, "!!\n", body, "\n!!"])81        return summary82 83 84class InformationOnly(SetuptoolsWarning):85    """Currently there is no clear way of displaying messages to the users86    that use the setuptools backend directly via ``pip``.87    The only thing that might work is a warning, although it is not the88    most appropriate tool for the job...89 90    See pypa/packaging-problems#558.91    """92 93 94class SetuptoolsDeprecationWarning(SetuptoolsWarning):95    """96    Base class for warning deprecations in ``setuptools``97 98    This class is not derived from ``DeprecationWarning``, and as such is99    visible by default.100    """101 102 103def _should_enforce():104    enforce = os.getenv("SETUPTOOLS_ENFORCE_DEPRECATION", "false").lower()105    return enforce in ("true", "on", "ok", "1")106