API

Package classcore

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 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).

classcore.__version__: str = '1.8'

Module classcore.decorators

Utilities for the decoration of classes, including metaclasses.

classcore.decorators.apply_decorators(cls, decorators)

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.

Parameters:
Return type:

type

classcore.decorators.decoration_by(*decorators, preparers=())

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.

Parameters:
Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

classcore.decorators.produce_class_construction_decorator(attributes_namer, constructor)

Produces metaclass decorator to control class construction.

Decorator overrides __new__ on metaclass.

Parameters:
Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.T ] ], type[ classcore.__.T ] ]

classcore.decorators.produce_class_initialization_decorator(attributes_namer, initializer)

Produces metaclass decorator to control class initialization.

Decorator overrides __init__ on metaclass.

Parameters:
Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.T ] ], type[ classcore.__.T ] ]

Module classcore.factories

Factories which produce metaclass implementations.

classcore.factories.produce_class_constructor(attributes_namer, preprocessors=(), postprocessors=())

Produces constructors for classes.

Parameters:
Returns:

Constructor to use with metaclass.

Return type:

collections.abc.Callable[ [ type, collections.abc.Callable[ …, type ], str, tuple[ type, … ], dict[ str, typing_extensions.Any ], collections.abc.Mapping[ str, typing_extensions.Any ], collections.abc.Sequence[ collections.abc.Callable[ [ type[ classcore.__.T ] ], type[ classcore.__.T ] ] ] ], type ]

classcore.factories.produce_class_initializer(attributes_namer, completers=())

Produces initializers for classes.

Parameters:

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • completers (collections.abc.Sequence[ collections.abc.Callable[ [ type ], None ] ]) – Processors to apply at final stage of class initialization.

Returns:

Initializer to use with metaclass.

Return type:

collections.abc.Callable[ [ type, collections.abc.Callable[ …, None ], collections.abc.Sequence[ typing_extensions.Any ], collections.abc.Mapping[ str, typing_extensions.Any ] ], None ]

Module classcore.exceptions

Exceptions from package.

exception classcore.exceptions.AttributeImmutability(name, target)

Bases: Omnierror, AttributeError

exception classcore.exceptions.BehaviorExclusionInvalidity(verifier)

Bases: Omnierror, TypeError, ValueError

exception classcore.exceptions.ErrorProvideFailure(name, reason)

Bases: Omnierror, RuntimeError

exception classcore.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base error for package.

exception classcore.exceptions.Omniexception(*posargs, **nomargs)

Bases: Object, BaseException

Base exception for package.

Module classcore.nomina

Catalog of common type aliases.

type classcore.nomina.AttributesNamer = collections.abc.Callable[[str, str], str]
type classcore.nomina.Decorator = collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]
type classcore.nomina.Decorators = collections.abc.Sequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]
type classcore.nomina.DecoratorsMutable = collections.abc.MutableSequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]
type classcore.nomina.DecorationPreparer = collections.abc.Callable[[type[classcore.__.U], collections.abc.MutableSequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]], None]
type classcore.nomina.DecorationPreparers = collections.abc.Sequence[collections.abc.Callable[[type[classcore.__.U], collections.abc.MutableSequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]], None]]
type classcore.nomina.ClassConstructorLigation = collections.abc.Callable[..., type]
type classcore.nomina.InitializerLigation = collections.abc.Callable[..., None]
type classcore.nomina.AssignerLigation = collections.abc.Callable[[str, typing_extensions.Any], None]
type classcore.nomina.DeleterLigation = collections.abc.Callable[[str], None]
type classcore.nomina.SurveyorLigation = collections.abc.Callable[[], collections.abc.Iterable[str]]
type classcore.nomina.ClassConstructionPreprocessor = collections.abc.Callable[[type[type], str, list[type], dict[str, typing_extensions.Any], dict[str, typing_extensions.Any], collections.abc.MutableSequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]], None]
type classcore.nomina.ClassConstructionPreprocessors = collections.abc.Sequence[collections.abc.Callable[[type[type], str, list[type], dict[str, typing_extensions.Any], dict[str, typing_extensions.Any], collections.abc.MutableSequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]], None]]
type classcore.nomina.ClassConstructionPostprocessor = collections.abc.Callable[[type, collections.abc.MutableSequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]], None]
type classcore.nomina.ClassConstructionPostprocessors = collections.abc.Sequence[collections.abc.Callable[[type, collections.abc.MutableSequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]], None]]
type classcore.nomina.ClassInitializationCompleter = collections.abc.Callable[[type], None]
type classcore.nomina.ClassInitializationCompleters = collections.abc.Sequence[collections.abc.Callable[[type], None]]
type classcore.nomina.ClassConstructor = collections.abc.Callable[[type, collections.abc.Callable[..., type], str, tuple[type, ...], dict[str, typing_extensions.Any], collections.abc.Mapping[str, typing_extensions.Any], collections.abc.Sequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]], type]
type classcore.nomina.ClassInitializer = collections.abc.Callable[[type, collections.abc.Callable[..., None], collections.abc.Sequence[typing_extensions.Any], collections.abc.Mapping[str, typing_extensions.Any]], None]

