Coverage for sources/accretive/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''' Accretive classes. ''' 

22 

23# ruff: noqa: F811 

24 

25 

26from . import __ 

27from . import iclasses as _iclasses 

28 

29 

30abc_class_mutables = ( 

31 '_abc_cache', 

32 '_abc_negative_cache', 

33 '_abc_negative_cache_version', 

34 '_abc_registry', 

35) 

36mutables_default = _iclasses.mutables_default 

37visibles_default = _iclasses.visibles_default 

38 

39 

40_class_factory = __.funct.partial( 

41 __.ccstd.class_factory, 

42 assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

43 attributes_namer = __.calculate_attrname, 

44 dynadoc_configuration = _iclasses.dynadoc_configuration, 

45 error_class_provider = _iclasses.provide_error_class ) 

46 

47 

48@_class_factory( ) 

49class Class( type ): 

50 ''' Metaclass for standard classes. ''' 

51 

52 _dynadoc_fragments_ = ( 

53 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

54 'cfc instance conceal', 'cfc instance protect' ) 

55 

56 def __new__( # Typechecker stub. 

57 clscls: type[ __.T ], 

58 name: str, 

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

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

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

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

63 ) -> __.T: 

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

65 

66 

67@_class_factory( ) 

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

69class Dataclass( type ): 

70 ''' Metaclass for standard dataclasses. ''' 

71 

72 _dynadoc_fragments_ = ( 

73 'cfc produce dataclass', 

74 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

75 'cfc instance conceal', 'cfc instance protect' ) 

76 

77 def __new__( # Typechecker stub. 

78 clscls: type[ __.T ], 

79 name: str, 

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

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

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

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

84 ) -> __.T: 

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

86 

87 

88@_class_factory( ) 

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

90class DataclassMutable( type ): 

91 ''' Metaclass for dataclasses with mutable instance attributes. ''' 

92 

93 _dynadoc_fragments_ = ( 

94 'cfc produce dataclass', 

95 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

96 'cfc instance conceal' ) 

97 

98 def __new__( # Typechecker stub. 

99 clscls: type[ __.T ], 

100 name: str, 

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

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

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

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

105 ) -> __.T: # pragma: no cover 

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

107 

108 

109@_class_factory( ) 

110class AbstractBaseClass( __.abc.ABCMeta ): 

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

112 

113 _dynadoc_fragments_ = ( 

114 'cfc produce abstract base class', 

115 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

116 'cfc instance conceal', 'cfc instance protect' ) 

117 

118 def __new__( # Typechecker stub. 

119 clscls: type[ __.T ], 

120 name: str, 

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

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

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

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

125 ) -> __.T: 

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

127 

128 

129@_class_factory( ) 

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

131 ''' Metaclass for standard protocol classes. ''' 

132 

133 _dynadoc_fragments_ = ( 

134 'cfc produce protocol class', 

135 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

136 'cfc instance conceal', 'cfc instance protect' ) 

137 

138 def __new__( # Typechecker stub. 

139 clscls: type[ __.T ], 

140 name: str, 

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

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

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

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

145 ) -> __.T: 

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

147 

148 

149@_class_factory( ) 

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

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

152 ''' Metaclass for standard protocol dataclasses. ''' 

153 

154 _dynadoc_fragments_ = ( 

155 'cfc produce protocol class', 'cfc produce dataclass', 

156 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

157 'cfc instance conceal', 'cfc instance protect' ) 

158 

159 def __new__( # Typechecker stub. 

160 clscls: type[ __.T ], 

161 name: str, 

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

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

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

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

166 ) -> __.T: # pragma: no cover 

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

168 

169 

170@_class_factory( ) 

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

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

173 ''' Metaclass for protocol dataclasses with mutable instance attributes. 

174 ''' 

175 

176 _dynadoc_fragments_ = ( 

177 'cfc produce protocol class', 'cfc produce dataclass', 

178 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

179 'cfc instance conceal' ) 

180 

181 def __new__( # Typechecker stub. 

182 clscls: type[ __.T ], 

183 name: str, 

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

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

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

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

188 ) -> __.T: # pragma: no cover 

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

