API¶

Package `accretive`¶

Accretive data structures.

Data structures which can grow but never shrink - once values are set, they become immutable. This behavior is useful for configuration registries, plugin systems, and other scenarios requiring grow-only collections with immutability guarantees.

accretive.__version__: str = '4.1'¶

Module `accretive.dictionaries`¶

Accretive dictionaries.

Dictionaries which can grow but never shrink. Once an entry is added, it cannot be modified or removed.

AbstractDictionary: Base class defining the accretive dictionary interface. Implementations must provide __getitem__, __iter__, __len__, and storage methods.
Dictionary: Standard implementation of an accretive dictionary. Supports all usual dict operations except those that would modify or remove existing entries.
ProducerDictionary: Automatically generates values for missing keys using a supplied factory function. Similar to collections.defaultdict but with accretive behavior.
ValidatorDictionary: Validates entries before addition using a supplied predicate function.
ProducerValidatorDictionary: Combines producer and validator behaviors. Generated values must pass validation before being added.

>>> from accretive import Dictionary
>>> d = Dictionary( apples = 12, bananas = 6 )
>>> d[ 'cherries' ] = 42  # Add new entry
>>> d[ 'apples' ] = 14    # Attempt modification
Traceback (most recent call last):
    ...
accretive.exceptions.EntryImmutability: Could not alter or remove existing entry for 'apples'.
>>> del d[ 'bananas' ]    # Attempt removal
Traceback (most recent call last):
    ...
accretive.exceptions.EntryImmutability: Could not alter or remove existing entry for 'bananas'.

>>> from accretive import ProducerDictionary
>>> d = ProducerDictionary( list )  # list() called for missing keys
>>> d[ 'new' ]
[]
>>> d[ 'new' ].append( 1 )  # List is mutable, but entry is fixed
>>> d[ 'new' ] = [ ]  # Attempt modification
Traceback (most recent call last):
    ...
accretive.exceptions.EntryImmutability: Could not alter or remove existing entry for 'new'.

>>> from accretive import ValidatorDictionary
>>> d = ValidatorDictionary( lambda k, v: isinstance( v, int ) )
>>> d[ 'valid' ] = 42  # Passes validation
>>> d[ 'invalid' ] = 'str'  # Fails validation
Traceback (most recent call last):
    ...
accretive.exceptions.EntryInvalidity: Could not add invalid entry with key, 'invalid', and value, 'str', to dictionary.

class accretive.dictionaries.AbstractDictionary¶

Bases: Mapping[H, V]

Abstract base class for dictionaries that can grow but not shrink.

An accretive dictionary allows new entries to be added but prevents modification or removal of existing entries. This provides a middle ground between immutable and fully mutable mappings.

Implementations must provide: - __getitem__, __iter__, __len__ - _pre_setitem_ for entry validation/preparation - _store_item_ for storage implementation

setdefault(key, default)¶

Returns value for key, setting it to default if missing.

Parameters:

self
key (accretive.__.nomina.H)
default (accretive.__.nomina.V)

Return type:

accretive.__.nomina.V

update(*iterables, **entries)¶

Adds new entries as a batch. Returns self.

Parameters:

self
iterables (collections.abc.Mapping[ accretive.__.nomina.H, accretive.__.nomina.V ] | collections.abc.Iterable[ tuple[ accretive.__.nomina.H, accretive.__.nomina.V ] ]) – Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.
entries (accretive.__.nomina.V) – Zero or more keyword arguments from which to initialize dictionary data.

Return type:

typing_extensions.Self

class accretive.dictionaries.Dictionary(*iterables, **entries)¶

Bases: _DictionaryOperations[H, V]

Accretive dictionary.

Accretes dictionary entries.

copy()¶

Provides fresh copy of dictionary.

Parameters:: self
Return type:: typing_extensions.Self

get(key, default=absence.absent)¶

Retrieves entry associated with key, if it exists.

Parameters:

self
key (accretive.__.nomina.H)
default (accretive.__.nomina.V | absence.objects.AbsentSingleton)

Returns:

Value of entry, if it exists. Else, supplied default value or None.

Return type:

