classcore 1.1__tar.gz → 1.2rc0__tar.gz

classcore-1.2rc0/.gitignore

@@ -0,0 +1,7 @@
+.env
+.*.swp
+AGENTS.md
+CLAUDE.md
+CONVENTIONS.md
+__pycache__/
+bugs/

{classcore-1.1 → classcore-1.2rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classcore
-Version: 1.1
+Version: 1.2rc0
 Summary: Foundational class factories and decorators.
 Project-URL: Homepage, https://github.com/emcd/python-classcore
 Project-URL: Documentation, https://emcd.github.io/python-classcore
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development
 Requires-Python: >=3.10
+Requires-Dist: dynadoc
 Requires-Dist: typing-extensions
 Description-Content-Type: text/x-rst
 
@@ -256,27 +257,24 @@ Other Projects by This Author 🌟
 ===============================================================================
 
 
-* `python-absence <https://github.com/emcd/python-absence>`_
-    - PyPI: `absence <https://pypi.org/project/absence/>`_
+* `python-absence <https://github.com/emcd/python-absence>`_ (`absence <https://pypi.org/project/absence/>`_ on PyPI) 
 
-    🕳️ A Python library package which provides a **sentinel for absent values** - a falsey, immutable singleton that represents the absence of a value in contexts where ``None`` or ``False`` may be valid values.
-* `python-accretive <https://github.com/emcd/python-accretive>`_
-    - PyPI: `accretive <https://pypi.org/project/accretive/>`_
+  🕳️ A Python library package which provides a **sentinel for absent values** - a falsey, immutable singleton that represents the absence of a value in contexts where ``None`` or ``False`` may be valid values.
+* `python-accretive <https://github.com/emcd/python-accretive>`_ (`accretive <https://pypi.org/project/accretive/>`_ on PyPI) 
 
-    🌌 A Python library package which provides **accretive data structures** - collections which can grow but never shrink.
-* `python-falsifier <https://github.com/emcd/python-falsifier>`_
-    - PyPI: `falsifier <https://pypi.org/project/falsifier/>`_
+  🌌 A Python library package which provides **accretive data structures** - collections which can grow but never shrink.
+* `python-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI) 
 
-    🎭 A very simple Python library package which provides a **base class for falsey objects** - objects that evaluate to ``False`` in boolean contexts.
-* `python-frigid <https://github.com/emcd/python-frigid>`_
-    - PyPI: `frigid <https://pypi.org/project/frigid/>`_
+  📝 A Python library package which bridges the gap between **rich annotations** and **automatic documentation generation** with configurable renderers and support for reusable fragments.
+* `python-falsifier <https://github.com/emcd/python-falsifier>`_ (`falsifier <https://pypi.org/project/falsifier/>`_ on PyPI) 
 
-    🔒 A Python library package which provides **immutable data structures** - collections which cannot be modified after creation.
-* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_
-    - PyPI: `icecream-truck <https://pypi.org/project/icecream-truck/>`_
+  🎭 A very simple Python library package which provides a **base class for falsey objects** - objects that evaluate to ``False`` in boolean contexts.
+* `python-frigid <https://github.com/emcd/python-frigid>`_ (`frigid <https://pypi.org/project/frigid/>`_ on PyPI) 
 
-    🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
-* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_
-    - PyPI: `mimeogram <https://pypi.org/project/mimeogram/>`_
+  🔒 A Python library package which provides **immutable data structures** - collections which cannot be modified after creation.
+* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI) 
 
-    📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.
+  🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
+* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI) 
+
+  📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.

{classcore-1.1 → classcore-1.2rc0}/README.rst

@@ -228,27 +228,24 @@ Other Projects by This Author 🌟
 ===============================================================================
 
 
-* `python-absence <https://github.com/emcd/python-absence>`_
-    - PyPI: `absence <https://pypi.org/project/absence/>`_
+* `python-absence <https://github.com/emcd/python-absence>`_ (`absence <https://pypi.org/project/absence/>`_ on PyPI) 
 
