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 

30mutables_default = _iclasses.mutables_default 

31visibles_default = _iclasses.visibles_default 

32 

33 

34_class_factory = __.funct.partial( 

35 __.ccstd.class_factory, 

36 assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

37 attributes_namer = __.calculate_attrname, 

38 dynadoc_configuration = _iclasses.dynadoc_configuration, 

39 error_class_provider = _iclasses.provide_error_class ) 

40 

41 

42@_class_factory( ) 

43class Class( type ): 

44 ''' Metaclass for standard classes. ''' 

45 

46 _dynadoc_fragments_ = ( 

47 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

48 'cfc instance conceal', 'cfc instance protect' ) 

49 

50 def __new__( # Typechecker stub. 

51 clscls: type[ __.T ], 

52 name: str, 

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

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

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

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

57 ) -> __.T: 

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

59 

60 

61@_class_factory( ) 

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

63class Dataclass( type ): 

64 ''' Metaclass for standard dataclasses. ''' 

65 

66 _dynadoc_fragments_ = ( 

67 'cfc produce dataclass', 

68 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

69 'cfc instance conceal', 'cfc instance protect' ) 

70 

71 def __new__( # Typechecker stub. 

72 clscls: type[ __.T ], 

73 name: str, 

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

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

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

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

78 ) -> __.T: 

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

80 

81 

82@_class_factory( ) 

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

84class DataclassMutable( type ): 

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

86 

87 _dynadoc_fragments_ = ( 

88 'cfc produce dataclass', 

89 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

90 'cfc instance conceal' ) 

91 

92 def __new__( # Typechecker stub. 

93 clscls: type[ __.T ], 

94 name: str, 

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

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

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

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

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

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

101 

102 

103@_class_factory( ) 

104class AbstractBaseClass( __.abc.ABCMeta ): 

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

106 

107 _dynadoc_fragments_ = ( 

108 'cfc produce abstract base class', 

109 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

110 'cfc instance conceal', 'cfc instance protect' ) 

111 

112 def __new__( # Typechecker stub. 

113 clscls: type[ __.T ], 

114 name: str, 

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

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

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

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

119 ) -> __.T: 

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

121 

122 

123@_class_factory( ) 

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

125 ''' Metaclass for standard protocol classes. ''' 

126 

127 _dynadoc_fragments_ = ( 

128 'cfc produce protocol class', 

129 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

130 'cfc instance conceal', 'cfc instance protect' ) 

131 

132 def __new__( # Typechecker stub. 

133 clscls: type[ __.T ], 

134 name: str, 

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

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

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

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

139 ) -> __.T: 

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

141 

142 

143@_class_factory( ) 

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

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

146 ''' Metaclass for standard protocol dataclasses. ''' 

147 

148 _dynadoc_fragments_ = ( 

149 'cfc produce protocol class', 'cfc produce dataclass', 

150 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

151 'cfc instance conceal', 'cfc instance protect' ) 

152 

153 def __new__( # Typechecker stub. 

154 clscls: type[ __.T ], 

155 name: str, 

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

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

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

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

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

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

162 

163 

164@_class_factory( ) 

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

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

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

168 ''' 

169 

170 _dynadoc_fragments_ = ( 

171 'cfc produce protocol class', 'cfc produce dataclass', 

172 'cfc class conceal', 'cfc class accrete', 'cfc dynadoc', 

173 'cfc instance conceal' ) 

174 

175 def __new__( # Typechecker stub. 

176 clscls: type[ __.T ], 

177 name: str, 

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

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

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

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

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

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

184 

185 

186class Object( 

187 metaclass = _iclasses.Class, 

188 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

189): 

190 ''' Standard base class. ''' 

191 

192 _dynadoc_fragments_ = ( 

193 'class concealment', 'class protection', 'class dynadoc', 

194 'class instance conceal', 'class instance accrete' ) 

195 

196 

197class ObjectMutable( 

198 metaclass = _iclasses.Class, 

199 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

200 instances_mutables = '*', 

201): 

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

203 

204 _dynadoc_fragments_ = ( 

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

206 'class instance conceal' ) 

207 

208 

209class DataclassObject( 

210 metaclass = _iclasses.Dataclass, 

211 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

212): 

213 ''' Standard base dataclass. ''' 

214 

215 _dynadoc_fragments_ = ( 

216 'dataclass', 

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

218 'class instance conceal', 'class instance accrete' ) 

219 

220 

221class DataclassObjectMutable( 

222 metaclass = _iclasses.DataclassMutable, 

223 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

224): 

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

236 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

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 accrete' ) 

244 

245 

246class ProtocolMutable( 

247 __.typx.Protocol, 

248 metaclass = _iclasses.ProtocolClass, 

249 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

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

263 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

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 accrete' ) 

271 

272 

273class DataclassProtocolMutable( 

274 __.typx.Protocol, 

275 metaclass = _iclasses.ProtocolDataclassMutable, 

276 instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

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

316 assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

317 decorators = decorators, 

318 mutables = mutables, visibles = visibles ) 

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

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

321 

322 

323@__.typx.overload 

324def with_standard_behaviors( # pragma: no cover 

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

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

327 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

328 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

330 

331 

332@__.typx.overload 

333def with_standard_behaviors( # pragma: no cover 

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

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

336 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

337 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

339 

340 

341def with_standard_behaviors( 

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

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

344 mutables: __.BehaviorExclusionVerifiersOmni = mutables_default, 

345 visibles: __.BehaviorExclusionVerifiersOmni = visibles_default, 

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

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

348 decorate = __.funct.partial( 

349 __.ccstd.with_standard_behaviors, 

350 attributes_namer = __.calculate_attrname, 

351 error_class_provider = _iclasses.provide_error_class, 

352 assigner_core = _iclasses.assign_attribute_if_absent_mutable, 

353 decorators = decorators, 

354 mutables = mutables, visibles = visibles ) 

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

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