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( table = __.fragments ) ) 

48_class_factory = __.funct.partial( 

49 __.ccstd.class_factory, 

50 attributes_namer = __.calculate_attrname, 

51 dynadoc_configuration = _dynadoc_configuration, 

52 error_class_provider = _provide_error_class ) 

53 

54 

55@_class_factory( ) 

56class Class( type ): 

57 ''' Metaclass for standard classes. ''' 

58 

59 _dynadoc_fragments_ = ( 

60 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

61 'cfc instance conceal', 'cfc instance protect' ) 

62 

63 def __new__( # Typechecker stub. 

64 clscls: type[ __.T ], 

65 name: str, 

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

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

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

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

70 ) -> __.T: 

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

72 

73 

74@_class_factory( ) 

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

76class Dataclass( type ): 

77 ''' Metaclass for standard dataclasses. ''' 

78 

79 _dynadoc_fragments_ = ( 

80 'cfc produce dataclass', 

81 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

82 'cfc instance conceal', 'cfc instance protect' ) 

83 

84 def __new__( # Typechecker stub. 

85 clscls: type[ __.T ], 

86 name: str, 

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

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

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

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

91 ) -> __.T: 

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

93 

94 

95@_class_factory( ) 

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

97class DataclassMutable( type ): 

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

99 

100 _dynadoc_fragments_ = ( 

101 'cfc produce dataclass', 

102 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

103 'cfc instance conceal' ) 

104 

105 def __new__( # Typechecker stub. 

106 clscls: type[ __.T ], 

107 name: str, 

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

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

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

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

112 ) -> __.T: 

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

114 

115 

116@_class_factory( ) 

117class AbstractBaseClass( __.abc.ABCMeta ): 

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

119 

120 _dynadoc_fragments_ = ( 

121 'cfc produce abstract base class', 

122 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

123 'cfc instance conceal', 'cfc instance protect' ) 

124 

125 def __new__( # Typechecker stub. 

126 clscls: type[ __.T ], 

127 name: str, 

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

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

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

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

132 ) -> __.T: 

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

134 

135 

136@_class_factory( ) 

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

138 ''' Metaclass for standard protocol classes. ''' 

139 

140 _dynadoc_fragments_ = ( 

141 'cfc produce protocol class', 

142 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

143 'cfc instance conceal', 'cfc instance protect' ) 

144 

145 def __new__( # Typechecker stub. 

146 clscls: type[ __.T ], 

147 name: str, 

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

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

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

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

152 ) -> __.T: 

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

154 

155 

156@_class_factory( ) 

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

158class ProtocolDataclass( ProtocolClass ): 

159 ''' Metaclass for standard protocol dataclasses. ''' 

160 

161 _dynadoc_fragments_ = ( 

162 'cfc produce protocol class', 'cfc produce dataclass', 

163 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

164 'cfc instance conceal', 'cfc instance protect' ) 

165 

166 def __new__( # Typechecker stub. 

167 clscls: type[ __.T ], 

168 name: str, 

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

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

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

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

173 ) -> __.T: 

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

175 

176 

177@_class_factory( ) 

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

179class ProtocolDataclassMutable( ProtocolDataclass ): 

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