Module classcore.utilities

Various utilities for class manipulation.

classcore.utilities.delattr0(objct, /, name)

Deletes special private attribute on object.

This avoids inheritance-related collisions.

Uses mangled attribute name which is unique to the class, except when attribute is slotted. Slotted attributes are effectively isolated from inheritance.

Parameters:
classcore.utilities.describe_object(objct, /)

Returns object type with fully-qualified name.

Parameters:

objct (object)

Return type:

str

classcore.utilities.getattr0(objct, /, name, default)

Returns special private attribute from object.

This avoids inheritance-related collisions.

Uses mangled attribute name which is unique to the class, except when attribute is slotted. Slotted attributes are effectively isolated from inheritance.

Parameters:

  • objct (object)

  • name (str)

  • default (typing_extensions.Any)

Return type:

typing_extensions.Any

classcore.utilities.mangle_name(objct, /, name)

Mangles attribute name so that it is unique.

Effectively provides name of private member attribute, which is unique across class inheritance.

Parameters:
Return type:

str

classcore.utilities.qualify_class_name(cls)

Returns fully-qualified class name.

Parameters:

cls (type)

Return type:

str

classcore.utilities.repair_class_reproduction(original, reproduction)

Repairs a class reproduction, if necessary.

Parameters:
classcore.utilities.setattr0(objct, /, name, value)

Assigns special private attribute to object.

This avoids inheritance-related collisions.

Uses mangled attribute name which is unique to the class, except when attribute is slotted. Slotted attributes are effectively isolated from inheritance.

Parameters:

  • objct (object)

  • name (str)

  • value (typing_extensions.Any)

Subpackage classcore.standard

Decorators and class factories providing concealment and immutability.

Concealment restricts the visibility of attributes on classes and their instances. By default, only public attributes (ones which do not start with _) are revealed for dir() calls. This behavior can be overriden by supplying visibility verifiers as a decorator factory argument or metaclass argument. These can be a sequence of attribute names, regular expression re.Pattern objects which match attribute names, or predicate functions which match attribute names. Or, total visibility (per the Python default) can be achieved by supplying visibles = '*' instead of a sequence of verifiers.

Immutability prevents assignment (including reassignment) or deletion of attrubtes on classes and their instances after they have been completely initialized. In addition to any standard Python class, this can be applied to dataclasses, allowing them to use __post_init__ to set attributes, which dataclasses.dataclass( frozen = True ) prevents. The immutability behavior can be overridden by supplying mutability verifiers as a decorator factory argument or metaclass argument. These behave similarly to the visibility verifiers described above.

Hooks to modify the concealment and immutability behaviors are also available.

