codekingpro/portable-devtools

1from __future__ import annotations
2
3import warnings
4
5from . import __version__
6
7
8def deprecate(
9    deprecated: str,
10    when: int | None,
11    replacement: str | None = None,
12    *,
13    action: str | None = None,
14    plural: bool = False,
15    stacklevel: int = 3,
16) -> None:
17    """
18    Deprecations helper.
19
20    :param deprecated: Name of thing to be deprecated.
21    :param when: Pillow major version to be removed in.
22    :param replacement: Name of replacement.
23    :param action: Instead of "replacement", give a custom call to action
24        e.g. "Upgrade to new thing".
25    :param plural: if the deprecated thing is plural, needing "are" instead of "is".
26
27    Usually of the form:
28
29        "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd).
30        Use [replacement] instead."
31
32    You can leave out the replacement sentence:
33
34        "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd)"
35
36    Or with another call to action:
37
38        "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd).
39        [action]."
40    """
41
42    is_ = "are" if plural else "is"
43
44    if when is None:
45        removed = "a future version"
46    elif when <= int(__version__.split(".")[0]):
47        msg = f"{deprecated} {is_} deprecated and should be removed."
48        raise RuntimeError(msg)
49    elif when == 13:
50        removed = "Pillow 13 (2026-10-15)"
51    elif when == 14:
52        removed = "Pillow 14 (2027-10-15)"
53    else:
54        msg = f"Unknown removal version: {when}. Update {__name__}?"
55        raise ValueError(msg)
56
57    if replacement and action:
58        msg = "Use only one of 'replacement' and 'action'"
59        raise ValueError(msg)
60
61    if replacement:
62        action = f". Use {replacement} instead."
63    elif action:
64        action = f". {action.rstrip('.')}."
65    else:
66        action = ""
67
68    warnings.warn(
69        f"{deprecated} {is_} deprecated and will be removed in {removed}{action}",
70        DeprecationWarning,
71        stacklevel=stacklevel,
72    )
73