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 

29abc_class_mutables = ( 

30 '_abc_cache', 

31 '_abc_negative_cache', 

32 '_abc_negative_cache_version', 

33 '_abc_registry', 

34) 

35is_public_identifier = __.is_public_identifier 

36mutables_default = ( ) 

37visibles_default = ( is_public_identifier, ) 

38 

39 

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

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

42 match name: 

43 case 'AttributeImmutability': 

44 from .exceptions import AttributeImmutability as error 

45 case _: 

46 from .exceptions import ErrorProvideFailure 

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

48 return error 

49 

50 

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

52_dynadoc_configuration = ( 

53 __.ccstd.dynadoc.produce_dynadoc_configuration( table = __.fragments ) ) 

54_class_factory = __.funct.partial( 

55 __.ccstd.class_factory, 

56 attributes_namer = __.calculate_attrname, 

57 dynadoc_configuration = _dynadoc_configuration, 

58 error_class_provider = _provide_error_class ) 

59 

60 

61@_class_factory( ) 

62class Class( type ): 

63 ''' Metaclass for standard classes. ''' 

64 

65 _dynadoc_fragments_ = ( 

66 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

67 'cfc instance conceal', 'cfc instance protect' ) 

68 

69 def __new__( # Typechecker stub. 

70 clscls: type[ __.T ], 

71 name: str, 

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

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

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

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

76 ) -> __.T: 

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

78 

79 

80@_class_factory( ) 

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

82class Dataclass( type ): 

83 ''' Metaclass for standard dataclasses. ''' 

84 

85 _dynadoc_fragments_ = ( 

86 'cfc produce dataclass', 

87 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

88 'cfc instance conceal', 'cfc instance protect' ) 

89 

90 def __new__( # Typechecker stub. 

91 clscls: type[ __.T ], 

92 name: str, 

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

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

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

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

97 ) -> __.T: 

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

99 

100 

101@_class_factory( ) 

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

103class DataclassMutable( type ): 

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

105 

106 _dynadoc_fragments_ = ( 

107 'cfc produce dataclass', 

108 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

109 'cfc instance conceal' ) 

110 

111 def __new__( # Typechecker stub. 

112 clscls: type[ __.T ], 

113 name: str, 

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

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

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

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

118 ) -> __.T: 

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

120 

121 

122@_class_factory( ) 

123class AbstractBaseClass( __.abc.ABCMeta ): 

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

125 

126 _dynadoc_fragments_ = ( 

127 'cfc produce abstract base class', 

128 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

129 'cfc instance conceal', 'cfc instance protect' ) 

130 

131 def __new__( # Typechecker stub. 

132 clscls: type[ __.T ], 

133 name: str, 

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

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

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

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

138 ) -> __.T: 

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

140 

141 

142@_class_factory( ) 

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

144 ''' Metaclass for standard protocol classes. ''' 

145 

146 _dynadoc_fragments_ = ( 

147 'cfc produce protocol class', 

148 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

149 'cfc instance conceal', 'cfc instance protect' ) 

150 

151 def __new__( # Typechecker stub. 

152 clscls: type[ __.T ], 

153 name: str, 

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

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

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

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

158 ) -> __.T: 

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

160 

161 

162@_class_factory( ) 

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

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

165 ''' Metaclass for standard protocol dataclasses. ''' 

166 

167 _dynadoc_fragments_ = ( 

168 'cfc produce protocol class', 'cfc produce dataclass', 

169 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

170 'cfc instance conceal', 'cfc instance protect' ) 

171 

172 def __new__( # Typechecker stub. 

173 clscls: type[ __.T ], 

174 name: str, 

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

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

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

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

179 ) -> __.T: 

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

181 

182 

183@_class_factory( ) 

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

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

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