Module classcore.standard.classes

Standard classes and class factories.

class classcore.standard.classes.Class(name, bases, namespace, *, decorators=(), **arguments)

Bases: type

Metaclass for standard classes.

By default, conceals non-public class attributes.

By default, protects class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class classcore.standard.classes.ClassFactoryExtraArguments

Bases: TypedDict

Extra arguments accepted by standard metaclasses.

Variables:
class classcore.standard.classes.Dataclass(name, bases, namespace, *, decorators=(), **arguments)

Bases: type

Metaclass for standard dataclasses.

Produces inheritable dataclasses with keyword-only instantiation.

By default, conceals non-public class attributes.

By default, protects class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class classcore.standard.classes.DataclassMutable(name, bases, namespace, *, decorators=(), **arguments)

Bases: type

Metaclass for dataclasses with mutable instance attributes.

Produces inheritable dataclasses with keyword-only instantiation.

By default, conceals non-public class attributes.

By default, protects class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

class classcore.standard.classes.DataclassObject

Bases: object

Standard base dataclass.

Inheritable dataclass with keyword-only instantiation.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

By default, protects instance attributes.

class classcore.standard.classes.DataclassObjectMutable

Bases: object

Base dataclass with mutable instance attributes.

Inheritable dataclass with keyword-only instantiation.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

class classcore.standard.classes.DataclassProtocol(*args, **kwargs)

Bases: Protocol

Standard base protocol dataclass.

Inheritable dataclass with keyword-only instantiation.

Protocol class (PEP 544). Nominal and structural subtyping.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

By default, protects instance attributes.

class classcore.standard.classes.DataclassProtocolMutable(*args, **kwargs)

Bases: Protocol

Base protocol dataclass with mutable instance attributes.

Inheritable dataclass with keyword-only instantiation.

Protocol class (PEP 544). Nominal and structural subtyping.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

class classcore.standard.classes.Object(*posargs, **nomargs)

Bases: object

Standard base class.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

By default, protects instance attributes.

class classcore.standard.classes.ObjectMutable(*posargs, **nomargs)

Bases: object

Base class with mutable instance attributes.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

class classcore.standard.classes.Protocol(*args, **kwargs)

Bases: Protocol

Standard base protocol class.

Protocol class (PEP 544). Nominal and structural subtyping.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

By default, protects instance attributes.

class classcore.standard.classes.ProtocolClass(name, bases, namespace, *, decorators=(), **arguments)

Bases: _ProtocolMeta

Metaclass for standard protocol classes.

Produces PEP 544 protocol classes.

By default, conceals non-public class attributes.

By default, protects class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class classcore.standard.classes.ProtocolDataclass(name, bases, namespace, *, decorators=(), **arguments)

Bases: _ProtocolMeta

Metaclass for standard protocol dataclasses.

Produces PEP 544 protocol classes.

Produces inheritable dataclasses with keyword-only instantiation.

By default, conceals non-public class attributes.

By default, protects class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class classcore.standard.classes.ProtocolDataclassMutable(name, bases, namespace, *, decorators=(), **arguments)

Bases: _ProtocolMeta

Metaclass for protocol dataclasses with mutable instance attributes.

Produces PEP 544 protocol classes.

Produces inheritable dataclasses with keyword-only instantiation.

By default, conceals non-public class attributes.

By default, protects class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

class classcore.standard.classes.ProtocolMutable(*args, **kwargs)

Bases: Protocol

Base protocol class with mutable instance attributes.

Protocol class (PEP 544). Nominal and structural subtyping.

By default, non-public class attributes are invisible.

By default, class attributes are immutable.

Is decorated by Dynadoc.

By default, conceals non-public instance attributes.

Module classcore.standard.decorators

Standard decorators.

classcore.standard.decorators.apply_cfc_attributes_assigner(clscls, /, attributes_namer, error_class_provider, implementation_core)