-    🕳️ A Python library package which provides a **sentinel for absent values** - a falsey, immutable singleton that represents the absence of a value in contexts where ``None`` or ``False`` may be valid values.
-* `python-accretive <https://github.com/emcd/python-accretive>`_
-    - PyPI: `accretive <https://pypi.org/project/accretive/>`_
+  🕳️ A Python library package which provides a **sentinel for absent values** - a falsey, immutable singleton that represents the absence of a value in contexts where ``None`` or ``False`` may be valid values.
+* `python-accretive <https://github.com/emcd/python-accretive>`_ (`accretive <https://pypi.org/project/accretive/>`_ on PyPI) 
 
-    🌌 A Python library package which provides **accretive data structures** - collections which can grow but never shrink.
-* `python-falsifier <https://github.com/emcd/python-falsifier>`_
-    - PyPI: `falsifier <https://pypi.org/project/falsifier/>`_
+  🌌 A Python library package which provides **accretive data structures** - collections which can grow but never shrink.
+* `python-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI) 
 
-    🎭 A very simple Python library package which provides a **base class for falsey objects** - objects that evaluate to ``False`` in boolean contexts.
-* `python-frigid <https://github.com/emcd/python-frigid>`_
-    - PyPI: `frigid <https://pypi.org/project/frigid/>`_
+  📝 A Python library package which bridges the gap between **rich annotations** and **automatic documentation generation** with configurable renderers and support for reusable fragments.
+* `python-falsifier <https://github.com/emcd/python-falsifier>`_ (`falsifier <https://pypi.org/project/falsifier/>`_ on PyPI) 
 
-    🔒 A Python library package which provides **immutable data structures** - collections which cannot be modified after creation.
-* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_
-    - PyPI: `icecream-truck <https://pypi.org/project/icecream-truck/>`_
+  🎭 A very simple Python library package which provides a **base class for falsey objects** - objects that evaluate to ``False`` in boolean contexts.
+* `python-frigid <https://github.com/emcd/python-frigid>`_ (`frigid <https://pypi.org/project/frigid/>`_ on PyPI) 
 
-    🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
-* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_
-    - PyPI: `mimeogram <https://pypi.org/project/mimeogram/>`_
+  🔒 A Python library package which provides **immutable data structures** - collections which cannot be modified after creation.
+* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI) 
 
-    📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.
+  🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
+* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI) 
+
+  📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.

{classcore-1.1 → classcore-1.2rc0}/pyproject.toml