190 

191 

192class Object( 

193 metaclass = _iclasses.Class, 

194 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

195): 

196 ''' Standard base class. ''' 

197 

198 _dynadoc_fragments_ = ( 

199 'class concealment', 'class protection', 'class dynadoc', 

200 'class instance conceal', 'class instance accrete' ) 

201 

202 

203class ObjectMutable( 

204 metaclass = _iclasses.Class, 

205 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

206 instances_mutables = '*', 

207): 

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( 

216 metaclass = _iclasses.Dataclass, 

217 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

218): 

219 ''' Standard base dataclass. ''' 

220 

221 _dynadoc_fragments_ = ( 

222 'dataclass', 

223 'class concealment', 'class protection', 'class dynadoc', 

224 'class instance conceal', 'class instance accrete' ) 

225 

226 

227class DataclassObjectMutable( 

228 metaclass = _iclasses.DataclassMutable, 

229 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

230): 

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 = _iclasses.ProtocolClass, 

242 class_mutables = abc_class_mutables, 

243 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

244): 

245 ''' Standard base protocol class. ''' 

246 

247 _dynadoc_fragments_ = ( 

248 'protocol class', 

249 'class concealment', 'class protection', 'class dynadoc', 

250 'class instance conceal', 'class instance accrete' ) 

251 

252 

253class ProtocolMutable( 

254 __.typx.Protocol, 

255 metaclass = _iclasses.ProtocolClass, 

256 class_mutables = abc_class_mutables, 

257 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

258 instances_mutables = '*', 

259): 

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

261 

262 _dynadoc_fragments_ = ( 

263 'protocol class', 

264 'class concealment', 'class protection', 'class dynadoc', 

265 'class instance conceal' ) 

266 

267 

268class DataclassProtocol( 

269 __.typx.Protocol, 

270 metaclass = _iclasses.ProtocolDataclass, 

271 class_mutables = abc_class_mutables, 

272 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

273): 

274 ''' Standard base protocol dataclass. ''' 

275 

276 _dynadoc_fragments_ = ( 

277 'dataclass', 'protocol class', 

278 'class concealment', 'class protection', 'class dynadoc', 

279 'class instance conceal', 'class instance accrete' ) 

280 

281 

282class DataclassProtocolMutable( 

283 __.typx.Protocol, 

284 metaclass = _iclasses.ProtocolDataclassMutable, 

285 class_mutables = abc_class_mutables, 

286 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

287): 

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

289 

290 _dynadoc_fragments_ = ( 

291 'dataclass', 'protocol class', 

292 'class concealment', 'class protection', 'class dynadoc', 

293 'class instance conceal' ) 

294 

295 

296@__.typx.overload 

297def dataclass_with_standard_behaviors( # pragma: no cover 

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

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

300 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

301 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

303 

304 

305@__.typx.overload 

306def dataclass_with_standard_behaviors( # pragma: no cover 

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

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

309 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

310 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

312 

313 

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

315def dataclass_with_standard_behaviors( 

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

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

318 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

319 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

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

322 decorate = __.funct.partial( 

323 __.ccstd.dataclass_with_standard_behaviors, 

324 attributes_namer = __.calculate_attrname, 

325 error_class_provider = _iclasses.provide_error_class, 

326 assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

327 decorators = decorators, 

328 mutables = mutables, visibles = visibles ) 

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

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

331 

332 

333@__.typx.overload 

334def with_standard_behaviors( # pragma: no cover 

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

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

337 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

338 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

340 

341 

342@__.typx.overload 

343def with_standard_behaviors( # pragma: no cover 

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

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

346 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

347 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

349 

350 

351def with_standard_behaviors( 

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

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

354 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

355 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

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

358 decorate = __.funct.partial( 

359 __.ccstd.with_standard_behaviors, 

360 attributes_namer = __.calculate_attrname, 

361 error_class_provider = _iclasses.provide_error_class, 

362 assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

363 decorators = decorators, 

364 mutables = mutables, visibles = visibles ) 

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

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