Injects ‘__setattr__’ method into metaclass.

Parameters:

  • clscls (type[ classcore.__.T ])

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

  • implementation_core (classcore.standard.nomina.AssignerCore | None)

classcore.standard.decorators.apply_cfc_attributes_deleter(clscls, /, attributes_namer, error_class_provider, implementation_core)

Injects ‘__delattr__’ method into metaclass.

Parameters:

  • clscls (type[ classcore.__.T ])

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

  • implementation_core (classcore.standard.nomina.DeleterCore | None)

classcore.standard.decorators.apply_cfc_attributes_surveyor(clscls, attributes_namer, implementation_core)

Injects ‘__dir__’ method into metaclass.

Parameters:

  • clscls (type[ classcore.__.T ])

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • implementation_core (classcore.standard.nomina.SurveyorCore | None)

classcore.standard.decorators.apply_cfc_constructor(clscls, /, attributes_namer, error_class_provider)

Injects ‘__new__’ method into metaclass.

Parameters:

  • clscls (type[ classcore.__.T ])

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

classcore.standard.decorators.apply_cfc_core_functions(clscls, /, attributes_namer, assigner_core=None, deleter_core=None, surveyor_core=None)

Stores core functions on metaclass.

Parameters:
classcore.standard.decorators.apply_cfc_dynadoc_configuration(clscls, /, attributes_namer, configuration)

Stores Dynadoc configuration on metaclass.

Parameters:

  • clscls (type[ classcore.__.T ])

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • configuration (collections.abc.Mapping[ str, typing_extensions.Any ])

classcore.standard.decorators.apply_cfc_initializer(clscls, /, attributes_namer)

Injects ‘__init__’ method into metaclass.

Parameters:

  • clscls (type[ classcore.__.T ])

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

classcore.standard.decorators.class_factory(attributes_namer=<function calculate_attrname>, error_class_provider=<function provide_error_class>, assigner_core=None, deleter_core=None, surveyor_core=None, dynadoc_configuration=mappingproxy({'context': Context(notifier=<function notify>, fragment_rectifier=<function rectify_fragment>, visibility_decider=<function is_attribute_visible>, fragments_name='_dynadoc_fragments_', introspection_limit_name='_dynadoc_introspection_limit_', invoker_globals=None, resolver_globals=None, resolver_locals=None), 'introspection': IntrospectionControl(enable=True, class_control=ClassIntrospectionControl(inheritance=True, introspectors=(<function introspect_special_classes>, ), scan_attributes=False), module_control=ModuleIntrospectionControl(scan_attributes=False), limiters=(functools.partial(<function dynadoc_avoid_immutables>, attributes_namer=<function calculate_attrname>), ), targets=<IntrospectionTargets.Function|Descriptor|Class: 7>), 'preserve': True, 'table': mappingproxy({})}))

Produces decorator to apply standard behaviors to metaclass.

Parameters:
Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.T ] ], type[ classcore.__.T ] ]

classcore.standard.decorators.dataclass_with_standard_behaviors(attributes_namer=<function calculate_attrname>, error_class_provider=<function provide_error_class>, decorators=(), assigner_core=None, deleter_core=None, surveyor_core=None, ignore_init_arguments=False, mutables=(), visibles=(<function is_public_identifier>, ))

Dataclass decorator factory.

Parameters:
Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

classcore.standard.decorators.prepare_dataclass_for_instances(cls, decorators, /, *, attributes_namer)

Annotates dataclass in support of instantiation machinery.

Parameters:

  • cls (type)

  • decorators (collections.abc.MutableSequence[ collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ] ]) –

    Sequence of class decorators.

    Each element takes a class argument and returns a class.

    Decorators may be inserted or removed from sequence.

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

classcore.standard.decorators.produce_attributes_assignment_decorator(level, attributes_namer, error_class_provider, implementation_core)

Produces decorator to inject ‘__setattr__’ method into class.

