Coverage for sources/classcore/__init__.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''' Foundational class factories and decorators. 

22 

23 Provides ability to create class decorators and metaclasses 

24 with customization hooks. The metaclasses can apply class decorators 

25 inline during the class construction and initialization process, properly 

26 handling cases where decorators replace classes (e.g., 

27 ``dataclasses.dataclass( slots = True )``). They also backport the repair 

28 mechanism from newer versions of CPython to ensure that the class closure 

29 cells are rectified on replaced classes, so that zero-argument ``super`` 

30 calls function correctly in them. 

31 

32 The ``classcore.standard`` subpackage is an example of the decorators and 

33 customization hooks being used to provide a set of practical classes and 

34 class decorators. Furthermore, the exception classes in the 

35 :py:mod:`classcore.exceptions` module inherit from one of the standard 

36 classes, making both the exception classes, themselves, and their 

37 instances immutable and concealing their non-public attributes to reduce 

38 API noise. I.e., this package "eats its own dog food" and provides 

39 practical examples in so doing. 

40 

41 This package is not as magical as it might seem. It does **not** rely on 

42 any ``exec`` or ``eval`` calls and it does **not** do anything with 

43 ``ctypes`` or similar surgical instruments. It relies completely on the 

44 documented Python data model and the machinery that it provides. While it 

45 is true that metaclasses can be tricky, this package is developed with a 

46 deep, highly-evolved understanding of them. We seek simplicity over 

47 cleverness and maintain robust tests across multiple Python 

48 implementations and versions. The package is also very clean in terms of 

49 static type checking (via Pyright). 

50''' 

51 

52 

53from . import __ 

54from . import exceptions 

55from . import nomina 

56from . import standard 

57# --- BEGIN: Injected by Copier --- 

58# --- END: Injected by Copier --- 

59 

60from .decorators import * 

61from .factories import * 

62 

63 

64__version__: __.typx.Annotated[ str, __.ddoc.Visibilities.Reveal ] 

65__version__ = '1.5.3' 

66 

67 

68standard.dynadoc.assign_module_docstring( __name__, table = __.fragments ) 

69standard.reclassify_modules( __name__, recursive = True )