classcore 1.11__tar.gz → 1.13__tar.gz

{classcore-1.11 → classcore-1.13}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: classcore
-Version: 1.11
+Version: 1.13
 Summary: Foundational class factories and decorators.
 Project-URL: Homepage, https://github.com/emcd/python-classcore
 Project-URL: Documentation, https://emcd.github.io/python-classcore
@@ -15,15 +15,13 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Requires-Dist: dynadoc~=1.4
 Requires-Dist: typing-extensions
 Description-Content-Type: text/x-rst

{classcore-1.11 → classcore-1.13}/pyproject.toml

@@ -13,7 +13,7 @@ description = 'Foundational class factories and decorators.'
 dynamic = [ 'version' ]
 license = 'Apache-2.0'
 readme = { 'file' = 'README.rst', 'content-type' = 'text/x-rst' }
-requires-python = '>= 3.10'
+requires-python = '>= 3.12'
 dependencies = [
   'dynadoc ~= 1.4',
   'typing-extensions',
@@ -26,13 +26,11 @@ classifiers = [ # https://pypi.org/classifiers
   'License :: OSI Approved :: Apache Software License',
   'Programming Language :: Python :: 3 :: Only',
   # --- BEGIN: Injected by Copier ---
-  'Programming Language :: Python :: 3.10',
-  'Programming Language :: Python :: 3.11',
   'Programming Language :: Python :: 3.12',
   'Programming Language :: Python :: 3.13',
   'Programming Language :: Python :: 3.14',
+  'Programming Language :: Python :: 3.15',
   'Programming Language :: Python :: Implementation :: CPython',
-  'Programming Language :: Python :: Implementation :: PyPy',
   # --- END: Injected by Copier ---
   'Topic :: Software Development',
 ]
@@ -91,7 +89,7 @@ strict-naming = false
 # --- BEGIN: Injected by Copier ---
 # --- END: Injected by Copier ---
 [tool.hatch.envs.default]
-python = '3.10'
+python = '3.12'
 [tool.hatch.envs.develop]
 description = ''' Development environment. '''
 builder = true
@@ -127,6 +125,12 @@ docsgen = [
   """sphinx-build -a -d .auxiliary/caches/sphinx --quiet \
       documentation .auxiliary/artifacts/sphinx-html""",
 ]
+fragments = [
+  """python .auxiliary/scripts/validate-fragments.py""",
+]
+module-sizes = [
+  """python .auxiliary/scripts/validate-module-sizes.py""",
+]
 linters = [
   """ruff check --quiet sources documentation tests""",
   # """vibelinter check""",
@@ -134,6 +138,8 @@ linters = [
   # --- END: Injected by Copier ---
   """isort --check-only --diff sources tests""",
   """pyright sources""",
+  'fragments',
+  'module-sizes',
 ]
 packagers = [
   """hatch build""",
@@ -170,12 +176,10 @@ description = ''' Quality assurance environment. '''
 template = 'develop'
 [[tool.hatch.envs.qa.matrix]]
 python = [
-    '3.10',
-    '3.11',
     '3.12',
     '3.13',
     '3.14',
-    'pypy3.11',
+    '3.15',
 ]
 # [tool.hatch.metadata]
 # allow-direct-references = true
@@ -255,6 +259,7 @@ cache_dir = '.auxiliary/caches/pytest'
 markers = [
     "slow: long-running tests",
 ]
+asyncio_default_fixture_loop_scope = "function"
 
 [tool.ruff]
 #builtins = [ 'ic' ]

{classcore-1.11 → classcore-1.13}/sources/classcore/README.md

@@ -83,19 +83,20 @@ Pre-configured implementations for common use cases:
 **Base Classes:**
 - `Object`: Standard class with immutability and concealment
 - `DataclassObject`: Automatic dataclass conversion with standard behaviors
-- `ProtocolObject`: Protocol class with immutability and concealment
+- `Protocol`: Protocol base class with immutability and concealment
+- `AbstractObject`: Abstract class with ABC machinery and behaviors
 - Variants for selective mutability (`ObjectMutable`, etc.)
 
 **Metaclasses:**
 - `Class`: Metaclass for standard classes
 - `Dataclass`: Metaclass that auto-applies dataclass decorator
-- `Protocol`: Metaclass for protocol classes
+- `AbstractClass`: Metaclass combining `Class` with `abc.ABCMeta`
+- `ProtocolClass`: Metaclass for protocol classes
 - Mutable variants of each
 
 **Decorators:**
-- `class_with_standard_behaviors`: Add behaviors to existing classes
+- `with_standard_behaviors`: Add behaviors to existing classes
 - `dataclass_with_standard_behaviors`: Dataclass creation with behaviors
-- `protocol_with_standard_behaviors`: Protocol creation with behaviors
 
 **Module Utilities:**
 - `reclassify_module`: Apply immutability and concealment to module objects
@@ -296,6 +297,7 @@ sources/
         ├── classes.py           # Standard metaclasses and base classes
         ├── decorators.py        # Standard class decorators
         ├── dynadoc.py           # Documentation configuration
+        ├── explanations.py      # Attribute behavior explanations
         ├── modules.py           # Module reclassification utilities
         └── nomina.py            # Standard-specific naming types
 ```
@@ -377,20 +379,38 @@ sources/
   - `survey_visible_attributes`: Filter attributes for `dir()`
   - Verifier processing for names, regexes, and predicates
 
+`explanations.py`
+: Explanations of attribute behavior decisions:
+
+  - `explain_attribute`: Decision trace for one attribute of one target
+  - `AttributeExplanation` and the `Verdict` records (`AssignVerdict`,
+    `DeleteVerdict`, `SurveyVerdict`) with derived permissibility
+  - The closed `Decision` hierarchy: `PermitByInapplicability`,
+    `PermitByOmni`, `PermitByNames`, `PermitByPredicate`,
+    `PermitByRegex`, `Prohibit`, with typed payloads
+  - Internal marking via metaclass-carried contributions: the namer
+    detector for framework names, the abstract-base wiring for stdlib
+    ABC machinery (only where that machinery operates), and downstream
+    factory namers' detectors for downstream names
+
 `classes.py`
 : Standard metaclasses and base classes:
 
   - `Class` / `Object`: Standard class with full behaviors
+  - `AbstractClass` / `AbstractObject`: Abstract class with ABC machinery
+    (abstract method enforcement, virtual subclass registration); mixes
+    with external `abc.ABCMeta`-based classes
   - `Dataclass` / `DataclassObject`: Auto-dataclass with behaviors
-  - `Protocol` / `ProtocolObject`: Protocol with behaviors
+  - `ProtocolClass` / `Protocol`, `ProtocolMutable`,
+    `DataclassProtocol`, `DataclassProtocolMutable`: Protocol classes
+    with behaviors
   - Mutable variants for each
 
 `decorators.py`
 : Standard class decorators:
 
-  - `class_with_standard_behaviors`: Apply behaviors to existing class
+  - `with_standard_behaviors`: Apply behaviors to existing class
   - `dataclass_with_standard_behaviors`: Create dataclass with behaviors
-  - `protocol_with_standard_behaviors`: Create protocol with behaviors
   - `class_factory`: Generic factory for creating custom metaclasses
 
 `dynadoc.py`

{classcore-1.11 → classcore-1.13}/sources/classcore/__/imports.py

@@ -23,6 +23,7 @@
 # ruff: noqa: F401
 
 
+import                      abc
 import collections.abc as   cabc
 import dataclasses as       dcls
 import functools as         funct

classcore-1.13/sources/classcore/__/nomina.py

@@ -0,0 +1,95 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Common names and type aliases. '''
+
+
+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 ]
+
+
+package_name = __name__.split( '.', maxsplit = 1 )[ 0 ]
+
+
+_levels = frozenset( ( 'class', 'classes', 'instance', 'instances' ) )
+_cores = frozenset( (
+    'behaviors',
+    'construction_arguments',
+    'dynadoc_configuration',
+    'in_progress',
+    'mutables_names', 'mutables_predicates', 'mutables_regexes',
+    'visibles_names', 'visibles_predicates', 'visibles_regexes',
+    'assigner_core', 'deleter_core', 'surveyor_core' ) )
+_hex_digits = frozenset( '0123456789abcdef' )
+_digest_length = 64
+_mangled_cores = frozenset( ( 'class_behaviors', 'class_in_progress' ) )
+
+
+class AttrnameCalculator:
+    ''' Calculates framework attribute names from level and core.
+
+        Reference implementation of the attribute namer convention:
+        call instances to produce names, and consult ``is_internal_name``
+        to detect names this framework generated. Downstream packages
+        may subclass (or otherwise provide callables exposing the same
+        optional detector) to contribute their own internal names.
+    '''
+
+    def is_internal_name( self, name: str ) -> bool:
+        prefix = f"_{package_name}_"
+        if not name.startswith( prefix ):
+            return False
+        body = name[ len( prefix ): ]
+        # Static stems: _{package}_{level}_{core}_, trailing underscore.
+        # The class-level behaviors and in_progress stems are stored
+        # mangled only, so they are excluded from static acceptance.
+        if body.endswith( '_' ):
+            level, _, core = body[ :-1 ].partition( '_' )
+            if level in _levels and core in _cores:
+                return not (
+                    'class' == level
+                    and f"{level}_{core}" in _mangled_cores )
+            return False
+        # Mangled forms: one of the mangled cores + 64 lowercase hex,
+        # no trailing underscore. The mangling accessors append digests
+        # to these stems only.
+        for mangled_core in _mangled_cores:
+            mangled_prefix = f"{mangled_core}_"
+            if body.startswith( mangled_prefix ):
+                suffix = body[ len( mangled_prefix ): ]
+                return (
+                    _digest_length == len( suffix )
+                    and all( c in _hex_digits for c in suffix ) )
+        return False
+
+    def __call__( self, level: str, core: str ) -> str:
+        return f"_{package_name}_{level}_{core}_"
+
+
+calculate_attrname = AttrnameCalculator( )
+
+
+def calculate_contribution_name( ) -> str:
+    ''' Returns metaclass attribute name holding internal-name detectors. '''
+    return f"_{package_name}_internal_names_"

{classcore-1.11 → classcore-1.13}/sources/classcore/__init__.py

@@ -62,7 +62,7 @@ from .factories import *
 
 
 __version__: __.typx.Annotated[ str, __.ddoc.Visibilities.Reveal ]
-__version__ = '1.11'
+__version__ = '1.13'
 
 
 standard.finalize_module(

{classcore-1.11 → classcore-1.13}/sources/classcore/decorators.py

@@ -89,8 +89,14 @@ def produce_class_construction_decorator(
                 decorators: _nomina.Decorators[ __.T ] = ( ),
                 **arguments: __.typx.Any,
             ) -> type[ object ]:
-                superf = super( clscls, clscls_ ).__new__
-                # TODO? Short-circuit if not at start of MRO.
+                superf = __.typx.cast(
+                    _nomina.ClassConstructorLigation,
+                    super( clscls, clscls_ ).__new__ )
+                if clscls is not clscls_:
+                    # Parent metaclass within a hierarchy: delegate without
+                    # duplicating preprocessing or decoration.
+                    return superf(
+                        clscls_, name, bases, namespace, **arguments )
                 return constructor(
                     clscls_, superf,
                     name, bases, namespace, arguments, decorators )
@@ -107,7 +113,11 @@ def produce_class_construction_decorator(
                 decorators: _nomina.Decorators[ __.T ] = ( ),
                 **arguments: __.typx.Any,
             ) -> type[ object ]:
-                # TODO? Short-circuit if not at start of MRO.
+                if clscls is not clscls_:
+                    # Parent metaclass within a hierarchy: delegate without
+                    # duplicating preprocessing or decoration.
+                    return original(
+                        clscls_, name, bases, namespace, **arguments )
                 return constructor(
                     clscls_, original,
                     name, bases, namespace, arguments, decorators )
@@ -138,7 +148,11 @@ def produce_class_initialization_decorator(
                 cls: type, *posargs: __.typx.Any, **nomargs: __.typx.Any
             ) -> None:
                 ligation = super( clscls, cls ).__init__
-                # TODO? Short-circuit if not at start of MRO.
+                if clscls is not type( cls ):
+                    # Parent metaclass within a hierarchy: delegate without
+                    # duplicating completion logic.
+                    ligation( *posargs, **nomargs )
+                    return
                 initializer( cls, ligation, posargs, nomargs )
 
             clscls.__init__ = initialize_with_super
@@ -149,8 +163,12 @@ def produce_class_initialization_decorator(
             def initialize_with_original(
                 cls: type, *posargs: __.typx.Any, **nomargs: __.typx.Any
             ) -> None:
+                if clscls is not type( cls ):
+                    # Parent metaclass within a hierarchy: delegate without
+                    # duplicating completion logic.
+                    original( cls, *posargs, **nomargs )
+                    return
                 ligation = __.funct.partial( original, cls )
-                # TODO? Short-circuit if not at start of MRO.
                 initializer( cls, ligation, posargs, nomargs )
 
             clscls.__init__ = initialize_with_original

{classcore-1.11 → classcore-1.13}/sources/classcore/factories.py

@@ -34,7 +34,7 @@ def produce_class_constructor(
 ) -> _nomina.ClassConstructor[ __.T ]:
     ''' Produces constructors for classes. '''
 
-    def construct( # noqa: PLR0913
+    def construct( # noqa: PLR0913, PLR0917
         clscls: type[ __.T ],
         superf: _nomina.ClassConstructorLigation,
         name: str,
@@ -54,12 +54,20 @@ def produce_class_constructor(
         # Some decorators create new classes, which invokes this method again.
         # Short-circuit to prevent recursive decoration and other tangles.
         progress_name = attributes_namer( 'class', 'in_progress' )
-        progress_name_m = _utilities.mangle_name( cls, progress_name )
-        in_progress = getattr( cls, progress_name_m, False )
+        progress_names = _utilities.survey_mangled_names( cls, progress_name )
+        in_progress = any(
+            getattr( cls, key, False ) for key in progress_names )
         if in_progress: return cls
+        progress_name_m = _utilities.mangle_name( cls, progress_name )
         setattr( cls, progress_name_m, True )
         for postprocessor in postprocessors: postprocessor( cls, decorators_ )
         cls = _decorators.apply_decorators( cls, decorators_ )
+        # Decoration may have replaced the class. Clear every marker
+        # variant, including ones inherited from the original namespace,
+        # so initialization completes regardless of qualname restoration.
+        progress_names = _utilities.survey_mangled_names( cls, progress_name )
+        for progress_name_ in progress_names:
+            setattr( cls, progress_name_, False )
         setattr( cls, progress_name_m, False )
         return cls
 
@@ -81,10 +89,11 @@ def produce_class_initializer(
         ''' Initializes class, applying hooks. '''
         superf( *posargs, **nomargs )
         progress_name = attributes_namer( 'class', 'in_progress' )
-        progress_name_m = _utilities.mangle_name( cls, progress_name )
-        in_progress = getattr( cls, progress_name_m, False )
+        progress_names = _utilities.survey_mangled_names( cls, progress_name )
+        in_progress = any(
+            getattr( cls, key, False ) for key in progress_names )
         if in_progress: return # If non-empty, then not top-level.
-        delattr( cls, progress_name_m )
+        for progress_name_m in progress_names: delattr( cls, progress_name_m )
         for completer in completers: completer( cls )
 
     return initialize

{classcore-1.11 → classcore-1.13}/sources/classcore/nomina.py

@@ -214,29 +214,52 @@ ClassInitializationCompleters: __.typx.TypeAlias = __.typx.Annotated[
 ClassConstructor: __.typx.TypeAlias = __.typx.Annotated[
     __.cabc.Callable[
         [
-            type,
-            ClassConstructorLigation,
-            str,
-            tuple[ type, ... ],
-            dict[ str, __.typx.Any ],
-            __.NominativeArguments,
-            Decorators[ __.U ],
+            type,                        # metaclass
+            ClassConstructorLigation,    # next constructor in metaclass MRO
+            str,                         # class name
+            tuple[ type, ... ],          # bases
+            dict[ str, __.typx.Any ],    # namespace
+            __.NominativeArguments,      # metaclass arguments
+            Decorators[ __.U ],          # decorators to apply after
         ],
         type
     ],
-    __.ddoc.Doc( ''' Constructor to use with metaclass. ''' ),
+    __.ddoc.Doc(
+        ''' Constructs class, then applies hooks.
+
+            Receives the metaclass ('clscls'), the next constructor in
+            the metaclass MRO ('superf'), the class name, bases,
+            namespace, metaclass arguments, and decorators to apply
+            after construction. Calls 'superf' to create the class,
+            then applies postprocessors and decorators.
+
+            Invoked only at the most-derived metaclass of a class.
+            Class factory wrappers on parent metaclasses delegate
+            directly, so construction hooks execute exactly once per
+            class.
+        ''' ),
 ]
 ClassInitializer: __.typx.TypeAlias = __.typx.Annotated[
     __.cabc.Callable[
         [
-            type,
-            InitializerLigation,
-            __.PositionalArguments,
-            __.NominativeArguments,
+            type,                        # class
+            InitializerLigation,         # next initializer in metaclass MRO
+            __.PositionalArguments,      # positional arguments
+            __.NominativeArguments,      # nominative arguments
         ],
         None
     ],
-    __.ddoc.Doc( ''' Initializer to use with metaclass. ''' ),
+    __.ddoc.Doc(
+        ''' Initializes class, then applies hooks.
+
+            Receives the class ('cls'), the next initializer in the
+            metaclass MRO ('superf'), positional arguments, and
+            nominative arguments. Calls 'superf' first, then applies
+            completers, which finalize class behaviors (e.g., enable
+            immutability once all other initialization has occurred).
+
+            Invoked only at the most-derived metaclass of a class.
+        ''' ),
 ]
 
 

{classcore-1.11 → classcore-1.13}/sources/classcore/standard/README.md

@@ -40,17 +40,27 @@ class Point2d(DataclassObject):
         self.hypotenuse = sqrt(x*x + y*y)
 ```
 
-### `ProtocolObject`
+### `Protocol`
+
+Protocol base class with immutability and concealment. Combines
+`typing.Protocol` with standard behaviors. Immutability and concealment
+are inherited by subclassed implementations. Dataclass protocol bases
+(`DataclassProtocol`, `DataclassProtocolMutable`) additionally provide
+automatic dataclass conversion.
 
-Protocol class with immutability and concealment. Combines `typing.Protocol`
-with standard behaviors. Immutability and concealment are inherited by
-subclassed implementations.
+### `AbstractObject`
+
+Abstract base class with immutability and concealment. Combines standard
+behaviors with `abc.ABCMeta` machinery: abstract method enforcement and
+virtual subclass registration. Mixes with external ABC-based classes
+without metaclass conflicts.
 
 ### Mutable Variants
 
 - `ObjectMutable`: Object with concealment only (no immutability)
 - `DataclassObjectMutable`: DataclassObject with concealment only
-- `ProtocolObjectMutable`: ProtocolObject with concealment only
+- `ProtocolMutable`: Protocol with concealment only
+- `DataclassProtocolMutable`: DataclassProtocol with concealment only
 
 ## Metaclasses
 
@@ -64,27 +74,35 @@ any class that uses this metaclass.
 Metaclass that automatically applies `dataclasses.dataclass` during class
 construction. Configurable for `frozen`, `slots`, etc.
 
-### `Protocol`
+### `AbstractClass`
+
+Metaclass combining `Class` with `abc.ABCMeta`. Supports abstract method
+enforcement and virtual subclass registration for classes that must mix
+with external ABC-based classes.
+
+### `ProtocolClass`
 
 Metaclass for protocol classes. Combines `typing.Protocol` with standard
-behaviors.
+behaviors. Descends from `AbstractClass`, unifying the standard metaclass
+taxonomy under `Class`. Dataclass protocol metaclasses
+(`ProtocolDataclass`, `ProtocolDataclassMutable`) additionally apply
+dataclass conversion.
 
 ### Mutable Variants
 
-- `ClassMutable`: Metaclass with concealment only
-- `DataclassMutable`: Dataclass metaclass with concealment only
-- `ProtocolMutable`: Protocol metaclass with concealment only
+- `DataclassMutable`: Dataclass metaclass whose instances have mutable
+  attributes (concealment only)
 
 ## Decorators
 
-### `class_with_standard_behaviors`
+### `with_standard_behaviors`
 
 Apply standard behaviors to an existing class.
 
 ```python
-from classcore.standard import class_with_standard_behaviors
+from classcore.standard import with_standard_behaviors
 
-@class_with_standard_behaviors()
+@with_standard_behaviors()
 class ExistingClass:
     x: int = 10
 ```
@@ -102,10 +120,6 @@ class Point:
     y: float
 ```
 
-### `protocol_with_standard_behaviors`
-
-Create a protocol with standard behaviors applied.
-
 ### `class_factory`
 
 Generic factory for creating custom metaclasses with standard behaviors.

classcore-1.13/sources/classcore/standard/__.py

@@ -0,0 +1,106 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Common constants, imports, and utilities. '''
+
+# ruff: noqa: F403, F405
+
+
+from ..__ import *
+from ..nomina import is_public_identifier
+
+
+def provide_error_class( name: str ) -> type[ Exception ]:
+    ''' Produces error class for this package. '''
+    match name:
+        case 'AttributeImmutability':
+            from ..exceptions import AttributeImmutability as error
+        case _:
+            from ..exceptions import ErrorProvideFailure
+            raise ErrorProvideFailure( name, reason = 'Does not exist.' )
+    return error
+
+
+mutables_default = ( )
+visibles_default = ( is_public_identifier, )
+
+# Standard library ABC machinery attribute names which the class-level
+# immutability behavior permits. The C _abc implementation writes these
+# cache attributes through direct dict access, so they must remain
+# assignable on standard classes. Also used to mark such names as
+# internal in attribute explanations.
+abc_class_mutables = (
+    '_abc_cache',
+    '_abc_negative_cache',
+    '_abc_negative_cache_version',
+    '_abc_registry',
+)
+# Standard library typing machinery attribute names which the
+# class-level immutability behavior permits on protocol classes.
+# 'typing' sets these protocol bookkeeping attributes during class
+# decoration: '_is_runtime_protocol' and '__non_callable_proto_members__'
+# in the 'runtime_checkable' decorator, and
+# '__typing_is_deprecated_inherited_runtime_protocol__' (CPython 3.15+)
+# during class decoration and in 'runtime_checkable'. Without this
+# exemption, decorating a runtime protocol which inherits runtime
+# checkability fails. Also used to mark such names as internal in
+# attribute explanations.
+typing_class_mutables = (
+    '_is_runtime_protocol',
+    '__non_callable_proto_members__',
+    '__typing_is_deprecated_inherited_runtime_protocol__', # Python 3.15+
+)
+
+
+def is_same_detector(
+    detector: cabc.Callable[ [ str ], bool ],
+    other: cabc.Callable[ [ str ], bool ], /,
+) -> bool:
+    ''' Returns whether two detector references are the same detector.
+
+        Bound methods are the same detector only when both the
+        underlying function and the bound instance are identical, so
+        distinct namer instances with distinct configured behavior keep
+        separate contributions. Plain callables compare by identity.
+    '''
+    if detector is other: return True
+    function = getattr( detector, '__func__', None )
+    other_function = getattr( other, '__func__', None )
+    if function is None or other_function is None: return False
+    return (
+        function is other_function
+        and getattr( detector, '__self__', None )
+            is getattr( other, '__self__', None ) )
+
+
+def augment_internal_names(
+    cls: type, /, detector: cabc.Callable[ [ str ], bool ]
+) -> None:
+    ''' Adds an internal-name detector to existing contributions.
+
+        Private wiring point for machinery mixins: the abstract-base
+        metaclass adds the stdlib machinery set after factory
+        decoration, without expanding public factory arguments.
+    '''
+    detectors = getattr( cls, calculate_contribution_name( ), ( ) )
+    if any( is_same_detector( detector, d ) for d in detectors ): return
+    setattr(
+        cls, calculate_contribution_name( ),
+        ( *detectors, detector ) )

{classcore-1.11 → classcore-1.13}/sources/classcore/standard/__init__.py

@@ -49,4 +49,5 @@ from . import nomina
 
 from .classes import *
 from .decorators import *
+from .explanations import *
 from .modules import *