accretive.__.nomina.V

items()¶

Provides iterable view over dictionary items.

Parameters:: self
Return type:: collections.abc.ItemsView[ accretive.__.nomina.H, accretive.__.nomina.V ]

keys()¶

Provides iterable view over dictionary keys.

Parameters:: self
Return type:: collections.abc.KeysView[ accretive.__.nomina.H ]

values()¶

Provides iterable view over dictionary values.

Parameters:: self
Return type:: collections.abc.ValuesView[ accretive.__.nomina.V ]

with_data(*iterables, **entries)¶

Parameters:

self
iterables (collections.abc.Mapping[ accretive.__.nomina.H, accretive.__.nomina.V ] | collections.abc.Iterable[ tuple[ accretive.__.nomina.H, accretive.__.nomina.V ] ]) – Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.
entries (accretive.__.nomina.V) – Zero or more keyword arguments from which to initialize dictionary data.

Return type:

typing_extensions.Self

class accretive.dictionaries.ProducerDictionary(producer, /, *iterables, **entries)¶

Bases: Dictionary[H, V]

Accretive dictionary with default value for missing entries.

Accretes dictionary entries.

Produces default entries on attempt to access absent ones.

Variables:: _producer_ (collections.abc.Callable[ [ ], accretive.__.nomina.V ]) – Callable which produces values for absent dictionary entries.

copy()¶

Provides fresh copy of dictionary.

Parameters:: self
Return type:: typing_extensions.Self

setdefault(key, default)¶

Returns value for key, setting it to default if missing.

Parameters:

self
key (accretive.__.nomina.H)
default (accretive.__.nomina.V)

Return type:

accretive.__.nomina.V

with_data(*iterables, **entries)¶

Parameters:

self
iterables (collections.abc.Mapping[ accretive.__.nomina.H, accretive.__.nomina.V ] | collections.abc.Iterable[ tuple[ accretive.__.nomina.H, accretive.__.nomina.V ] ]) – Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.
entries (accretive.__.nomina.V) – Zero or more keyword arguments from which to initialize dictionary data.

Return type:

typing_extensions.Self

class accretive.dictionaries.ProducerValidatorDictionary(producer, validator, /, *iterables, **entries)¶

Bases: Dictionary[H, V]

Accretive dictionary with defaults and validation.

Accretes dictionary entries.

Produces default entries on attempt to access absent ones.

Validates dictionary entries on initialization.

Variables:

_producer_ (collections.abc.Callable[ [ ], accretive.__.nomina.V ]) – Callable which produces values for absent dictionary entries.
_validator_ (collections.abc.Callable[ [ accretive.__.nomina.H, accretive.__.nomina.V ], bool ]) – Callable which validates entries before addition to dictionary.

copy()¶

Provides fresh copy of dictionary.

Parameters:: self
Return type:: typing_extensions.Self

setdefault(key, default)¶

Returns value for key, setting it to default if missing.

Parameters:

self
key (accretive.__.nomina.H)
default (accretive.__.nomina.V)

Return type:

accretive.__.nomina.V

with_data(*iterables, **entries)¶

Parameters:

self
iterables (collections.abc.Mapping[ accretive.__.nomina.H, accretive.__.nomina.V ] | collections.abc.Iterable[ tuple[ accretive.__.nomina.H, accretive.__.nomina.V ] ]) – Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.
entries (accretive.__.nomina.V) – Zero or more keyword arguments from which to initialize dictionary data.

Return type:

typing_extensions.Self

class accretive.dictionaries.ValidatorDictionary(validator, /, *iterables, **entries)¶

Bases: Dictionary[H, V]

Accretive dictionary with validation of new entries.

Accretes dictionary entries.

Validates dictionary entries on initialization.

Variables:: _validator_ (collections.abc.Callable[ [ accretive.__.nomina.H, accretive.__.nomina.V ], bool ]) – Callable which validates entries before addition to dictionary.

copy()¶

Provides fresh copy of dictionary.

Parameters:: self
Return type:: typing_extensions.Self

with_data(*iterables, **entries)¶

Parameters:

