classcore 1.0rc0__py3-none-any.whl

classcore/__/__init__.py

@@ -0,0 +1,25 @@
+# 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. '''
+
+
+from .imports import *
+from .nomina import *

classcore/__/imports.py

@@ -0,0 +1,42 @@
+# 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 imports and type aliases used throughout the package. '''
+
+# ruff: noqa: F401
+
+
+from __future__ import annotations
+
+import collections.abc as   cabc
+import dataclasses as       dcls
+import functools as         funct
+import                      inspect
+import                      platform
+import                      re
+import                      sys
+import                      types
+
+import typing_extensions as typx
+# --- BEGIN: Injected by Copier ---
+# --- END: Injected by Copier ---
+
+
+ComparisonResult: typx.TypeAlias = bool | types.NotImplementedType

classcore/__/nomina.py

@@ -0,0 +1,37 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Catalog of common type aliases. '''
+
+
+from __future__ import annotations
+
+from . import imports as __
+
+
+NominativeArguments: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ]
+PositionalArguments: __.typx.TypeAlias = __.cabc.Sequence[ __.typx.Any ]
+
+
+package_name = __name__.split( '.', maxsplit = 1 )[ 0 ]
+
+
+def calculate_attrname( level: str, core: str ) -> str:
+    return f"_{package_name}_{level}_{core}_"

classcore/__init__.py

@@ -0,0 +1,38 @@
+# 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. '''
+
+
+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__ = '1.0rc0'
+
+
+standard.reclassify_modules( __name__, recursive = True )

classcore/decorators.py

@@ -0,0 +1,130 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' 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:
+    ''' Applies sequence of decorators to class.
+
+        If decorators replace classes (e.g., ``dataclass( slots = True )``),
+        then any necessary repairs are performed on the replacement class with
+        respect to the original. E.g., on CPython, the class closure cell is
+        repaired so that ``super`` operates correctly in methods of the
+        replacement class.
+    '''
+    for decorator in decorators:
+        cls_ = decorator( cls )
+        if cls is cls_: continue # Simple mutation. No replacement.
+        _utilities.repair_class_reproduction( cls, cls_ )
+        cls = cls_ # Use the replacement class.
+    return cls
+
+
+def decoration_by(
+    *decorators: _nomina.Decorator,
+    preparers: _nomina.DecorationPreparers = ( ),
+) -> _nomina.Decorator:
+    ''' Class decorator which applies other class decorators.
+
+        Useful to apply a stack of decorators as a sequence.
+
+        Can optionally execute a sequence of decoration preparers before
+        applying the decorators proper. These can be used to alter the
+        decorators list itself, such as to inject decorators based on
+        introspection of the class.
+    '''
+    def decorate( cls: type ) -> type:
+        decorators_ = list( decorators )
+        for preparer in preparers: preparer( cls, decorators_ )
+        return apply_decorators( cls, decorators_ )
+
+    return decorate
+
+
+def produce_class_construction_decorator(
+    attributes_namer: _nomina.AttributesNamer,
+    constructor: _nomina.ClassConstructor,
+) -> _nomina.Decorator:
+    ''' Produces metaclass decorator to control class construction.
+
+        Decorator overrides ``__new__`` on metaclass.
+    '''
+    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 ],
+            name: str,
+            bases: tuple[ type, ... ],
+            namespace: dict[ str, __.typx.Any ], *,
+            decorators: _nomina.Decorators = ( ),
+            **arguments: __.typx.Any,
+        ) -> type[ object ]:
+            return constructor(
+                clscls_, original,
+                name, bases, namespace, arguments, decorators )
+
+        setattr( clscls, constructor_name, construct )
+        setattr( clscls, '__new__', construct )
+        return clscls
+
+    return decorate
+
+
+def produce_class_initialization_decorator(
+    attributes_namer: _nomina.AttributesNamer,
+    initializer: _nomina.ClassInitializer,
+) -> _nomina.Decorator:
+    ''' Produces metaclass decorator to control class initialization.
+
+        Decorator overrides ``__init__`` on metaclass.
+    '''
+    def decorate( clscls: type[ _T ] ) -> type[ _T ]:
+        initializer_name = attributes_namer( 'classes', 'initializer' )
+        extant = getattr( clscls, initializer_name, None )
+        original = getattr( clscls, '__init__' )
+        if extant is original: return clscls
+
+        @__.funct.wraps( original )
+        def initialize(
+            cls: type, *posargs: __.typx.Any, **nomargs: __.typx.Any
+        ) -> None:
+            ligation = __.funct.partial( original, cls )
+            initializer( cls, ligation, posargs, nomargs )
+
+        setattr( clscls, initializer_name, initialize )
+        clscls.__init__ = initialize
+        return clscls
+
+    return decorate

