API

Package frigid

Immutable data structures.

Data structures which are completely immutable after creation. This behavior is useful for configuration objects, value objects, and other scenarios requiring collections with strong immutability guarantees.

frigid.__version__: str = '4.1'

Module frigid.dictionaries

Immutable dictionaries.

Dictionaries which cannot be modified after creation.

Note

While types.MappingProxyType also provides a read-only view of a dictionary, it has important differences from Dictionary:

  • A MappingProxyType is a view over a mutable dictionary, so its contents can still change if the underlying dictionary is modified.

  • Dictionary owns its data and guarantees that it will never change.

  • Dictionary provides set operations (union, intersection) that maintain immutability guarantees.

Use MappingProxyType when you want to expose a read-only view of a dictionary that might need to change. Use Dictionary when you want to ensure that the data can never change, such as for configuration objects or other cases requiring strong immutability guarantees.

  • AbstractDictionary: Base class defining the immutable dictionary interface. Implementations must provide __getitem__, __iter__, and __len__.

  • Dictionary: Standard implementation of an immutable dictionary. Supports all usual dict read operations but prevents any modifications.

  • ValidatorDictionary: Validates entries before addition using a supplied predicate function.

>>> from frigid import Dictionary
>>> d = Dictionary( x = 1, y = 2 )
>>> d[ 'z' ] = 3  # Attempt to add entry
Traceback (most recent call last):
    ...
frigid.exceptions.EntryImmutability: Cannot assign or delete entry for 'z'.
>>> d[ 'x' ] = 4  # Attempt modification
Traceback (most recent call last):
    ...
frigid.exceptions.EntryImmutability: Cannot assign or delete entry for 'x'.
>>> del d[ 'y' ]  # Attempt removal
Traceback (most recent call last):
    ...
frigid.exceptions.EntryImmutability: Cannot assign or delete entry for 'y'.
class frigid.dictionaries.AbstractDictionary

Bases: Mapping[H, V]

Abstract base class for immutable dictionaries.

An immutable dictionary prevents modification or removal of entries after creation. This provides a clean interface for dictionaries that should never change.

Implementations must provide __getitem__, __iter__, __len__.

class frigid.dictionaries.Dictionary(*iterables, **entries)

Bases: _DictionaryOperations[H, V]

Immutable dictionary.

Protects dictionary entries on initialization.

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 (frigid.__.nomina.H)

  • default (frigid.__.nomina.V | absence.objects.AbsentSingleton)

Returns:

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

Return type:

frigid.__.nomina.V

items()

Provides iterable view over dictionary items.

Parameters:

self

Return type:

collections.abc.ItemsView[ frigid.__.nomina.H, frigid.__.nomina.V ]

keys()

Provides iterable view over dictionary keys.

Parameters:

self

Return type:

collections.abc.KeysView[ frigid.__.nomina.H ]

values()

Provides iterable view over dictionary values.

Parameters:

self

Return type:

collections.abc.ValuesView[ frigid.__.nomina.V ]

