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.15'

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:

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • constructor (collections.abc.Callable[ [ type, collections.abc.Callable[ ..., type ], str, tuple[ type, ... ], dict[ str, Any ], collections.abc.Mapping[ str, Any ], collections.abc.Sequence[ collections.abc.Callable[ [ type[ classcore.__.T ] ], type[ classcore.__.T ] ] ] ], type ]) –

    Constructs class, then applies hooks.

    Receives the metaclass (‘clscls’), the next constructor in the metaclass MRO (‘superf’), the class name, bases, namespace, metaclass arguments, and decorators to apply after construction. Calls ‘superf’ to create the class, then applies postprocessors and decorators.

    Invoked only at the most-derived metaclass of a class. Class factory wrappers on parent metaclasses delegate directly, so construction hooks execute exactly once per class.

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:

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • initializer (collections.abc.Callable[ [ type, collections.abc.Callable[ ..., None ], collections.abc.Sequence[ Any ], collections.abc.Mapping[ str, Any ] ], None ]) –

    Initializes class, then applies hooks.

    Receives the class (‘cls’), the next initializer in the metaclass MRO (‘superf’), positional arguments, and nominative arguments. Calls ‘superf’ first, then applies completers, which finalize class behaviors (e.g., enable immutability once all other initialization has occurred).

    Invoked only at the most-derived metaclass of a class.

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:

Constructs class, then applies hooks.

Receives the metaclass (‘clscls’), the next constructor in the metaclass MRO (‘superf’), the class name, bases, namespace, metaclass arguments, and decorators to apply after construction. Calls ‘superf’ to create the class, then applies postprocessors and decorators.

Invoked only at the most-derived metaclass of a class. Class factory wrappers on parent metaclasses delegate directly, so construction hooks execute exactly once per class.

Return type:

collections.abc.Callable[ [ type, collections.abc.Callable[ …, type ], str, tuple[ type, … ], dict[ str, Any ], collections.abc.Mapping[ str, 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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:

Initializes class, then applies hooks.

Receives the class (‘cls’), the next initializer in the metaclass MRO (‘superf’), positional arguments, and nominative arguments. Calls ‘superf’ first, then applies completers, which finalize class behaviors (e.g., enable immutability once all other initialization has occurred).

Invoked only at the most-derived metaclass of a class.

Return type:

collections.abc.Callable[ [ type, collections.abc.Callable[ …, None ], collections.abc.Sequence[ Any ], collections.abc.Mapping[ str, 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.ClassDecorator = collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]
type classcore.nomina.ClassDecorators = collections.abc.Sequence[collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]
type classcore.nomina.ClassDecoratorFactory = collections.abc.Callable[..., collections.abc.Callable[[type[classcore.__.U]], type[classcore.__.U]]]
type classcore.nomina.ModuleReclassifier = collections.abc.Callable[[collections.abc.Mapping[str, Any]], None]
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, 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, Any], dict[str, 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, Any], dict[str, 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, Any], collections.abc.Mapping[str, 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[Any], collections.abc.Mapping[str, Any]], None]
classcore.nomina.is_public_identifier(name)

Is Python identifier public?

Parameters:

name (str)

Return type:

bool

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:
Return type:

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:
classcore.utilities.survey_mangled_names(cls, /, name)

Returns mangled variants of name present in class’s own namespace.

A class reproduction (e.g., from dataclass( slots = ... )) is created with a bare __qualname__, which is restored only after the reproduction is constructed. During that window, mangled names computed from the reproduction differ from those computed from the original. Detection by prefix survives such qualname drift.

Parameters:
Return type:

tuple[ str, … ]

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.AbstractClass(name, bases, namespace, *, decorators=(), **arguments)

Bases: Class, ABCMeta

Metaclass for abstract classes with standard behaviors.

Combines the standard behaviors of Class with the machinery of abc.ABCMeta (abstract method enforcement, virtual subclass registration) via a diamond hierarchy. Class itself remains backed by plain type, so ABC machinery applies only where this metaclass is used.

Contributes the stdlib ABC and typing machinery names as internal for the classes it builds, mirroring the class_mutables exemption scoping.

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.AbstractObject(*posargs, **nomargs)

Bases: object

Base class for abstract classes with standard behaviors.

Supports abstract method enforcement and virtual subclass registration, and mixes with external classes whose metaclass is abc.ABCMeta.

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.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: Class

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: Dataclass

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: AbstractClass, _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: ProtocolClass

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: ProtocolDataclass

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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • configuration (collections.abc.Mapping[ str, 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

classcore.standard.decorators.apply_internal_names(cls, /, attributes_namer)

Records the namer’s internal-name contribution, if any.

Works for metaclasses (contributions inherit to every class the metaclass builds) and for decorator-path classes (contributions ride the class itself, since plain decorated classes have no custom metaclass). Parent wiring may already contribute the same detector (e.g., a diamond re-running the factory with the same namer); keep one of each by identity.

Parameters:

  • cls (type)

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

classcore.standard.decorators.class_factory(attributes_namer=<classcore.__.nomina.AttrnameCalculator object>, 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=<classcore.__.nomina.AttrnameCalculator object>), ), targets=<IntrospectionTargets.Class|Descriptor|Function: 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=<classcore.__.nomina.AttrnameCalculator object>, 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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=<classcore.__.nomina.AttrnameCalculator object>, 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=<classcore.__.nomina.AttrnameCalculator object>, 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=<classcore.__.nomina.AttrnameCalculator object>), ), targets=<IntrospectionTargets.Class|Descriptor|Function|Module: 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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=<classcore.__.nomina.AttrnameCalculator object>, 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, 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

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

  • level (str)

  • name (str)

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

Return type:

collections.abc.Callable[ …, 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, 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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 (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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • namespace (dict[ str, 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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.determine_relevant_permitters(objct, /, *, attributes_namer, level, basename, name)

Returns exclusion rules matching name, in evaluation order.

A names match short-circuits, matching the survey core’s historical control flow: predicates and regexes are not evaluated for a name found in the exclusion names. Otherwise a name may match any number of predicates and any number of regexes. The wildcard is not considered here; callers handle its short-circuit separately.

Rules pair a kind (‘names’, ‘predicate’, ‘regex’) with the raw matched verifier (name, predicate, or regex). Matching never renders diagnostic text: enforcement and survey consult kind and presence only, so exotic callables cannot disrupt them. Render verifiers with ‘render_verifier_text’ at the record layer when producing explanation records.

Parameters:

  • objct (object)

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • level (str)

  • basename (str)

  • name (str)

Return type:

tuple[ tuple[ str, Any ], … ]

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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

    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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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, Any ], dict[ str, 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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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.provide_permitter_if_applicable(objct, /, *, attributes_namer, level, basename, name)

Returns first exclusion rule permitting operation, else None.

Rules apply by precedence: omni or names membership, then the first matching predicate, then the first matching regex. Each rule pairs a kind (‘omni’, ‘names’, ‘predicate’, ‘regex’) with the raw matched verifier. Matching never renders diagnostic text: enforcement consults kind and presence only, so exotic callables cannot disrupt it. Render the verifier with ‘render_verifier_text’ at the record layer when producing explanation records.

Parameters:

  • objct (object)

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • level (str)

  • basename (str)

  • name (str)

Return type:

tuple[ str, Any ] | None

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

Records details of particular class behavior, such as immutability.

Parameters:

  • cls (type)

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • level (str)

  • basename (str)

  • label (str)

  • behaviors (set[ str ])

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

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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • namespace (dict[ str, Any ])

  • arguments (dict[ str, Any ])

classcore.standard.behaviors.render_verifier_text(verifier, /)

Returns stable detail text for an exclusion verifier.

Regexes render as pattern text; predicates render as fully-qualified name, with an anonymous fallback when no qualified name is available. Strings do not reach this function; they are classified as names before rendering. A non-string ‘pattern’ attribute is not trusted as text; such verifiers fall through to qualified-name rendering, where a non-string qualified name falls back to ‘<anonymous>’ while a non-string module name preserves the qualified name. Hostile metadata (raising descriptors, custom ‘__getattribute__’) yields ‘<unrenderable>’ rather than raising, so diagnostic rendering never disrupts its callers. The broad ‘except Exception’ is deliberate: rendering is diagnostics, and diagnostics must never break enforcement or survey paths.

Note: the inspect utilities were considered and rejected here; they resolve modules to objects and provide no qualified-name rendering with an anonymous fallback, while this getattr chain stays defensive for exotic callables (e.g., partials).

Parameters:

verifier (Any)

Return type:

str

classcore.standard.behaviors.survey_active_behaviors(objct, /, *, attributes_namer, level)

Returns active behaviors set for object at level.

This is the shared entry point of the behavior decision cascade: every core first determines whether the governing behavior is active before consulting exclusion configuration.

Parameters:

  • objct (object)

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

  • level (str)

Return type:

collections.abc.Set[ str ]

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’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

Explanations of attribute behavior decisions.

class classcore.standard.explanations.AssignVerdict(*, operation, decision)

Bases: Verdict

Verdict for attribute assignment.

Variables:
class classcore.standard.explanations.AttributeExplanation(*, target, name, behaviors, operations, internal)

Bases: object

Decision trace for one attribute of one target.

Variables:
class classcore.standard.explanations.Decision

Bases: object

Decision which one operation reached for one attribute.

The decision subclasses form a closed hierarchy; the decision type is the discriminant. Verdict permissibility is derived from the decision type.

class classcore.standard.explanations.DeleteVerdict(*, operation, decision)

Bases: Verdict

Verdict for attribute deletion.

Variables:
class classcore.standard.explanations.PermitByInapplicability

Bases: Decision

Permission because the governing behavior is inactive.

class classcore.standard.explanations.PermitByNames(*, name)

Bases: Decision

Permission by exclusion names membership.

Variables:

name (str)

class classcore.standard.explanations.PermitByOmni

Bases: Decision

Permission by the omni marker, which permits every name.

class classcore.standard.explanations.PermitByPredicate(*, predicate)

Bases: Decision

Permission by an exclusion predicate.

Variables:

predicate (str)

class classcore.standard.explanations.PermitByRegex(*, pattern)

Bases: Decision

Permission by an exclusion regex.

Variables:

pattern (str)

class classcore.standard.explanations.Prohibit

Bases: Decision

Prohibition: the behavior is active and no rule permits.

class classcore.standard.explanations.SurveyVerdict(*, operation, decision)

Bases: Verdict

Verdict for attribute visibility in survey results.

Variables:
class classcore.standard.explanations.Verdict(*, operation, decision)

Bases: object

Verdict for one operation on one attribute.

Variables:
property permissible

Returns whether the operation is permissible.

Parameters:

self

Return type:

bool

classcore.standard.explanations.explain_attribute(target, name, /, *, attributes_namer=<classcore.__.nomina.AttrnameCalculator object>)

Returns decision trace for attribute name on target.

All operations follow precedence semantics: omni, then names membership, then the first matching predicate, then the first matching regex; prohibition when the governing behavior is active and nothing permits; permission by inapplicability when the behavior is inactive. For class targets, the classes-level configuration is evaluated; for instance targets, the instances-level configuration is evaluated against the instance’s class hierarchy — matching the levels the behavior cores evaluate. Records report the normalized level names (‘class’ and ‘instance’) at which behaviors and exclusion configuration were found. Explanations are observational: they neither bypass nor alter concealment or immutability. They are not side-effect-free for arbitrary callbacks, however: producing a record invokes user predicates and internal-name detectors to determine the same outcome the cores would.

Survey explanations describe normalized first-match semantics; the survey core’s current once-per-matching-rule duplication is characterized as a defect whose repair is deferred separately.

Parameters:

  • target (object)

  • name (str)

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

    Names attribute from level and core arguments.

    Level will be one of ‘class’, ‘classes’, ‘instance’, or ‘instances’. Core will be one of the framework cores named in the attribute-namer grammar (mutables and visibles rules, assigner, deleter, and surveyor cores, and construction bookkeeping).

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

Return type:

classcore.standard.explanations.AttributeExplanation

classcore.standard.explanations.is_internal_name(target, name, /)

Returns whether name is internal to the target’s machinery.

Contributions are discovered on the metaclass chain: for a class target, its metaclass method resolution order; for an instance target, the metaclass resolution order of its type (the metaclass chain is reached through the double type transformation — the instance’s own type resolution order enumerates the class bases, never the metaclass). Decorator- based classes carry their contributions on the class itself, so the class resolution order is consulted as well. Each contribution is a detector produced by the machinery which built the class, so a name is internal only where the machinery that generates it operates. Classification scope is the machinery chain and is independent of per-class mutability exemptions: a name may be internal on a class where it is not mutable, and mutable where it is not internal.

Parameters:
Return type:

bool

classcore.standard.explanations.produce_decision(rule, active, /)

Returns decision for governing-behavior activity and first rule.

Rules are the (kind, raw verifier) pairs produced by provide_permitter_if_applicable; the kind vocabulary matches the omni/names/predicate/regex precedence stages. Verifier detail text is rendered here, at the record layer, so enforcement paths which consult the same rules never depend on rendering.

Parameters:
Return type:

classcore.standard.explanations.Decision

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.InternalNameDetector = collections.abc.Callable[[str], bool]
type classcore.standard.nomina.InternalNameDetectors = collections.abc.Sequence[collections.abc.Callable[[str], bool]]
type classcore.standard.nomina.ErrorClassProvider = collections.abc.Callable[[str], type[Exception]]
type classcore.standard.nomina.DynadocConfiguration = collections.abc.Mapping[str, 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, 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.