self
iterables (collections.abc.Mapping[ accretive.__.nomina.H, accretive.__.nomina.V ] | collections.abc.Iterable[ tuple[ accretive.__.nomina.H, accretive.__.nomina.V ] ]) – Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.
entries (accretive.__.nomina.V) – Zero or more keyword arguments from which to initialize dictionary data.

Return type:

typing_extensions.Self

Module `accretive.namespaces`¶

Accretive namespaces.

Provides a namespace type that can grow but never shrink. Once an attribute is set, it cannot be modified or removed. This provides a simple way to create objects with named attributes that become immutable after assignment.

The namespace implementation is modeled after types.SimpleNamespace but adds accretive behavior. Like types.SimpleNamespace, it provides a simple __repr__ which lists all attributes.

>>> from accretive import Namespace
>>> ns = Namespace( apples = 12, bananas = 6 )
>>> ns.cherries = 42  # Add new attribute
>>> ns.apples = 14    # Attempt modification
Traceback (most recent call last):
    ...
accretive.exceptions.AttributeImmutability: Could not assign or delete existing attribute 'apples'.
>>> del ns.bananas    # Attempt deletion
Traceback (most recent call last):
    ...
accretive.exceptions.AttributeImmutability: Could not assign or delete existing attribute 'bananas'.

class accretive.namespaces.Namespace(*iterables, **attributes)¶

Bases: object

Accretive namespaces.

Module `accretive.modules`¶

Accretive modules.

Provides a module type that enforces attribute immutability after assignment. This helps ensure that module-level constants remain constant and that module interfaces remain stable during runtime.

The module implementation is derived from types.ModuleType and adds accretive behavior. This makes it particularly useful for:

Ensuring constants remain constant
Preventing accidental modification of module interfaces

Also provides a convenience function:

reclassify_modules: Converts existing modules to accretive modules.

type accretive.modules.ModuleNamespaceDictionary = collections.abc.Mapping[str, typing_extensions.Any]¶

type accretive.modules.DynadocIntrospectionArgument = dynadoc.context.IntrospectionControl | absence.objects.AbsentSingleton¶

type accretive.modules.FinalizeModuleDynadocTableArgument = collections.abc.Mapping[str, str] | absence.objects.AbsentSingleton¶

type accretive.modules.ModuleArgument = str | types.ModuleType¶

type accretive.modules.ModuleNamespaceArgument = str | types.ModuleType | collections.abc.Mapping[str, typing_extensions.Any]¶

type accretive.modules.RecursiveArgument = bool¶

type accretive.modules.ReplacementClassArgument = type[types.ModuleType]¶

class accretive.modules.Module(*posargs, **nomargs)¶

Bases: ModuleType

Accretive module.

Python module class, derived from types.ModuleType.

By default, conceals non-public module attributes.

By default, accrets module attributes.

accretive.modules.finalize_module(module, /, *fragments, attributes_namer=<function calculate_attrname>, dynadoc_introspection=absence.absent, dynadoc_table=absence.absent, recursive=False, replacement_class=<class 'accretive.modules.Module'>)¶

Combines Dynadoc docstring assignment and module reclassification.

Applies module docstring generation via Dynadoc introspection, then reclassifies modules for accretion 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.
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 | absence.objects.AbsentSingleton) –
Dynadoc introspection control.

Which kinds of object to recursively introspect? Scan unnannotated attributes? Consider base classes? Etc…
dynadoc_table (collections.abc.Mapping[ str, str ] | absence.objects.AbsentSingleton) – Table of documentation fragments.
recursive (bool) – Recursively reclassify package modules?
replacement_class (type[ types.ModuleType ]) – New class for module.

accretive.modules.reclassify_modules(module, /, *, recursive=False)¶

Reclassifies modules to be accretive.

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-accretive modules.

Parameters:

module (str | types.ModuleType | collections.abc.Mapping[ str, typing_extensions.Any ]) – Module, module name, or module namespace.
recursive (bool) – Recursively reclassify package modules?

Module `accretive.classes`¶

Accretive classes.

class accretive.classes.AbstractBaseClass(name, bases, namespace, *, decorators=(), **arguments)¶

