Coverage for sources/accretive/exceptions.py: 100%

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

6# Licensed under the Apache License, Version 2.0 (the "License"); # 

7# you may not use this file except in compliance with the License. # 

8# You may obtain a copy of the License at # 

9# # 

10# http://www.apache.org/licenses/LICENSE-2.0 # 

11# # 

12# Unless required by applicable law or agreed to in writing, software # 

13# distributed under the License is distributed on an "AS IS" BASIS, # 

14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

15# See the License for the specific language governing permissions and # 

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Family of exceptions for package API. 

22 

23Provides a hierarchy of exceptions that are raised when accretive behavior is 

24violated. The hierarchy is designed to allow both specific and general 

25exception handling. 

26 

27* ``Omniexception``: Base for all package exceptions 

28* ``Omnierror``: Base for all package errors 

29 

30* ``AttributeImmutabilityError``: Raised for attribute modification 

31* ``EntryImmutabilityError``: Raised for dictionary entry modification 

32* ``EntryValidityError``: Raised for invalid dictionary entries 

33* ``OperationValidityError``: Raised for invalid operations 

34 

35.. note:: 

36 

37 Some exception names from earlier versions are maintained as aliases for 

38 backward compatibility but are deprecated. 

39''' 

40 

41 

42from . import __ # pylint: disable=cyclic-import 

43 

44 

45class Omniexception( __.InternalObject, BaseException ): 

46 ''' Base for all exceptions raised by package API. ''' 

47 

48 _attribute_visibility_includes_: __.cabc.Collection[ str ] = ( 

49 frozenset( ( '__cause__', '__context__', ) ) ) 

50 

51 

52class Omnierror( Omniexception, Exception ): 

53 ''' Base for error exceptions raised by package API. ''' 

54 

55 

56class AttributeImmutabilityError( Omnierror, AttributeError, TypeError ): 

57 ''' Attempt to reassign or delete immutable attribute. ''' 

58 

59 def __init__( self, name: str ) -> None: 

60 super( ).__init__( f"Cannot reassign or delete attribute {name!r}." ) 

61 

62 

63class EntryImmutabilityError( Omnierror, TypeError ): 

64 ''' Attempt to update or remove immutable dictionary entry. ''' 

65 

66 def __init__( self, indicator: __.cabc.Hashable ) -> None: 

67 super( ).__init__( 

68 f"Cannot alter or remove existing entry for {indicator!r}." ) 

69 

70 

71class EntryValidityError( Omnierror, ValueError ): 

72 ''' Attempt to add invalid entry to dictionary. ''' 

73 

74 def __init__( self, indicator: __.cabc.Hashable, value: __.a.Any ) -> None: 

75 super( ).__init__( 

76 f"Cannot add invalid entry with key, {indicator!r}, " 

77 f"and value, {value!r}, to dictionary." ) 

78 

79 

80class OperationValidityError( Omnierror, RuntimeError, TypeError ): 

81 ''' Attempt to perform invalid operation. ''' 

82 

83 def __init__( self, name: str ) -> None: 

84 super( ).__init__( f"Operation {name!r} is not valid on this object." ) 

85 

86 

87## BEGIN: Deprecated Exceptions 

88# TODO: release 3.0: Remove. 

89 

90 

91class EntryValidationError( EntryValidityError ): 

92 ''' Attempt to add invalid entry to dictionary. 

93 

94 .. deprecated:: 2.1 

95 Please use :py:exc:`EntryValidityError` instead. 

96 ''' 

97 

98 

99class IndelibleAttributeError( AttributeImmutabilityError ): 

100 ''' Attempt to reassign or delete indelible attribute. 

101 

102 .. deprecated:: 2.1 

103 Please use :py:exc:`AttributeImmutabilityError` instead. 

104 ''' 

105 

106 

107class IndelibleEntryError( EntryImmutabilityError ): 

108 ''' Attempt to update or remove indelible dictionary entry. 

109 

110 .. deprecated:: 2.1 

111 Please use :py:exc:`EntryImmutabilityError` instead. 

112 ''' 

113 

114 def __init__( self, indicator: __.a.Any ) -> None: 

115 super( ).__init__( indicator ) 

116 

117 

118class InvalidOperationError( OperationValidityError ): 

119 ''' Attempt to perform invalid operation. 

120 

121 .. deprecated:: 2.1 

122 Please use :py:exc:`OperationValidityError` instead. 

123 '''