Coverage for sources/frigid/classes.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''' Immutable classes. ''' 

22 

23# ruff: noqa: F811 

24 

25 

26from . import __ 

27 

28 

29is_public_identifier = __.is_public_identifier 

30mutables_default = ( ) 

31visibles_default = ( is_public_identifier, ) 

32 

33 

34def _provide_error_class( name: str ) -> type[ Exception ]: 

35 ''' Provides error class for this package. ''' 

36 match name: 

37 case 'AttributeImmutability': 

38 from .exceptions import AttributeImmutability as error 

39 case _: 

40 from .exceptions import ErrorProvideFailure 

41 raise ErrorProvideFailure( name, reason = 'Does not exist.' ) 

42 return error 

43 

44 

45_dataclass_core = __.dcls.dataclass( kw_only = True, slots = True ) 

46_dynadoc_configuration = ( 

47 __.ccstd.dynadoc.produce_dynadoc_configuration( 

48 introspection = __.dynadoc_introspection_control_on_class, 

49 table = __.fragments ) ) 

50_class_factory = __.funct.partial( 

51 __.ccstd.class_factory, 

52 attributes_namer = __.calculate_attrname, 

53 dynadoc_configuration = _dynadoc_configuration, 

54 error_class_provider = _provide_error_class ) 

55 

56 

57@_class_factory( ) 

58class Class( type ): 

59 ''' Metaclass for standard classes. ''' 

60 

61 _dynadoc_fragments_ = ( 

62 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

63 'cfc instance conceal', 'cfc instance protect' ) 

64 

65 def __new__( # Typechecker stub. 

66 clscls: type[ __.T ], 

67 name: str, 

68 bases: tuple[ type, ... ], 

69 namespace: dict[ str, __.typx.Any ], *, 

70 decorators: __.ClassDecorators[ __.T ] = ( ), 

71 **arguments: __.typx.Unpack[ __.ccstd.ClassFactoryExtraArguments ], 

72 ) -> __.T: 

73 return super( ).__new__( clscls, name, bases, namespace ) 

74 

75 

76@_class_factory( ) 

77@__.typx.dataclass_transform( frozen_default = True, kw_only_default = True ) 

78class Dataclass( type ): 

79 ''' Metaclass for standard dataclasses. ''' 

80 

81 _dynadoc_fragments_ = ( 

82 'cfc produce dataclass', 

83 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

84 'cfc instance conceal', 'cfc instance protect' ) 

85 

86 def __new__( # Typechecker stub. 

87 clscls: type[ __.T ], 

88 name: str, 

89 bases: tuple[ type, ... ], 

90 namespace: dict[ str, __.typx.Any ], *, 

91 decorators: __.ClassDecorators[ __.T ] = ( ), 

92 **arguments: __.typx.Unpack[ __.ccstd.ClassFactoryExtraArguments ], 

93 ) -> __.T: 

94 return super( ).__new__( clscls, name, bases, namespace ) 

95 

96 

97@_class_factory( ) 

98@__.typx.dataclass_transform( kw_only_default = True ) 

99class DataclassMutable( type ): 

100 ''' Metaclass for dataclasses with mutable instances. ''' 

101 

102 _dynadoc_fragments_ = ( 

103 'cfc produce dataclass', 

104 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

105 'cfc instance conceal' ) 

106 

107 def __new__( # Typechecker stub. 

108 clscls: type[ __.T ], 

109 name: str, 

110 bases: tuple[ type, ... ], 

111 namespace: dict[ str, __.typx.Any ], *, 

112 decorators: __.ClassDecorators[ __.T ] = ( ), 

113 **arguments: __.typx.Unpack[ __.ccstd.ClassFactoryExtraArguments ], 

114 ) -> __.T: 

115 return super( ).__new__( clscls, name, bases, namespace ) 

116 

117 

118@_class_factory( ) 

119class AbstractBaseClass( __.abc.ABCMeta ): 

120 ''' Metaclass for standard abstract base classes. ''' 

121 

122 _dynadoc_fragments_ = ( 

123 'cfc produce abstract base class', 

124 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

125 'cfc instance conceal', 'cfc instance protect' ) 

126 

127 def __new__( # Typechecker stub. 

128 clscls: type[ __.T ], 

129 name: str, 

130 bases: tuple[ type, ... ], 

131 namespace: dict[ str, __.typx.Any ], *, 

132 decorators: __.ClassDecorators[ __.T ] = ( ), 

133 **arguments: __.typx.Unpack[ __.ccstd.ClassFactoryExtraArguments ], 

134 ) -> __.T: 