Parameters:

  • level (str)

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

  • implementation_core (classcore.standard.nomina.AssignerCore | None)

Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

classcore.standard.decorators.produce_attributes_deletion_decorator(level, attributes_namer, error_class_provider, implementation_core)

Produces decorator to inject ‘__delattr__’ method into class.

Parameters:

  • level (str)

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

  • implementation_core (classcore.standard.nomina.DeleterCore | None)

Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

classcore.standard.decorators.produce_attributes_surveillance_decorator(level, attributes_namer, implementation_core)

Produces decorator to inject ‘__dir__’ method into class.

Parameters:

  • level (str)

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • implementation_core (classcore.standard.nomina.SurveyorCore | None)

Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

classcore.standard.decorators.produce_instances_inception_decorator(attributes_namer, assigner_core, deleter_core, surveyor_core, ignore_init_arguments, mutables, visibles)

Produces decorator to inject ‘__new__’ or ‘__init__’ method.

Also handles common bookkeeping tasks.

Parameters:
Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

classcore.standard.decorators.produce_instances_initialization_decorator(attributes_namer, behaviors, ignore_init_arguments)

Produces decorator to inject ‘__init__’ method into class.

Parameters:

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • behaviors (collections.abc.MutableSet[ str ])

  • ignore_init_arguments (bool)

Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

classcore.standard.decorators.with_standard_behaviors(attributes_namer=<function calculate_attrname>, error_class_provider=<function provide_error_class>, decorators=(), assigner_core=None, deleter_core=None, surveyor_core=None, ignore_init_arguments=False, mutables=(), visibles=(<function is_public_identifier>, ))

Class decorator factory.

Parameters:
Returns:

Class decorator.

Takes class argument and returns class.

Return type:

collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ]

Module classcore.standard.modules

Standard module classes and reclassifers.

class classcore.standard.modules.Module(*posargs, **nomargs)

Bases: Object, ModuleType

Modules with attributes immutability and concealment.

classcore.standard.modules.finalize_module(module, /, *fragments, attributes_namer=<function calculate_attrname>, dynadoc_introspection=IntrospectionControl(enable=True, class_control=ClassIntrospectionControl(inheritance=True, introspectors=(<function introspect_special_classes>, ), scan_attributes=False), module_control=ModuleIntrospectionControl(scan_attributes=False), limiters=(functools.partial(<function dynadoc_avoid_immutables>, attributes_namer=<function calculate_attrname>), ), targets=<IntrospectionTargets.Module|Function|Descriptor|Class: 15>), dynadoc_table=mappingproxy({}), excludes=None, recursive=False, replacement_class=<class 'classcore.standard.modules.Module'>)

Combines Dynadoc docstring assignment and module reclassification.

Applies module docstring generation via Dynadoc introspection, then reclassifies modules for immutability and concealment.

When recursive is False, automatically excludes module targets from dynadoc introspection to document only the provided module. When recursive is True, automatically includes module targets so Dynadoc can recursively document all modules.

Parameters:

  • module (str | types.ModuleType) – Module or module name to finalize.

  • fragments (str | typing_extensions.Doc)

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • dynadoc_introspection (dynadoc.context.IntrospectionControl) –

    Dynadoc introspection control.

    Which kinds of object to recursively introspect? Scan unnannotated attributes? Consider base classes? Etc…

  • dynadoc_table (collections.abc.Mapping[ str, str ]) – Table of documentation fragments.

  • excludes (collections.abc.MutableSet[ types.ModuleType ] | None) – Modules to exclude from reclassification.

  • recursive (bool) – Recursively reclassify package modules?

  • replacement_class (type[ types.ModuleType ]) – New class for module.

classcore.standard.modules.reclassify_modules(attributes, /, *, attributes_namer=<function calculate_attrname>, excludes=None, recursive=False, replacement_class=<class 'classcore.standard.modules.Module'>)

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.