Bases: ABCMeta

Metaclass for standard abstract base classes.

Produces abstract base classes compatible with abc.ABCMeta.

By default, conceals non-public class attributes.

By default, accretes class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class accretive.classes.Class(name, bases, namespace, *, decorators=(), **arguments)¶

Bases: type

Metaclass for standard classes.

By default, conceals non-public class attributes.

By default, accretes class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class accretive.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, accretes class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class accretive.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, accretes class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

class accretive.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, accretes instance attributes.

class accretive.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 accretive.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, accretes instance attributes.

class accretive.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 accretive.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, accretes instance attributes.

class accretive.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 accretive.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, accretes instance attributes.

class accretive.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, accretes class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class accretive.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, accretes class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class accretive.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, accretes class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

class accretive.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.

accretive.classes.dataclass_with_standard_behaviors(cls=absence.absent, /, *, decorators=(), mutables=(), visibles=(<function is_public_identifier>, ))¶

Decorates dataclass to enforce standard behaviors on instances.

Parameters:

cls (type[ accretive.__.nomina.U ] | absence.objects.AbsentSingleton)
decorators (collections.abc.Sequence[ collections.abc.Callable[ [ type[ accretive.__.nomina.U ] ], type[ accretive.__.nomina.U ] ] ])
mutables (collections.abc.Sequence[ str | re.Pattern[ str ] | collections.abc.Callable[ [ str ], bool ] ] | Literal[ '*' ])
visibles (collections.abc.Sequence[ str | re.Pattern[ str ] | collections.abc.Callable[ [ str ], bool ] ] | Literal[ '*' ])

Return type:

type[ accretive.__.nomina.U ] | collections.abc.Callable[ …, collections.abc.Callable[ [ type[ accretive.__.nomina.U ] ], type[ accretive.__.nomina.U ] ] ]

accretive.classes.with_standard_behaviors(cls=absence.absent, /, *, decorators=(), mutables=(), visibles=(<function is_public_identifier>, ))¶

Decorates class to enforce standard behaviors on instances.

Parameters:

cls (type[ accretive.__.nomina.U ] | absence.objects.AbsentSingleton)
decorators (collections.abc.Sequence[ collections.abc.Callable[ [ type[ accretive.__.nomina.U ] ], type[ accretive.__.nomina.U ] ] ])
mutables (collections.abc.Sequence[ str | re.Pattern[ str ] | collections.abc.Callable[ [ str ], bool ] ] | Literal[ '*' ])
visibles (collections.abc.Sequence[ str | re.Pattern[ str ] | collections.abc.Callable[ [ str ], bool ] ] | Literal[ '*' ])

Return type:

type[ accretive.__.nomina.U ] | collections.abc.Callable[ …, collections.abc.Callable[ [ type[ accretive.__.nomina.U ] ], type[ accretive.__.nomina.U ] ] ]

Module `accretive.exceptions`¶

Family of exceptions for package API.

Provides a hierarchy of exceptions that are raised when accretive behavior is violated. The hierarchy is designed to allow both specific and general exception handling.

exception accretive.exceptions.AttributeImmutability(name, target)¶: Bases: Omnierror, AttributeError, TypeError

exception accretive.exceptions.EntryImmutability(indicator)¶: Bases: Omnierror, TypeError

exception accretive.exceptions.EntryInvalidity(indicator, value)¶: Bases: Omnierror, ValueError

exception accretive.exceptions.ErrorProvideFailure(name, reason)¶: Bases: Omnierror, RuntimeError

exception accretive.exceptions.Omnierror(*posargs, **nomargs)¶

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

exception accretive.exceptions.Omniexception(*posargs, **nomargs)¶

Bases: Object, BaseException

Base exceptions for package.

API¶

Package accretive¶

Module accretive.dictionaries¶

Module accretive.namespaces¶

Module accretive.modules¶

Module accretive.classes¶

Module accretive.exceptions¶

Package `accretive`¶

Module `accretive.dictionaries`¶

Module `accretive.namespaces`¶

Module `accretive.modules`¶

Module `accretive.classes`¶

Module `accretive.exceptions`¶