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

1from __future__ import annotations 

2 

3__lazy_modules__ = {"warnings"} 

4 

5import warnings 

6 

7from . import __version__ 

8 

9 

10def deprecate( 

11 deprecated: str, 

12 when: int | None, 

13 replacement: str | None = None, 

14 *, 

15 action: str | None = None, 

16 plural: bool = False, 

17 stacklevel: int = 3, 

18) -> None: 

19 """ 

20 Deprecations helper. 

21 

22 :param deprecated: Name of thing to be deprecated. 

23 :param when: Pillow major version to be removed in. 

24 :param replacement: Name of replacement. 

25 :param action: Instead of "replacement", give a custom call to action 

26 e.g. "Upgrade to new thing". 

27 :param plural: if the deprecated thing is plural, needing "are" instead of "is". 

28 

29 Usually of the form: 

30 

31 "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd). 

32 Use [replacement] instead." 

33 

34 You can leave out the replacement sentence: 

35 

36 "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd)" 

37 

38 Or with another call to action: 

39 

40 "[deprecated] is deprecated and will be removed in Pillow [when] (yyyy-mm-dd). 

41 [action]." 

42 """ 

43 

44 is_ = "are" if plural else "is" 

45 

46 if when is None: 

47 removed = "a future version" 

48 elif when <= int(__version__.split(".")[0]): 

49 msg = f"{deprecated} {is_} deprecated and should be removed." 

50 raise RuntimeError(msg) 

51 elif when == 14: 

52 removed = "Pillow 14 (2027-10-15)" 

53 elif when == 15: 

54 removed = "Pillow 15 (2028-10-15)" 

55 else: 

56 msg = f"Unknown removal version: {when}. Update {__name__}?" 

57 raise ValueError(msg) 

58 

59 if replacement and action: 

60 msg = "Use only one of 'replacement' and 'action'" 

61 raise ValueError(msg) 

62 

63 if replacement: 

64 action = f". Use {replacement} instead." 

65 elif action: 

66 action = f". {action.rstrip('.')}." 

67 else: 

68 action = "" 

69 

70 warnings.warn( 

71 f"{deprecated} {is_} deprecated and will be removed in {removed}{action}", 

72 DeprecationWarning, 

73 stacklevel=stacklevel, 

74 )