Parameters:

  • attributes (collections.abc.Mapping[ str, typing_extensions.Any ] | types.ModuleType | str) – Module, module name, or dictionary of object attributes.

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

    Attributes namer function with which to seal class.

  • excludes (collections.abc.MutableSet[ types.ModuleType ] | None) – Modules to exclude from reclassification.

  • recursive (bool) – Recursively reclassify package modules?

  • replacement_class (type[ types.ModuleType ]) – New class for module.

Module classcore.standard.behaviors

Implementations for standard behaviors.

classcore.standard.behaviors.access_core_function(cls, /, *, attributes_namer, arguments, level, name, default)

Accesses core behavior function.

First checks for override argument, then checks for heritable attribute. Finally, falls back to provided default.

Parameters:

  • cls (type)

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • arguments (collections.abc.Mapping[ str, typing_extensions.Any ])

  • level (str)

  • name (str)

  • default (collections.abc.Callable[ ..., typing_extensions.Any ])

Return type:

collections.abc.Callable[ …, typing_extensions.Any ]

classcore.standard.behaviors.assign_attribute_if_mutable(obj, /, *, ligation, attributes_namer, error_class_provider, level, name, value)

Assigns attribute if it is mutable, else raises error.

Parameters:

  • obj (object)

  • ligation (collections.abc.Callable[ [ str, typing_extensions.Any ], None ]) –

    Bound attributes assigner function.

    Usually from super( ).__setattr__ or a partial function.

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

  • level (str)

  • name (str)

  • value (typing_extensions.Any)

classcore.standard.behaviors.augment_class_attributes_allocations(attributes_namer, namespace)

Adds necessary slots for record-keeping attributes.

Parameters:

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • namespace (dict[ str, typing_extensions.Any ])

classcore.standard.behaviors.classify_behavior_exclusion_verifiers(verifiers)

Threshes sequence of behavior exclusion verifiers into bins.

Parameters:

verifiers (collections.abc.Sequence[ str | re.Pattern[ str ] | collections.abc.Callable[ [ str ], bool ] ])

Return type:

tuple[ collections.abc.Set[ str ], collections.abc.Sequence[ re.Pattern[ str ] ], collections.abc.Sequence[ collections.abc.Callable[ [ str ], bool ] ] ]

classcore.standard.behaviors.delete_attribute_if_mutable(obj, /, *, ligation, attributes_namer, error_class_provider, level, name)

Deletes attribute if it is mutable, else raises error.

Parameters:

  • obj (object)

  • ligation (collections.abc.Callable[ [ str ], None ]) –

    Bound attributes deleter function.

    Usually from super( ).__delattr__ or a partial function.

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

  • level (str)

  • name (str)

classcore.standard.behaviors.produce_class_construction_postprocessor(attributes_namer, error_class_provider)

Produces construction processor which determines class decorators.

Parameters:

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • error_class_provider (collections.abc.Callable[ [ str ], type[ Exception ] ]) –

    Takes name of exception class and returns corresponding class.

    Can be used by downstream packages to provide exceptions from their own hierarchies rather than the hierarchy from this package.

Returns:

Processes class before decoration.

For use cases, such as decorator list manipulation.

Return type:

collections.abc.Callable[ [ type, collections.abc.MutableSequence[ collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ] ] ], None ]

classcore.standard.behaviors.produce_class_construction_preprocessor(attributes_namer)

Produces construction processor which handles metaclass arguments.

Parameters:

attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

Names attribute from level and core arguments.

Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

Returns:

Processes class data before construction.

For use cases, such as argument conversion.

Return type:

collections.abc.Callable[ [ type[ type ], str, list[ type ], dict[ str, typing_extensions.Any ], dict[ str, typing_extensions.Any ], collections.abc.MutableSequence[ collections.abc.Callable[ [ type[ classcore.__.U ] ], type[ classcore.__.U ] ] ] ], None ]

classcore.standard.behaviors.produce_class_initialization_completer(attributes_namer)