187 ''' 

188 

189 _dynadoc_fragments_ = ( 

190 'cfc produce protocol class', 'cfc produce dataclass', 

191 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

192 'cfc instance conceal' ) 

193 

194 def __new__( # Typechecker stub. 

195 clscls: type[ __.T ], 

196 name: str, 

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

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

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

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

201 ) -> __.T: 

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

203 

204 

205class Object( metaclass = Class ): 

206 ''' Standard base class. ''' 

207 

208 _dynadoc_fragments_ = ( 

209 'class concealment', 'class protection', 'class dynadoc', 

210 'class instance conceal', 'class instance protect' ) 

211 

212 

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

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

215 

216 _dynadoc_fragments_ = ( 

217 'class concealment', 'class protection', 'class dynadoc', 

218 'class instance conceal' ) 

219 

220 

221class DataclassObject( metaclass = Dataclass ): 

222 ''' Standard base dataclass. ''' 

223 

224 _dynadoc_fragments_ = ( 

225 'dataclass', 

226 'class concealment', 'class protection', 'class dynadoc', 

227 'class instance conceal', 'class instance protect' ) 

228 

229 

230class DataclassObjectMutable( metaclass = DataclassMutable ): 

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

232 

233 _dynadoc_fragments_ = ( 

234 'dataclass', 

235 'class concealment', 'class protection', 'class dynadoc', 

236 'class instance conceal' ) 

237 

238 

239class Protocol( 

240 __.typx.Protocol, 

241 metaclass = ProtocolClass, 

242 class_mutables = abc_class_mutables, 

243): 

244 ''' Standard base protocol class. ''' 

245 

246 _dynadoc_fragments_ = ( 

247 'protocol class', 

248 'class concealment', 'class protection', 'class dynadoc', 

249 'class instance conceal', 'class instance protect' ) 

250 

251 

252class ProtocolMutable( 

253 __.typx.Protocol, 

254 metaclass = ProtocolClass, 

255 class_mutables = abc_class_mutables, 

256 instances_mutables = '*', 

257): 

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

259 

260 _dynadoc_fragments_ = ( 

261 'protocol class', 

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

263 'class instance conceal' ) 

264 

265 

266class DataclassProtocol( 

267 __.typx.Protocol, 

268 metaclass = ProtocolDataclass, 

269 class_mutables = abc_class_mutables, 

270): 

271 ''' Standard base protocol dataclass. ''' 

272 

273 _dynadoc_fragments_ = ( 

274 'dataclass', 'protocol class', 

275 'class concealment', 'class protection', 'class dynadoc', 

276 'class instance conceal', 'class instance protect' ) 

277 

278 

279class DataclassProtocolMutable( 

280 __.typx.Protocol, 

281 metaclass = ProtocolDataclassMutable, 

282 class_mutables = abc_class_mutables, 

283): 

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

285 

286 _dynadoc_fragments_ = ( 

287 'dataclass', 'protocol class', 

288 'class concealment', 'class protection', 'class dynadoc', 

289 'class instance conceal' ) 

290 

291 

292@__.typx.overload 

293def dataclass_with_standard_behaviors( # pragma: no cover 

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

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

296 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

297 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

299 

300 

301@__.typx.overload 

302def dataclass_with_standard_behaviors( # pragma: no cover 

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

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

305 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

306 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

308 

309 

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

311def dataclass_with_standard_behaviors( 

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

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

314 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

315 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

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

318 decorate = __.funct.partial( 

319 __.ccstd.dataclass_with_standard_behaviors, 

320 attributes_namer = __.calculate_attrname, 

321 error_class_provider = _provide_error_class, 

322 decorators = decorators, 

323 mutables = mutables, visibles = visibles ) 

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

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

326 

327 

328@__.typx.overload 

329def with_standard_behaviors( # pragma: no cover 

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

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

332 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

333 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

335 

336 

337@__.typx.overload 

338def with_standard_behaviors( # pragma: no cover 

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

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

341 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

342 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

344 

345 

346def with_standard_behaviors( 

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

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

349 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

350 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

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

353 decorate = __.funct.partial( 

354 __.ccstd.with_standard_behaviors, 

355 attributes_namer = __.calculate_attrname, 

356 error_class_provider = _provide_error_class, 

357 decorators = decorators, 

358 mutables = mutables, visibles = visibles ) 

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

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