classcore 1.6__tar.gz → 1.7__tar.gz

{classcore-1.6 → classcore-1.7}/.gitignore

@@ -1,4 +1,5 @@
 .env
+.claude
 .gemini
 .mcp.json
 .*.swp

{classcore-1.6 → classcore-1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classcore
-Version: 1.6
+Version: 1.7
 Summary: Foundational class factories and decorators.
 Project-URL: Homepage, https://github.com/emcd/python-classcore
 Project-URL: Documentation, https://emcd.github.io/python-classcore
@@ -110,14 +110,17 @@ modules.
 Installation 📦
 ===============================================================================
 
-Via `uv <https://github.com/astral-sh/uv/blob/main/README.md>`_ ``pip``
+Method: Install Python Package
+-------------------------------------------------------------------------------
+
+Install via `uv <https://github.com/astral-sh/uv/blob/main/README.md>`_ ``pip``
 command:
 
 ::
 
     uv pip install classcore
 
-Or, via ``pip``:
+Or, install via ``pip``:
 
 ::
 
@@ -217,6 +220,23 @@ Use Cases 🎯
 * 📦 **Frameworks**: Frameworks with controlled extension and modification.
 
 
+Contribution 🤝
+===============================================================================
+
+Contribution to this project is welcome! However, it must follow the `code of
+conduct
+<https://emcd.github.io/python-project-common/stable/sphinx-html/common/conduct.html>`_
+for the project.
+
+Please file bug reports and feature requests in the `issue tracker
+<https://github.com/emcd/python-classcore/issues>`_ or submit `pull
+requests <https://github.com/emcd/python-classcore/pulls>`_ to
+improve the source code or documentation.
+
+For development guidance and standards, please see the `development guide
+<https://emcd.github.io/python-classcore/stable/sphinx-html/contribution.html#development>`_.
+
+
 `More Flair <https://www.imdb.com/title/tt0151804/characters/nm0431918>`_
 ===============================================================================
 
@@ -257,24 +277,24 @@ Other Projects by This Author 🌟
 ===============================================================================
 
 
-* `python-absence <https://github.com/emcd/python-absence>`_ (`absence <https://pypi.org/project/absence/>`_ on PyPI) 
+* `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>`_ (`accretive <https://pypi.org/project/accretive/>`_ on PyPI) 
+* `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-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI) 
+* `python-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI)
 
   📝 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) 
+* `python-falsifier <https://github.com/emcd/python-falsifier>`_ (`falsifier <https://pypi.org/project/falsifier/>`_ 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>`_ (`frigid <https://pypi.org/project/frigid/>`_ on PyPI) 
+* `python-frigid <https://github.com/emcd/python-frigid>`_ (`frigid <https://pypi.org/project/frigid/>`_ 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>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI) 
+* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ 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>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI) 
+* `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.6 → classcore-1.7}/README.rst

@@ -81,14 +81,17 @@ modules.
 Installation 📦
 ===============================================================================
 
-Via `uv <https://github.com/astral-sh/uv/blob/main/README.md>`_ ``pip``
+Method: Install Python Package
+-------------------------------------------------------------------------------
+
+Install via `uv <https://github.com/astral-sh/uv/blob/main/README.md>`_ ``pip``
 command:
 
 ::
 
     uv pip install classcore
 
-Or, via ``pip``:
+Or, install via ``pip``:
 
 ::
 
@@ -188,6 +191,23 @@ Use Cases 🎯
 * 📦 **Frameworks**: Frameworks with controlled extension and modification.
 
 
+Contribution 🤝
+===============================================================================
+
+Contribution to this project is welcome! However, it must follow the `code of
+conduct
+<https://emcd.github.io/python-project-common/stable/sphinx-html/common/conduct.html>`_
+for the project.
+
+Please file bug reports and feature requests in the `issue tracker
+<https://github.com/emcd/python-classcore/issues>`_ or submit `pull
+requests <https://github.com/emcd/python-classcore/pulls>`_ to
+improve the source code or documentation.
+
+For development guidance and standards, please see the `development guide
+<https://emcd.github.io/python-classcore/stable/sphinx-html/contribution.html#development>`_.
+
+
 `More Flair <https://www.imdb.com/title/tt0151804/characters/nm0431918>`_
 ===============================================================================
 