135 return super( ).__new__( clscls, name, bases, namespace ) 

136 

137 

138@_class_factory( ) 

139class ProtocolClass( type( __.typx.Protocol ) ): 

140 ''' Metaclass for standard protocol classes. ''' 

141 

142 _dynadoc_fragments_ = ( 

143 'cfc produce protocol class', 

144 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

145 'cfc instance conceal', 'cfc instance protect' ) 

146 

147 def __new__( # Typechecker stub. 

148 clscls: type[ __.T ], 

149 name: str, 

150 bases: tuple[ type, ... ], 

151 namespace: dict[ str, __.typx.Any ], *, 

152 decorators: __.ClassDecorators[ __.T ] = ( ), 

153 **arguments: __.typx.Unpack[ __.ccstd.ClassFactoryExtraArguments ], 

154 ) -> __.T: 

155 return super( ).__new__( clscls, name, bases, namespace ) 

156 

157 

158@_class_factory( ) 

159@__.typx.dataclass_transform( frozen_default = True, kw_only_default = True ) 

160class ProtocolDataclass( type( __.typx.Protocol ) ): 

161 ''' Metaclass for standard protocol dataclasses. ''' 

162 

163 _dynadoc_fragments_ = ( 

164 'cfc produce protocol class', 'cfc produce dataclass', 

165 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

166 'cfc instance conceal', 'cfc instance protect' ) 

167 

168 def __new__( # Typechecker stub. 

169 clscls: type[ __.T ], 

170 name: str, 

171 bases: tuple[ type, ... ], 

172 namespace: dict[ str, __.typx.Any ], *, 

173 decorators: __.ClassDecorators[ __.T ] = ( ), 

174 **arguments: __.typx.Unpack[ __.ccstd.ClassFactoryExtraArguments ], 

175 ) -> __.T: 

176 return super( ).__new__( clscls, name, bases, namespace ) 

177 

178 

179@_class_factory( ) 

180@__.typx.dataclass_transform( kw_only_default = True ) 

181class ProtocolDataclassMutable( type( __.typx.Protocol ) ): 

182 ''' Metaclass for protocol dataclasses with mutable instances. 

183 ''' 

184 

185 _dynadoc_fragments_ = ( 

186 'cfc produce protocol class', 'cfc produce dataclass', 

187 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

188 'cfc instance conceal' ) 

189 

190 def __new__( # Typechecker stub. 

191 clscls: type[ __.T ], 

192 name: str, 

193 bases: tuple[ type, ... ], 

194 namespace: dict[ str, __.typx.Any ], *, 

195 decorators: __.ClassDecorators[ __.T ] = ( ), 

196 **arguments: __.typx.Unpack[ __.ccstd.ClassFactoryExtraArguments ], 

197 ) -> __.T: 

198 return super( ).__new__( clscls, name, bases, namespace ) 

199 

200 

201class Object( metaclass = Class ): 

202 ''' Standard base class. ''' 

203 

204 _dynadoc_fragments_ = ( 

205 'class concealment', 'class protection', 'class dynadoc', 

206 'class instance conceal', 'class instance protect' ) 

207 

208 

209class ObjectMutable( metaclass = Class, instances_mutables = '*' ): 

210 ''' Base class with mutable instance attributes. ''' 

211 

212 _dynadoc_fragments_ = ( 

213 'class concealment', 'class protection', 'class dynadoc', 

214 'class instance conceal' ) 

215 

216 

217class DataclassObject( metaclass = Dataclass ): 

218 ''' Standard base dataclass. ''' 

219 

220 _dynadoc_fragments_ = ( 

221 'dataclass', 

222 'class concealment', 'class protection', 'class dynadoc', 

223 'class instance conceal', 'class instance protect' ) 

224 

225 

226class DataclassObjectMutable( metaclass = DataclassMutable ): 

227 ''' Base dataclass with mutable instance attributes. ''' 

228 

229 _dynadoc_fragments_ = ( 

230 'dataclass', 

231 'class concealment', 'class protection', 'class dynadoc', 

232 'class instance conceal' ) 

233 

234 

235class Protocol( __.typx.Protocol, metaclass = ProtocolClass ): 

236 ''' Standard base protocol class. ''' 

