Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3import warnings
5from . import __version__
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) -> None:
16 """
17 Deprecations helper.
19 :param deprecated: Name of thing to be deprecated.
20 :param when: Pillow major version to be removed in.
21 :param replacement: Name of replacement.
22 :param action: Instead of "replacement", give a custom call to action
23 e.g. "Upgrade to new thing".
24 :param plural: if the deprecated thing is plural, needing "are" instead of "is".
26 Usually of the form:
28 "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd).
29 Use [replacement] instead."
31 You can leave out the replacement sentence:
33 "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd)"
35 Or with another call to action:
37 "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd).
38 [action]."
39 """
41 is_ = "are" if plural else "is"
43 if when is None:
44 removed = "a future version"
45 elif when <= int(__version__.split(".")[0]):
46 msg = f"{deprecated} {is_} deprecated and should be removed."
47 raise RuntimeError(msg)
48 elif when == 12:
49 removed = "Pillow 12 (2025-10-15)"
50 else:
51 msg = f"Unknown removal version: {when}. Update {__name__}?"
52 raise ValueError(msg)
54 if replacement and action:
55 msg = "Use only one of 'replacement' and 'action'"
56 raise ValueError(msg)
58 if replacement:
59 action = f". Use {replacement} instead."
60 elif action:
61 action = f". {action.rstrip('.')}."
62 else:
63 action = ""
65 warnings.warn(
66 f"{deprecated} {is_} deprecated and will be removed in {removed}{action}",
67 DeprecationWarning,
68 stacklevel=3,
69 )