@@ -228,24 +248,24 @@ Other Projects by This Author 🌟
 ===============================================================================
 
 
-* `python-absence <https://github.com/emcd/python-absence>`_ (`absence <https://pypi.org/project/absence/>`_ on PyPI) 
+* `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>`_ (`accretive <https://pypi.org/project/accretive/>`_ on PyPI) 
+* `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-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI) 
+* `python-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI)
 
   📝 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) 
+* `python-falsifier <https://github.com/emcd/python-falsifier>`_ (`falsifier <https://pypi.org/project/falsifier/>`_ 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>`_ (`frigid <https://pypi.org/project/frigid/>`_ on PyPI) 
+* `python-frigid <https://github.com/emcd/python-frigid>`_ (`frigid <https://pypi.org/project/frigid/>`_ 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>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI) 
+* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ 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>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI) 
+* `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.6 → classcore-1.7}/sources/classcore/__init__.py

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

{classcore-1.6 → classcore-1.7}/sources/classcore/standard/behaviors.py

@@ -272,6 +272,8 @@ def produce_class_construction_postprocessor(
             'instances_mutables', __.mutables_default )
         instances_visibles = arguments.get(
             'instances_visibles', __.visibles_default )
+        instances_ignore_init_arguments = arguments.get(
+            'instances_ignore_init_arguments', False )
         if dcls_spec and dcls_spec.get( 'kw_only_default', False ):
             from .decorators import dataclass_with_standard_behaviors
             decorator_factory = dataclass_with_standard_behaviors
@@ -289,6 +291,7 @@ def produce_class_construction_postprocessor(
                 _nomina.DeleterCore, cores[ 'deleter' ] ),
             surveyor_core = __.typx.cast(
                 _nomina.SurveyorCore, cores[ 'surveyor' ] ),
+            ignore_init_arguments = instances_ignore_init_arguments,
             mutables = instances_mutables,
             visibles = instances_visibles )
         decorators.append( decorator )
@@ -391,6 +394,7 @@ def record_class_construction_arguments(
         'instances_assigner_core',
         'instances_deleter_core',
         'instances_surveyor_core',
+        'instances_ignore_init_arguments',
         'instances_mutables', 'instances_visibles',
     ):
         if name not in arguments: continue

{classcore-1.6 → classcore-1.7}/sources/classcore/standard/classes.py

@@ -42,6 +42,7 @@ class ClassFactoryExtraArguments( __.typx.TypedDict, total = False ):
     instances_assigner_core: _nomina.AssignerCore
     instances_deleter_core: _nomina.DeleterCore
     instances_surveyor_core: _nomina.SurveyorCore
+    instances_ignore_init_arguments: bool
     instances_mutables: _nomina.BehaviorExclusionVerifiersOmni
     instances_visibles: _nomina.BehaviorExclusionVerifiersOmni
 

{classcore-1.6 → classcore-1.7}/sources/classcore/standard/decorators.py

@@ -220,15 +220,19 @@ def class_factory( # noqa: PLR0913
     return decorate
 
 
-def produce_instances_initialization_decorator( # noqa: PLR0913
+def produce_instances_inception_decorator( # noqa: PLR0913
     attributes_namer: _nomina.AttributesNamer,
     assigner_core: __.typx.Optional[ _nomina.AssignerCore ],
     deleter_core: __.typx.Optional[ _nomina.DeleterCore ],
     surveyor_core: __.typx.Optional[ _nomina.SurveyorCore ],
+    ignore_init_arguments: bool,
     mutables: _nomina.BehaviorExclusionVerifiersOmni,
     visibles: _nomina.BehaviorExclusionVerifiersOmni,
 ) -> _nomina.Decorator[ __.U ]:
-    ''' Produces decorator to inject '__init__' method into class. '''
+    ''' Produces decorator to inject '__new__' or '__init__' method.
+
+        Also handles common bookkeeping tasks.
+    '''
     cores = dict(
         instances_assigner_core = assigner_core,
         instances_deleter_core = deleter_core,
@@ -249,7 +253,6 @@ def produce_instances_initialization_decorator( # noqa: PLR0913
             core_aname = attributes_namer( 'instances', f"{core_name}_core" )
             setattr( cls, core_aname, core_function )
         behaviors: set[ str ] = set( )
-        behaviors_name = attributes_namer( 'instance', 'behaviors' )
         _behaviors.record_behavior(
             cls, attributes_namer = attributes_namer,
             level = 'instances', basename = 'mutables',
@@ -260,6 +263,66 @@ def produce_instances_initialization_decorator( # noqa: PLR0913
             level = 'instances', basename = 'visibles',
             label = _nomina.concealment_label, behaviors = behaviors,
             verifiers = visibles )
+        decorator = produce_instances_initialization_decorator(
+            attributes_namer = attributes_namer,
+            behaviors = behaviors,
+            ignore_init_arguments = ignore_init_arguments )
+        return decorator( cls )
+
+    return decorate
+
+
+# def produce_instances_construction_decorator(
+#     attributes_namer: _nomina.AttributesNamer,
+#     behaviors: __.cabc.MutableSet[ str ],
+# ) -> _nomina.Decorator[ __.U ]:
+#     ''' Produces decorator to inject '__new__' method. '''
+#     def decorate( cls_: type[ __.U ] ) -> type[ __.U ]:
+#         behaviors_name = attributes_namer( 'instance', 'behaviors' )
+#         original = cls_.__dict__.get( '__new__' )
+#
+#         if original is None:
+#
+#             def initialize_with_super(
+#                 cls: type[ __.U ],
+#                 *posargs: __.typx.Any,
+#                 **nomargs: __.typx.Any,
+#             ) -> __.U:
+#                 self = super( cls_, cls ).__new__( cls, *posargs, **nomargs )
+#                 _activate_instance_behaviors(
+#                     cls_, self, behaviors_name, behaviors )
+#                 return self
+#
+#             cls_.__new__ = initialize_with_super
+#
+#         else:
+#
+#             @__.funct.wraps( original )
+#             def initialize_with_original(
+#                 cls: type[ __.U ],
+#                 *posargs: __.typx.Any,
+#                 **nomargs: __.typx.Any,
+#             ) -> __.U:
+#                 self = original( cls, *posargs, **nomargs )
+#                 _activate_instance_behaviors(
+#                     cls_, self, behaviors_name, behaviors )
+#                 return self
+#
+#             cls_.__new__ = initialize_with_original
+#
+#         return cls_
+#
+#     return decorate
+
+
+def produce_instances_initialization_decorator(
+    attributes_namer: _nomina.AttributesNamer,
+    behaviors: __.cabc.MutableSet[ str ],
+    ignore_init_arguments: bool,
+) -> _nomina.Decorator[ __.U ]:
+    ''' Produces decorator to inject '__init__' method into class. '''
+    def decorate( cls: type[ __.U ] ) -> type[ __.U ]:
+        behaviors_name = attributes_namer( 'instance', 'behaviors' )
         original = cls.__dict__.get( '__init__' )
 
         if original is None:
@@ -267,14 +330,10 @@ def produce_instances_initialization_decorator( # noqa: PLR0913
             def initialize_with_super(
                 self: object, *posargs: __.typx.Any, **nomargs: __.typx.Any
             ) -> None:
-                super( cls, self ).__init__( *posargs, **nomargs )
-                # Only record behaviors at start of MRO.
-                if cls is not type( self ): return
-                behaviors_: set[ str ] = (
-                    _utilities.getattr0( self, behaviors_name, set( ) ) )
-                behaviors_.update( behaviors )
-                _utilities.setattr0(
-                    self, behaviors_name, frozenset( behaviors_ ) )
+                if ignore_init_arguments: super( cls, self ).__init__( )
+                else: super( cls, self ).__init__( *posargs, **nomargs )
+                _activate_instance_behaviors(
+                    cls, self, behaviors_name, behaviors )
 
             cls.__init__ = initialize_with_super
 
@@ -284,14 +343,10 @@ def produce_instances_initialization_decorator( # noqa: PLR0913
             def initialize_with_original(
                 self: object, *posargs: __.typx.Any, **nomargs: __.typx.Any
             ) -> None:
-                original( self, *posargs, **nomargs )
-                # Only record behaviors at start of MRO.
-                if cls is not type( self ): return
-                behaviors_: set[ str ] = (
-                    _utilities.getattr0( self, behaviors_name, set( ) ) )
-                behaviors_.update( behaviors )
-                _utilities.setattr0(
-                    self, behaviors_name, frozenset( behaviors_ ) )
+                if ignore_init_arguments: original( self )
+                else: original( self, *posargs, **nomargs )
+                _activate_instance_behaviors(
+                    cls, self, behaviors_name, behaviors )
 
             cls.__init__ = initialize_with_original
 
@@ -484,6 +539,7 @@ def dataclass_with_standard_behaviors( # noqa: PLR0913
     assigner_core: __.typx.Optional[ _nomina.AssignerCore ] = None,
     deleter_core: __.typx.Optional[ _nomina.DeleterCore ] = None,
     surveyor_core: __.typx.Optional[ _nomina.SurveyorCore ] = None,
+    ignore_init_arguments: bool = False,
     mutables: _nomina.BehaviorExclusionVerifiersOmni = __.mutables_default,
     visibles: _nomina.BehaviorExclusionVerifiersOmni = __.visibles_default,
 ) -> _nomina.Decorator[ __.U ]:
@@ -496,6 +552,7 @@ def dataclass_with_standard_behaviors( # noqa: PLR0913
             assigner_core = assigner_core,
             deleter_core = deleter_core,
             surveyor_core = surveyor_core,
+            ignore_init_arguments = ignore_init_arguments,
             mutables = mutables,
             visibles = visibles ) )
     preparers: _nomina.DecorationPreparers[ __.U ] = (
@@ -514,6 +571,7 @@ def with_standard_behaviors( # noqa: PLR0913
     assigner_core: __.typx.Optional[ _nomina.AssignerCore ] = None,
     deleter_core: __.typx.Optional[ _nomina.DeleterCore ] = None,
     surveyor_core: __.typx.Optional[ _nomina.SurveyorCore ] = None,
+    ignore_init_arguments: bool = False,
     mutables: _nomina.BehaviorExclusionVerifiersOmni = __.mutables_default,
     visibles: _nomina.BehaviorExclusionVerifiersOmni = __.visibles_default,
 ) -> _nomina.Decorator[ __.U ]:
@@ -525,6 +583,7 @@ def with_standard_behaviors( # noqa: PLR0913
             assigner_core = assigner_core,
             deleter_core = deleter_core,
             surveyor_core = surveyor_core,
+            ignore_init_arguments = ignore_init_arguments,
             mutables = mutables,
             visibles = visibles ) )
     preparers: _nomina.DecorationPreparers[ __.U ] = (
@@ -534,6 +593,20 @@ def with_standard_behaviors( # noqa: PLR0913
     return decoration_by( *decorators, *decorators_, preparers = preparers )
 
 
+def _activate_instance_behaviors(
+    cls: type[ __.U ],
+    self: object,
+    behaviors_name: str,
+    behaviors: __.cabc.MutableSet[ str ],
+) -> None:
+    # Only record behaviors at start of MRO.
+    if cls is not type( self ): return
+    behaviors_: set[ str ] = (
+        _utilities.getattr0( self, behaviors_name, set( ) ) )
+    behaviors_.update( behaviors )
+    _utilities.setattr0( self, behaviors_name, frozenset( behaviors_ ) )
+
+
 def _produce_instances_decoration_preparers(
     attributes_namer: _nomina.AttributesNamer,
     error_class_provider: _nomina.ErrorClassProvider,
@@ -554,17 +627,19 @@ def _produce_instances_decorators( # noqa: PLR0913
     assigner_core: __.typx.Optional[ _nomina.AssignerCore ],
     deleter_core: __.typx.Optional[ _nomina.DeleterCore ],
     surveyor_core: __.typx.Optional[ _nomina.SurveyorCore ],
+    ignore_init_arguments: bool,
     mutables: _nomina.BehaviorExclusionVerifiersOmni,
     visibles: _nomina.BehaviorExclusionVerifiersOmni,
 ) -> _nomina.Decorators[ __.U ]:
     ''' Produces standard decorators. '''
     decorators: list[ _nomina.Decorator[ __.U ] ] = [ ]
     decorators.append(
-        produce_instances_initialization_decorator(
+        produce_instances_inception_decorator(
             attributes_namer = attributes_namer,
             assigner_core = assigner_core,
             deleter_core = deleter_core,
             surveyor_core = surveyor_core,
+            ignore_init_arguments = ignore_init_arguments,
             mutables = mutables, visibles = visibles ) )
     decorators.append(
         produce_attributes_assignment_decorator(

{classcore-1.6 → classcore-1.7}/sources/classcore/standard/modules.py

@@ -81,7 +81,7 @@ def finalize_module( # noqa: PLR0913
         *fragments,
         introspection = introspection,
         table = dynadoc_table )
-    reclassify_modules(
+    _reclassify_module(
         module,
         attributes_namer = attributes_namer,
         recursive = recursive,
@@ -108,7 +108,6 @@ def reclassify_modules(
         __.ddoc.Doc( ''' New class for module. ''' ),
     ] = Module,
 ) -> None:
-    # TODO? Ensure correct operation with namespace packages.
     ''' Reclassifies modules to have attributes concealment and immutability.
 
         Can operate on individual modules or entire package hierarchies.
@@ -121,6 +120,46 @@ def reclassify_modules(
 
         Has no effect on already-reclassified modules.
     '''
+    _reclassify_module(
+        attributes,
+        attributes_namer = attributes_namer,
+        recursive = recursive,
+        replacement_class = replacement_class )
+
+
+def _reclassify_module(
+    attributes: __.typx.Annotated[
+        __.cabc.Mapping[ str, __.typx.Any ] | __.types.ModuleType | str,
+        __.ddoc.Doc(
+            ''' Module, module name, or dictionary of object attributes. ''' ),
+    ], /, *,
+    attributes_namer: __.typx.Annotated[
+        _nomina.AttributesNamer,
+        __.ddoc.Doc(
+            ''' Attributes namer function with which to seal class. ''' ),
+    ] = __.calculate_attrname,
+    recursive: __.typx.Annotated[
+        bool, __.ddoc.Doc( ''' Recursively reclassify package modules? ''' )
+    ] = False,
+    replacement_class: __.typx.Annotated[
+        type[ __.types.ModuleType ],
+        __.ddoc.Doc( ''' New class for module. ''' ),
+    ] = Module,
+) -> None:
+    # TODO? Ensure correct operation with namespace packages.
+    ''' Core implementation for module reclassification.
+
+        Reclassifies modules to have attributes concealment and immutability.
+        Can operate on individual modules or entire package hierarchies.
+
+        Only converts modules within the same package to prevent unintended
+        modifications to external modules.
+
+        When used with a dictionary, converts any module objects found as
+        values if they belong to the same package.
+
+        Has no effect on already-reclassified modules.
+    '''
     if isinstance( attributes, str ):
         attributes = __.sys.modules[ attributes ]
     if isinstance( attributes, __.types.ModuleType ):
@@ -134,7 +173,7 @@ def reclassify_modules(
         if not __.inspect.ismodule( value ): continue
         if not value.__name__.startswith( f"{package_name}." ): continue
         if recursive:
-            reclassify_modules(
+            _reclassify_module(
                 value,
                 attributes_namer = attributes_namer,
                 recursive = True,