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

1"""Helper functions for deprecation. 

2 

3This interface is itself unstable and may change without warning. Do 

4not use these functions yourself, even as a joke. The underscores are 

5there for a reason. No support will be given. 

6 

7In particular, most of this will go away without warning once 

8Beautiful Soup drops support for Python 3.11, since Python 3.12 

9defines a `@typing.deprecated() 

10decorator. <https://peps.python.org/pep-0702/>`_ 

11""" 

12 

13import functools 

14import warnings 

15 

16from typing import ( 

17 Any, 

18 Callable, 

19) 

20 

21 

22def _deprecated_alias(old_name: str, new_name: str, version: str): 

23 """Alias one attribute name to another for backward compatibility 

24 

25 :meta private: 

26 """ 

27 

28 @property # type:ignore 

29 def alias(self) -> Any: 

30 ":meta private:" 

31 warnings.warn( 

32 f"Access to deprecated property {old_name}. (Replaced by {new_name}) -- Deprecated since version {version}.", 

33 DeprecationWarning, 

34 stacklevel=2, 

35 ) 

36 return getattr(self, new_name) 

37 

38 @alias.setter 

39 def alias(self, value: str) -> None: 

40 ":meta private:" 

41 warnings.warn( 

42 f"Write to deprecated property {old_name}. (Replaced by {new_name}) -- Deprecated since version {version}.", 

43 DeprecationWarning, 

44 stacklevel=2, 

45 ) 

46 return setattr(self, new_name, value) 

47 

48 return alias 

49 

50_UPDATE_NOW:str = "\nYou must update this call before the next Beautiful Soup release, or your code will silently change its behavior." 

51 

52def _deprecated_function_alias( 

53 old_name: str, new_name: str, version: str, eol:bool=False 

54) -> Callable[[Any], Any]: 

55 def alias(self, *args: Any, **kwargs: Any) -> Any: 

56 ":meta private:" 

57 

58 message = f"Call to deprecated method {old_name}. (Replaced by {new_name}) -- Deprecated since version {version}." 

59 if eol: 

60 message += _UPDATE_NOW 

61 raise NotImplementedError(message) 

62 warnings.warn( 

63 message, 

64 DeprecationWarning, 

65 stacklevel=2, 

66 ) 

67 return getattr(self, new_name)(*args, **kwargs) 

68 

69 return alias 

70 

71 

72def _deprecated(replaced_by: str, version: str, eol:bool=False) -> Callable: 

73 def deprecate(func: Callable) -> Callable: 

74 @functools.wraps(func) 

75 def with_warning(*args: Any, **kwargs: Any) -> Any: 

76 ":meta private:" 

77 message = f"Call to deprecated method {func.__name__}. (Replaced by {replaced_by}) -- Deprecated since version {version}." 

78 if eol: 

79 message += _UPDATE_NOW 

80 raise NotImplementedError(message) 

81 warnings.warn( 

82 message, 

83 DeprecationWarning, 

84 stacklevel=2, 

85 ) 

86 return func(*args, **kwargs) 

87 

88 return with_warning 

89 

90 return deprecate