181 ''' 

182 

183 _dynadoc_fragments_ = ( 

184 'cfc produce protocol class', 'cfc produce dataclass', 

185 'cfc class conceal', 'cfc class protect', 'cfc dynadoc', 

186 'cfc instance conceal' ) 

187 

188 def __new__( # Typechecker stub. 

189 clscls: type[ __.T ], 

190 name: str, 

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

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

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

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

195 ) -> __.T: 

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

197 

198 

199class Object( metaclass = Class ): 

200 ''' Standard base class. ''' 

201 

202 _dynadoc_fragments_ = ( 

203 'class concealment', 'class protection', 'class dynadoc', 

204 'class instance conceal', 'class instance protect' ) 

205 

206 

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

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

209 

210 _dynadoc_fragments_ = ( 

211 'class concealment', 'class protection', 'class dynadoc', 

212 'class instance conceal' ) 

213 

214 

215class DataclassObject( metaclass = Dataclass ): 

216 ''' Standard base dataclass. ''' 

217 

218 _dynadoc_fragments_ = ( 

219 'dataclass', 

220 'class concealment', 'class protection', 'class dynadoc', 

221 'class instance conceal', 'class instance protect' ) 

222 

223 

224class DataclassObjectMutable( metaclass = DataclassMutable ): 

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

226 

227 _dynadoc_fragments_ = ( 

228 'dataclass', 

229 'class concealment', 'class protection', 'class dynadoc', 

230 'class instance conceal' ) 

231 

232 

233class Protocol( 

234 __.typx.Protocol, 

235 metaclass = ProtocolClass, 

236 class_mutables = ( *__.abc_class_mutables, *__.typing_class_mutables ), 

237): 

238 ''' Standard base protocol class. ''' 

239 

240 _dynadoc_fragments_ = ( 

241 'protocol class', 

242 'class concealment', 'class protection', 'class dynadoc', 

243 'class instance conceal', 'class instance protect' ) 

244 

245 

246class ProtocolMutable( 

247 __.typx.Protocol, 

248 metaclass = ProtocolClass, 

249 class_mutables = ( *__.abc_class_mutables, *__.typing_class_mutables ), 

250 instances_mutables = '*', 

251): 

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

253 

254 _dynadoc_fragments_ = ( 

255 'protocol class', 

256 'class concealment', 'class protection', 'class dynadoc', 

257 'class instance conceal' ) 

258 

259 

260class DataclassProtocol( 

261 __.typx.Protocol, 

262 metaclass = ProtocolDataclass, 

263 class_mutables = ( *__.abc_class_mutables, *__.typing_class_mutables ), 

264): 

265 ''' Standard base protocol dataclass. ''' 

266 

267 _dynadoc_fragments_ = ( 

268 'dataclass', 'protocol class', 

269 'class concealment', 'class protection', 'class dynadoc', 

270 'class instance conceal', 'class instance protect' ) 

271 

272 

273class DataclassProtocolMutable( 

274 __.typx.Protocol, 

275 metaclass = ProtocolDataclassMutable, 

276 class_mutables = ( *__.abc_class_mutables, *__.typing_class_mutables ), 

277): 

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

279 

280 _dynadoc_fragments_ = ( 

281 'dataclass', 'protocol class', 

282 'class concealment', 'class protection', 'class dynadoc', 

283 'class instance conceal' ) 

284 

285 

286@__.typx.overload 

287def dataclass_with_standard_behaviors( # pragma: no cover 

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

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

290 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

291 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

293 

294 

295@__.typx.overload 

296def dataclass_with_standard_behaviors( # pragma: no cover 

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

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

299 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

300 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

302 

303 

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

305def dataclass_with_standard_behaviors( 

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

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

308 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

309 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

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

312 decorate = __.funct.partial( 

313 __.ccstd.dataclass_with_standard_behaviors, 

314 attributes_namer = __.calculate_attrname, 

315 error_class_provider = _provide_error_class, 

316 decorators = decorators, 

317 mutables = mutables, visibles = visibles ) 

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

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

320 

321 

322@__.typx.overload 

323def with_standard_behaviors( # pragma: no cover 

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

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

326 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

327 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

329 

330 

331@__.typx.overload 

332def with_standard_behaviors( # pragma: no cover 

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

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

335 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

336 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

338 

339 

340def with_standard_behaviors( 

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

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

343 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

344 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

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

347 decorate = __.funct.partial( 

348 __.ccstd.with_standard_behaviors, 

349 attributes_namer = __.calculate_attrname, 

350 error_class_provider = _provide_error_class, 

351 decorators = decorators, 

352 mutables = mutables, visibles = visibles ) 

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

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