classcore/exceptions.py

@@ -0,0 +1,59 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Exceptions from package. '''
+
+
+from __future__ import annotations
+
+from . import __
+from . import standard as _standard
+
+
+class Omniexception( # pyright: ignore[reportGeneralTypeIssues]
+    BaseException, _standard.Object,
+    instances_visibles = ( '__cause__', '__context__' ), # pyright: ignore[reportCallIssue]
+):
+    ''' Base exception for package. '''
+
+
+class Omnierror( Exception, Omniexception ):
+    ''' Base error for package. '''
+
+
+class AttributeImmutability( AttributeError, Omnierror ):
+
+    def __init__( self, name: str, target: str ):
+        super( ).__init__(
+            f"Could not assign or delete attribute {name!r} on {target}." )
+
+
+class BehaviorExclusionInvalidity( TypeError, ValueError, Omnierror ):
+
+    def __init__( self, verifier: __.typx.Any ):
+        super( ).__init__(
+            f"Invalid behavior exclusion verifier: {verifier!r}" )
+
+
+class ErrorProvideFailure( RuntimeError, Omnierror ):
+
+    def __init__( self, name: str, reason: str ):
+        super( ).__init__(
+            f"Could not provide error class {name!r}. Reason: {reason}" )

classcore/factories.py

@@ -0,0 +1,92 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' 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:
+    ''' Produces constructors for classes. '''
+
+    def construct( # noqa: PLR0913
+        clscls: type[ _T ],
+        superf: _nomina.ClassConstructorLigation,
+        name: str,
+        bases: tuple[ type, ... ],
+        namespace: dict[ str, __.typx.Any ],
+        arguments: __.NominativeArguments,
+        decorators: _nomina.Decorators,
+    ) -> 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_ )
+        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.
+        progress_name = attributes_namer( 'class', 'in_progress' )
+        in_progress = _utilities.getattr0( cls, progress_name, False )
+        if in_progress: return cls
+        setattr( cls, progress_name, True )
+        for postp in postprocessors: postp( cls, decorators_ )
+        cls = _decorators.apply_decorators( cls, decorators_ )
+        setattr( cls, progress_name, False )
+        return cls
+
+    return construct
+
+
+def produce_class_initializer(
+    attributes_namer: _nomina.AttributesNamer,
+    completers: _nomina.ProduceInitializerCompletersArgument = ( ),
+) -> _nomina.ClassInitializer:
+    ''' Produces initializers for classes. '''
+
+    def initialize(
+        cls: type,
+        superf: _nomina.InitializerLigation,
+        posargs: __.PositionalArguments,
+        nomargs: __.NominativeArguments,
+    ) -> None:
+        ''' Initializes class, applying hooks. '''
+        superf( *posargs, **nomargs )
+        progress_name = attributes_namer( 'class', 'in_progress' )
+        in_progress = _utilities.getattr0( cls, progress_name, False )
+        if in_progress: return # If non-empty, then not top-level.
+        delattr( cls, progress_name )
+        for completer in completers: completer( cls )
+
+    return initialize

classcore/nomina.py

@@ -0,0 +1,162 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Catalog of common type aliases. '''
+
+
+from __future__ import annotations
+
+from . import __
+
+
+AttributesNamer: __.typx.TypeAlias = (
+    __.cabc.Callable[ [ str, str ], str ] )
+
+Decorator: __.typx.TypeAlias = __.cabc.Callable[ [ type ], type ]
+Decorators: __.typx.TypeAlias = __.cabc.Sequence[ Decorator ]
+DecoratorsMutable: __.typx.TypeAlias = __.cabc.MutableSequence[ Decorator ]
+
+DecorationPreparer: __.typx.TypeAlias = (
+    __.cabc.Callable[ [ type, DecoratorsMutable ], None ] )
+DecorationPreparers: __.typx.TypeAlias = (
+    __.cabc.Sequence[ DecorationPreparer ] )
+
+ClassConstructorLigation: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[ ..., type ],
+    __.typx.Doc(
+        ''' Bound class constructor function.
+
+            Usually from ``super( ).__new__`` or a partial function.
+        ''' ),
+]
+InitializerLigation: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[ ..., None ],
+    __.typx.Doc(
+        ''' Bound initializer function.
+
+            Usually from ``super( ).__init__`` or a partial function.
+        ''' ),
+]
+AssignerLigation: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[ [ str, __.typx.Any ], None ],
+    __.typx.Doc(
+        ''' Bound attributes assigner function.
+
+            Usually from ``super( ).__setattr__`` or a partial function.
+        ''' ),
+]
+DeleterLigation: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[ [ str ], None ],
+    __.typx.Doc(
+        ''' Bound attributes deleter function.
+
+            Usually from ``super( ).__delattr__`` or a partial function.
+        ''' ),
+]
+SurveyorLigation: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[ [ ], __.cabc.Iterable[ str ] ],
+    __.typx.Doc(
+        ''' Bound attributes surveyor function.
+
+            Usually from ``super( ).__dir__`` or a partial function.
+        ''' ),
+]
+
+
+ClassConstructionPreprocessor: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[
+        [
+            type[ type ],               # metaclass
+            str,                        # class name
+            list[ type ],               # bases (mutable)
+            dict[ str, __.typx.Any ],   # namespace (mutable)
+            dict[ str, __.typx.Any ],   # arguments (mutable)
+            DecoratorsMutable,          # decorators (mutable)
+        ],
+        None
+    ],
+    __.typx.Doc(
+        ''' Processes class data before construction.
+
+            For use cases, such as argument conversion.
+        ''' ),
+]
+ClassConstructionPostprocessor: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[ [ type, DecoratorsMutable ], None ],
+    __.typx.Doc(
+        ''' Processes class before decoration.
+
+            For use cases, such as decorator list manipulation.
+        ''' ),
+]
+# TODO: ClassInitializationPreparer (arguments mutation)
+ClassInitializationCompleter: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[ [ type ], None ],
+    __.typx.Doc(
+        ''' Completes initialization of class.
+
+            For use cases, such as enabling immutability once all other
+            initialization has occurred.
+        ''' ),
+]
+
+
+ClassConstructor: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[
+        [
+            type,
+            ClassConstructorLigation,
+            str,
+            tuple[ type, ... ],
+            dict[ str, __.typx.Any ],
+            __.NominativeArguments,
+            Decorators,
+        ],
+        type
+    ],
+    __.typx.Doc( ''' Constructor to use with metaclass. ''' ),
+]
+ClassInitializer: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Callable[
+        [
+            type,
+            InitializerLigation,
+            __.PositionalArguments,
+            __.NominativeArguments,
+        ],
+        None
+    ],
+    __.typx.Doc( ''' Initializer to use with metaclass. ''' ),
+]
+
+
+ProduceConstructorPreprocsArgument: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Sequence[ ClassConstructionPreprocessor ],
+    __.typx.Doc( ''' Processors to apply before construction of class. ''' ),
+]
+ProduceConstructorPostprocsArgument: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Sequence[ ClassConstructionPostprocessor ],
+    __.typx.Doc( ''' Processors to apply before decoration of class. ''' ),
+]
+ProduceInitializerCompletersArgument: __.typx.TypeAlias = __.typx.Annotated[
+    __.cabc.Sequence[ ClassInitializationCompleter ],
+    __.typx.Doc(
+        ''' Processors to apply at final stage of class initialization. ''' ),
+]

classcore/standard/__.py

@@ -0,0 +1,46 @@
+# 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. '''
+
+
+from __future__ import annotations
+
+from ..__ import * # noqa: F403
+
+
+def is_public_identifier( name: str ) -> bool:
+    ''' Is Python identifier public? '''
+    return not name.startswith( '_' )
+
+
+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, )

classcore/standard/__init__.py

@@ -0,0 +1,28 @@
+# 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.                                            #
+#                                                                            #
+#============================================================================#
+
+
+''' Decorators and class factories providing concealment and immutability. '''
+
+
+from __future__ import annotations
+
+from .classes import *
+from .decorators import *
+from .modules import *