@@ -15,6 +15,7 @@ license = 'Apache-2.0'
 readme = { 'file' = 'README.rst', 'content-type' = 'text/x-rst' }
 requires-python = '>= 3.10'
 dependencies = [
+  'dynadoc',
   'typing-extensions',
   # --- BEGIN: Injected by Copier ---
   # --- END: Injected by Copier ---
@@ -166,6 +167,8 @@ python = [
     '3.13',
     'pypy3.10',
 ]
+# [tool.hatch.metadata]
+# allow-direct-references = true
 [tool.hatch.version]
 path = 'sources/classcore/__init__.py'
 
@@ -182,7 +185,7 @@ strict = false
 
 # https://microsoft.github.io/pyright/#/configuration
 [tool.pyright]
-ignore = [ 'tests' ] # Stronger hint for language server.
+ignore = [ 'documentation', 'tests' ] # Stronger hint for language server.
 include = [ 'sources' ]
 reportConstantRedefinition = true
 reportInvalidTypeVarUse = true

{classcore-1.1 → classcore-1.2rc0}/sources/classcore/__/__init__.py

@@ -21,5 +21,13 @@
 ''' Common constants, imports, and utilities. '''
 
 
+from .doctab import *
 from .imports import *
 from .nomina import *
+
+
+T = typx.TypeVar( 'T', bound = type )
+U = typx.TypeVar( 'U' )
+
+
+dictproxy_empty: cabc.Mapping[ str, str ] = types.MappingProxyType( { } )

classcore-1.2rc0/sources/classcore/__/doctab.py

@@ -0,0 +1,76 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Docstring fragments. '''
+
+
+from . import imports as __
+
+
+_FragmentsTable: __.typx.TypeAlias = __.cabc.Mapping[ str, str ]
+fragments: _FragmentsTable = __.types.MappingProxyType( {
+
+    'cfc class conceal':
+    ''' By default, conceals non-public class attributes. ''',
+
+    'cfc class protect':
+    ''' By default, protects class attributes. ''',
+
+    'cfc dynadoc': ''' Applies Dynadoc decoration to classes. ''',
+
+    'cfc instance conceal':
+    ''' Produces classes which can conceal instance attributes. ''',
+
+    'cfc instance protect':
+    ''' Produces classes which can protect instance attributes. ''',
+
+    'cfc produce dataclass':
+    ''' Produces inheritable dataclasses with keyword-only instantiation. ''',
+
+    'cfc produce protocol class':
+    ''' Produces :pep:`544` protocol classes. ''',
+
+    'class concealment':
+    ''' By default, non-public class attributes are invisible. ''',
+
+    'class protection':
+    ''' By default, class attributes are immutable. ''',
+
+    'class instance conceal':
+    ''' By default, conceals non-public instance attributes. ''',
+
+    'class instance protect':
+    ''' By default, protects instance attributes. ''',
+
+    'dataclass':
+    ''' Inheritable dataclass with keyword-only instantiation. ''',
+
+    'protocol class':
+    ''' Protocol class (:pep:`544`). Nominal and structural subtyping. ''',
+
+    'class dynadoc': ''' Is decorated by Dynadoc. ''',
+
+    'decorators':
+    ''' Sequence of class decorators.
+
+        Each element takes a class argument and returns a class.
+    ''',
+
+} )

{classcore-1.1 → classcore-1.2rc0}/sources/classcore/__/imports.py

@@ -23,8 +23,6 @@
 # ruff: noqa: F401
 
 
-from __future__ import annotations
-
 import collections.abc as   cabc
 import dataclasses as       dcls
 import functools as         funct
@@ -35,9 +33,7 @@ import                      re
 import                      sys
 import                      types
 
+import                      dynadoc
 import typing_extensions as typx
 # --- BEGIN: Injected by Copier ---
 # --- END: Injected by Copier ---
-
-
-ComparisonResult: typx.TypeAlias = bool | types.NotImplementedType

{classcore-1.1 → classcore-1.2rc0}/sources/classcore/__/nomina.py

@@ -18,14 +18,13 @@
 #============================================================================#
 
 
-''' Catalog of common type aliases. '''
+''' Common names and type aliases. '''
 
 
-from __future__ import annotations
-
 from . import imports as __
 
 
+ComparisonResult: __.typx.TypeAlias = bool | __.types.NotImplementedType
 NominativeArguments: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ]
 PositionalArguments: __.typx.TypeAlias = __.cabc.Sequence[ __.typx.Any ]
 

classcore-1.2rc0/sources/classcore/__init__.py

@@ -0,0 +1,69 @@
+# vim: set filetype=python fileencoding=utf-8:
+# -*- coding: utf-8 -*-
+
+#============================================================================#
+#                                                                            #
+#  Licensed under the Apache License, Version 2.0 (the "License");           #
+#  you may not use this file except in compliance with the License.          #
+#  You may obtain a copy of the License at                                   #
+#                                                                            #
+#      http://www.apache.org/licenses/LICENSE-2.0                            #
+#                                                                            #
+#  Unless required by applicable law or agreed to in writing, software       #
+#  distributed under the License is distributed on an "AS IS" BASIS,         #
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  #
+#  See the License for the specific language governing permissions and       #
+#  limitations under the License.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Foundational class factories and decorators.
+
+    Provides ability to create class decorators and metaclasses
+    with customization hooks. The metaclasses can apply class decorators
+    inline during the class construction and initialization process, properly
+    handling cases where decorators replace classes (e.g.,
+    ``dataclasses.dataclass( slots = True )``). They also backport the repair
+    mechanism from newer versions of CPython to ensure that the class closure
+    cells are rectified on replaced classes, so that zero-argument ``super``
+    calls function correctly in them.
+
+    The ``classcore.standard`` subpackage is an example of the decorators and
+    customization hooks being used to provide a set of practical classes and
+    class decorators. Furthermore, the exception classes in the
+    :py:mod:`classcore.exceptions` module inherit from one of the standard
+    classes, making both the exception classes, themselves, and their
+    instances immutable and concealing their non-public attributes to reduce
+    API noise. I.e., this package "eats its own dog food" and provides
+    practical examples in so doing.
+
+    This package is not as magical as it might seem. It does **not** rely on
+    any ``exec`` or ``eval`` calls and it does **not** do anything with
+    ``ctypes`` or similar surgical instruments. It relies completely on the
+    documented Python data model and the machinery that it provides. While it
+    is true that metaclasses can be tricky, this package is developed with a
+    deep, highly-evolved understanding of them. We seek simplicity over
+    cleverness and maintain robust tests across multiple Python
+    implementations and versions. The package is also very clean in terms of
+    static type checking (via Pyright).
+'''
+
+
+from . import __
+from . import exceptions
+from . import nomina
+from . import standard
+# --- BEGIN: Injected by Copier ---
+# --- END: Injected by Copier ---
+
+from .decorators import *
+from .factories import *
+
+
+__version__: __.typx.Annotated[ str, __.dynadoc.Visibilities.Reveal ]
+__version__ = '1.2rc0'
+
+
+standard.dynadoc.assign_module_docstring( __name__, table = __.fragments )
+standard.reclassify_modules( __name__, recursive = True )

{classcore-1.1 → classcore-1.2rc0}/sources/classcore/decorators.py

@@ -21,17 +21,14 @@
 ''' Utilities for the decoration of classes, including metaclasses. '''
 
 
-from __future__ import annotations
-
 from . import __
 from . import nomina as _nomina
 from . import utilities as _utilities
 
 
-_T = __.typx.TypeVar( '_T', bound = type )
-
-
-def apply_decorators( cls: type, decorators: _nomina.Decorators ) -> type:
+def apply_decorators(
+    cls: type[ __.U ], decorators: _nomina.Decorators[ __.U ]
+) -> type:
     ''' Applies sequence of decorators to class.
 
         If decorators replace classes (e.g., ``dataclass( slots = True )``),
@@ -49,9 +46,9 @@ def apply_decorators( cls: type, decorators: _nomina.Decorators ) -> type:
 
 
 def decoration_by(
-    *decorators: _nomina.Decorator,
-    preparers: _nomina.DecorationPreparers = ( ),
-) -> _nomina.Decorator:
+    *decorators: _nomina.Decorator[ __.U ],
+    preparers: _nomina.DecorationPreparers[ __.U ] = ( ),
+) -> _nomina.Decorator[ __.U ]:
     ''' Class decorator which applies other class decorators.
 
         Useful to apply a stack of decorators as a sequence.
@@ -61,7 +58,7 @@ def decoration_by(
         decorators list itself, such as to inject decorators based on
         introspection of the class.
     '''
-    def decorate( cls: type ) -> type:
+    def decorate( cls: type[ __.U ] ) -> type[ __.U ]:
         decorators_ = list( decorators )
         for preparer in preparers: preparer( cls, decorators_ )
         return apply_decorators( cls, decorators_ )
@@ -71,24 +68,24 @@ def decoration_by(
 
 def produce_class_construction_decorator(
     attributes_namer: _nomina.AttributesNamer,
-    constructor: _nomina.ClassConstructor,
-) -> _nomina.Decorator:
+    constructor: _nomina.ClassConstructor[ __.T ],
+) -> _nomina.Decorator[ __.T ]:
     ''' Produces metaclass decorator to control class construction.
 
         Decorator overrides ``__new__`` on metaclass.
     '''
-    def decorate( clscls: type[ _T ] ) -> type[ _T ]:
+    def decorate( clscls: type[ __.T ] ) -> type[ __.T ]:
         constructor_name = attributes_namer( 'classes', 'constructor' )
         extant = getattr( clscls, constructor_name, None )
         original = getattr( clscls, '__new__' )
         if extant is original: return clscls
 
         def construct(
-            clscls_: type[ _T ],
+            clscls_: type[ __.T ],
             name: str,
             bases: tuple[ type, ... ],
             namespace: dict[ str, __.typx.Any ], *,
-            decorators: _nomina.Decorators = ( ),
+            decorators: _nomina.Decorators[ __.T ] = ( ),
             **arguments: __.typx.Any,
         ) -> type[ object ]:
             return constructor(
@@ -105,12 +102,12 @@ def produce_class_construction_decorator(
 def produce_class_initialization_decorator(
     attributes_namer: _nomina.AttributesNamer,
     initializer: _nomina.ClassInitializer,
-) -> _nomina.Decorator:
+) -> _nomina.Decorator[ __.T ]:
     ''' Produces metaclass decorator to control class initialization.
 
         Decorator overrides ``__init__`` on metaclass.
     '''
-    def decorate( clscls: type[ _T ] ) -> type[ _T ]:
+    def decorate( clscls: type[ __.T ] ) -> type[ __.T ]:
         initializer_name = attributes_namer( 'classes', 'initializer' )
         extant = getattr( clscls, initializer_name, None )
         original = getattr( clscls, '__init__' )

{classcore-1.1 → classcore-1.2rc0}/sources/classcore/exceptions.py

@@ -21,15 +21,13 @@
 ''' Exceptions from package. '''
 
 
-from __future__ import annotations
-
 from . import __
 from . import standard as _standard
 
 
-class Omniexception( # pyright: ignore[reportGeneralTypeIssues]
+class Omniexception(
     BaseException, _standard.Object,
-    instances_visibles = ( '__cause__', '__context__' ), # pyright: ignore[reportCallIssue]
+    instances_visibles = ( '__cause__', '__context__' ),
 ):
     ''' Base exception for package. '''
 

{classcore-1.1 → classcore-1.2rc0}/sources/classcore/factories.py

@@ -21,39 +21,35 @@
 ''' Factories which produce metaclass implementations. '''
 
 
-from __future__ import annotations
-
 from . import __
 from . import decorators as _decorators
 from . import nomina as _nomina
 from . import utilities as _utilities
 
 
-_T = __.typx.TypeVar( '_T', bound = type )
-
-
 def produce_class_constructor(
     attributes_namer: _nomina.AttributesNamer,
-    preprocessors: _nomina.ProduceConstructorPreprocsArgument = ( ),
-    postprocessors: _nomina.ProduceConstructorPostprocsArgument = ( ),
-) -> _nomina.ClassConstructor:
+    preprocessors: _nomina.ProduceConstructorPreprocsArgument[ __.T ] = ( ),
+    postprocessors: _nomina.ProduceConstructorPostprocsArgument[ __.T ] = ( ),
+) -> _nomina.ClassConstructor[ __.T ]:
     ''' Produces constructors for classes. '''
 
     def construct( # noqa: PLR0913
-        clscls: type[ _T ],
+        clscls: type[ __.T ],
         superf: _nomina.ClassConstructorLigation,
         name: str,
         bases: tuple[ type, ... ],
         namespace: dict[ str, __.typx.Any ],
         arguments: __.NominativeArguments,
-        decorators: _nomina.Decorators,
+        decorators: _nomina.Decorators[ __.T ],
     ) -> type:
         ''' Constructs class, applying decorators and hooks. '''
         bases_ = list( bases )
         arguments_ = dict( arguments )
         decorators_ = list( decorators )
-        for prep in preprocessors:
-            prep( clscls, name, bases_, namespace, arguments_, decorators_ )
+        for preprocessor in preprocessors:
+            preprocessor(
+                clscls, name, bases_, namespace, arguments_, decorators_ )
         cls = superf( clscls, name, tuple( bases_ ), namespace, **arguments_ )
         # Some decorators create new classes, which invokes this method again.
         # Short-circuit to prevent recursive decoration and other tangles.
@@ -62,7 +58,7 @@ def produce_class_constructor(
         in_progress = getattr( cls, progress_name_m, False )
         if in_progress: return cls
         setattr( cls, progress_name_m, True )
-        for postp in postprocessors: postp( cls, decorators_ )
+        for postprocessor in postprocessors: postprocessor( cls, decorators_ )
         cls = _decorators.apply_decorators( cls, decorators_ )
         setattr( cls, progress_name_m, False )
         return cls