Produces initialization completer which finalizes class behaviors.

Parameters:

attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

Names attribute from level and core arguments.

Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

Returns:

Completes initialization of class.

For use cases, such as enabling immutability once all other initialization has occurred.

Return type:

collections.abc.Callable[ [ type ], None ]

classcore.standard.behaviors.record_behavior(cls, /, *, attributes_namer, level, basename, label, behaviors, verifiers)

Records details of particular class behavior, such as immutability.

Parameters:
classcore.standard.behaviors.record_class_construction_arguments(attributes_namer, namespace, arguments)

Captures metaclass arguments as class attribute for later use.

Parameters:

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • namespace (dict[ str, typing_extensions.Any ])

  • arguments (dict[ str, typing_extensions.Any ])

classcore.standard.behaviors.survey_visible_attributes(obj, /, *, ligation, attributes_namer, level)

Returns sequence of visible attributes.

Parameters:

  • obj (object)

  • ligation (collections.abc.Callable[ [ ], collections.abc.Iterable[ str ] ]) –

    Bound attributes surveyor function.

    Usually from super( ).__dir__ or a partial function.

  • attributes_namer (collections.abc.Callable[ [ str, str ], str ]) –

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘instances’, or ‘instance’. Core will be the core of the name as supplied this package.

    Can be used by downstream packages to determine names of bookkeeping attributes assigned by this package.

  • level (str)

Return type:

collections.abc.Iterable[ str ]

Module classcore.standard.nomina

Catalog of common names and type aliases.

type classcore.standard.nomina.BehaviorExclusionNames = collections.abc.Set[str]
type classcore.standard.nomina.BehaviorExclusionNamesOmni = collections.abc.Set[str] | Literal['*']
type classcore.standard.nomina.BehaviorExclusionPredicate = collections.abc.Callable[[str], bool]
type classcore.standard.nomina.BehaviorExclusionPredicates = collections.abc.Sequence[collections.abc.Callable[[str], bool]]
type classcore.standard.nomina.BehaviorExclusionRegex = re.Pattern[str]
type classcore.standard.nomina.BehaviorExclusionRegexes = collections.abc.Sequence[re.Pattern[str]]
type classcore.standard.nomina.BehaviorExclusionVerifier = str | re.Pattern[str] | collections.abc.Callable[[str], bool]
type classcore.standard.nomina.BehaviorExclusionVerifiers = collections.abc.Sequence[str | re.Pattern[str] | collections.abc.Callable[[str], bool]]
type classcore.standard.nomina.BehaviorExclusionVerifiersOmni = collections.abc.Sequence[str | re.Pattern[str] | collections.abc.Callable[[str], bool]] | Literal['*']
type classcore.standard.nomina.ErrorClassProvider = collections.abc.Callable[[str], type[Exception]]
type classcore.standard.nomina.DynadocConfiguration = collections.abc.Mapping[str, typing_extensions.Any]
type classcore.standard.nomina.DynadocContextArgument = dynadoc.context.Context
type classcore.standard.nomina.DynadocIntrospectionArgument = dynadoc.context.IntrospectionControl
type classcore.standard.nomina.DynadocPreserveArgument = bool
type classcore.standard.nomina.DynadocTableArgument = collections.abc.Mapping[str, str]
type classcore.standard.nomina.ProduceDynadocConfigurationReturn = collections.abc.Mapping[str, typing_extensions.Any]
class classcore.standard.nomina.AssignerCore(*args, **kwargs)

Bases: Protocol

Core implementation of attributes assigner.

class classcore.standard.nomina.ClassPreparer(*args, **kwargs)

Bases: Protocol

Prepares class for decorator application.

class classcore.standard.nomina.DeleterCore(*args, **kwargs)

Bases: Protocol

Core implementation of attributes deleter.

class classcore.standard.nomina.SurveyorCore(*args, **kwargs)

Bases: Protocol

Core implementation of attributes surveyor.