with_data(*iterables, **entries)
Parameters:

  • self

  • iterables (collections.abc.Mapping[ frigid.__.nomina.H, frigid.__.nomina.V ] | collections.abc.Iterable[ tuple[ frigid.__.nomina.H, frigid.__.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 (frigid.__.nomina.V) – Zero or more keyword arguments from which to initialize dictionary data.

Return type:

typing_extensions.Self

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

Bases: Dictionary[H, V]

Immutable dictionary with validation of entries on initialization.

Protects dictionary entries on initialization.

Validates dictionary entries on initialization.

Variables:

_validator_ (collections.abc.Callable[ [ frigid.__.nomina.H, frigid.__.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)

Creates new dictionary with same behavior but different data.

Parameters:

  • self

  • iterables (collections.abc.Mapping[ frigid.__.nomina.H, frigid.__.nomina.V ] | collections.abc.Iterable[ tuple[ frigid.__.nomina.H, frigid.__.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 (frigid.__.nomina.V) – Zero or more keyword arguments from which to initialize dictionary data.

Return type:

typing_extensions.Self

Module frigid.namespaces

Immutable namespaces.

Provides a namespace type with immutable attributes. Similar to types.SimpleNamespace, but attributes cannot be modified or deleted after initialization.

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

>>> from frigid import Namespace
>>> ns = Namespace( x = 1, y = 2 )
>>> ns.z = 3  # Attempt to add attribute
Traceback (most recent call last):
    ...
frigid.exceptions.AttributeImmutability: Could not assign or delete attribute 'z'.
>>> ns.x = 4  # Attempt modification
Traceback (most recent call last):
    ...
frigid.exceptions.AttributeImmutability: Could not assign or delete attribute 'x'.
>>> ns
frigid.namespaces.Namespace( x = 1, y = 2 )
class frigid.namespaces.Namespace(*iterables, **attributes)

Bases: object

Immutable namespaces.

Module frigid.modules

Immutable modules.

Provides a module type that enforces complete attribute immutability. 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 immutability. This makes it particularly useful for:

  • Ensuring constants remain constant

  • Preventing modification of module interfaces

Also provides a convenience function:

  • reclassify_modules: Converts existing modules to immutable modules.

type frigid.modules.ModuleNamespaceDictionary = collections.abc.Mapping[str, typing_extensions.Any]
type frigid.modules.DynadocIntrospectionArgument = dynadoc.context.IntrospectionControl | absence.objects.AbsentSingleton
type frigid.modules.FinalizeModuleDynadocTableArgument = collections.abc.Mapping[str, str] | absence.objects.AbsentSingleton
type frigid.modules.ModuleArgument = str | types.ModuleType
type frigid.modules.ModuleNamespaceArgument = str | types.ModuleType | collections.abc.Mapping[str, typing_extensions.Any]
type frigid.modules.RecursiveArgument = bool
type frigid.modules.ReplacementClassArgument = type[types.ModuleType]
class frigid.modules.Module(*posargs, **nomargs)

Bases: Object, ModuleType

Immutable module.

Python module class, derived from types.ModuleType.

By default, conceals non-public module attributes.

By default, protects module attributes.

frigid.modules.finalize_module(module, /, *fragments, attributes_namer=<function calculate_attrname>, dynadoc_introspection=absence.absent, dynadoc_table=absence.absent, recursive=False, replacement_class=<class 'frigid.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.

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

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

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:

Module frigid.classes

Immutable classes.

class frigid.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, protects class attributes.

Applies Dynadoc decoration to classes.

Produces classes which can conceal instance attributes.

Produces classes which can protect instance attributes.

class frigid.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 frigid.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 frigid.classes.DataclassMutable(name, bases, namespace, *, decorators=(), **arguments)

Bases: type

Metaclass for dataclasses with mutable instances.

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

Bases: _ProtocolMeta

Metaclass for protocol dataclasses with mutable instances.

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

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

Decorates dataclass to enforce standard behaviors on instances.

Parameters:
Return type:

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

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

Decorates class to enforce standard behaviors on instances.

Parameters:
Return type:

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

Module frigid.exceptions

Family of exceptions for package API.

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

exception frigid.exceptions.AttributeImmutability(name, target)

Bases: Omnierror, AttributeError

exception frigid.exceptions.EntryImmutability(key)

Bases: Omnierror, TypeError

exception frigid.exceptions.EntryInvalidity(indicator, value)

Bases: Omnierror, ValueError

exception frigid.exceptions.ErrorProvideFailure(name, reason)

Bases: Omnierror, RuntimeError

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

Bases: Omniexception, Exception

Base error for package.

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

Bases: Object, BaseException

Base exceptions for package.

Module frigid.installers

Convenience to expose certain package features as Python builtins.

frigid.installers.install(single_name='one')

Installs 1-element tuple constructor into builtins.

Parameters:

single_name (str | None) – Name to use for single function in builtins. None to skip.

Module frigid.sequences

Immutable sequences.

frigid.sequences.one(value)

Produces single-item tuple from value.

Provides a more explicit and readable alternative to the comma-syntax for creating single-item tuples. While Python allows ( x, ) for creating single-item tuples, using one( x ) can be clearer, especially in certain contexts:

  • List comprehensions and generator expressions

  • Situations where formatter behavior with trailing commas is undesired

Parameters:

value (frigid.__.nomina.V)

Return type:

tuple[ frigid.__.nomina.V, … ]