Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/PIL/_deprecate.py: 56%

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 == 12: 

50 removed = "Pillow 12 (2025-10-15)" 

51 elif when == 13: 

52 removed = "Pillow 13 (2026-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 )