237 

238 _dynadoc_fragments_ = ( 

239 'protocol class', 

240 'class concealment', 'class protection', 'class dynadoc', 

241 'class instance conceal', 'class instance protect' ) 

242 

243 

244class ProtocolMutable( 

245 __.typx.Protocol, metaclass = ProtocolClass, instances_mutables = '*' 

246): 

247 ''' Base protocol class with mutable instance attributes. ''' 

248 

249 _dynadoc_fragments_ = ( 

250 'protocol class', 

251 'class concealment', 'class protection', 'class dynadoc', 

252 'class instance conceal' ) 

253 

254 

255class DataclassProtocol( 

256 __.typx.Protocol, metaclass = ProtocolDataclass, 

257): 

258 ''' Standard base protocol dataclass. ''' 

259 

260 _dynadoc_fragments_ = ( 

261 'dataclass', 'protocol class', 

262 'class concealment', 'class protection', 'class dynadoc', 

263 'class instance conceal', 'class instance protect' ) 

264 

265 

266class DataclassProtocolMutable( 

267 __.typx.Protocol, metaclass = ProtocolDataclassMutable, 

268): 

269 ''' Base protocol dataclass with mutable instance attributes. ''' 

270 

271 _dynadoc_fragments_ = ( 

272 'dataclass', 'protocol class', 

273 'class concealment', 'class protection', 'class dynadoc', 

274 'class instance conceal' ) 

275 

276 

277@__.typx.overload 

278def dataclass_with_standard_behaviors( # pragma: no cover 

279 cls: type[ __.U ], /, *, 

280 decorators: __.ClassDecorators[ __.U ] = ( ), 

281 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

282 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

283) -> type[ __.U ]: ... 

284 

285 

286@__.typx.overload 

287def dataclass_with_standard_behaviors( # pragma: no cover 

288 cls: __.AbsentSingleton = __.absent, /, *, 

289 decorators: __.ClassDecorators[ __.U ] = ( ), 

290 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

291 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

292) -> __.ClassDecoratorFactory[ __.U ]: ... 

293 

294 

295@__.typx.dataclass_transform( frozen_default = True, kw_only_default = True ) 

296def dataclass_with_standard_behaviors( 

297 cls: __.Absential[ type[ __.U ] ] = __.absent, /, *, 

298 decorators: __.ClassDecorators[ __.U ] = ( ), 

299 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

300 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

301) -> type[ __.U ] | __.ClassDecoratorFactory[ __.U ]: 

302 ''' Decorates dataclass to enforce standard behaviors on instances. ''' 

303 decorate = __.funct.partial( 

304 __.ccstd.dataclass_with_standard_behaviors, 

305 attributes_namer = __.calculate_attrname, 

306 error_class_provider = _provide_error_class, 

307 decorators = decorators, 

308 mutables = mutables, visibles = visibles ) 

309 if not __.is_absent( cls ): return decorate( )( cls ) 

310 return decorate( ) # No class to decorate; keyword arguments only. 

311 

312 

313@__.typx.overload 

314def with_standard_behaviors( # pragma: no cover 

315 cls: type[ __.U ], /, *, 

316 decorators: __.ClassDecorators[ __.U ] = ( ), 

317 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

318 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

319) -> type[ __.U ]: ... 

320 

321 

322@__.typx.overload 

323def with_standard_behaviors( # pragma: no cover 

324 cls: __.AbsentSingleton = __.absent, /, *, 

325 decorators: __.ClassDecorators[ __.U ] = ( ), 

326 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

327 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

328) -> __.ClassDecoratorFactory[ __.U ]: ... 

329 

330 

331def with_standard_behaviors( 

332 cls: __.Absential[ type[ __.U ] ] = __.absent, /, *, 

333 decorators: __.ClassDecorators[ __.U ] = ( ), 

334 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

335 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

336) -> type[ __.U ] | __.ClassDecoratorFactory[ __.U ]: 

337 ''' Decorates class to enforce standard behaviors on instances. ''' 

338 decorate = __.funct.partial( 

339 __.ccstd.with_standard_behaviors, 

340 attributes_namer = __.calculate_attrname, 

341 error_class_provider = _provide_error_class, 

342 decorators = decorators, 

343 mutables = mutables, visibles = visibles ) 

344 if not __.is_absent( cls ): return decorate( )( cls ) 

345 return decorate( ) # No class to decorate; keyword arguments only.