diff --git a/documentation/architecture/decisions/index.rst b/documentation/architecture/decisions/index.rst index a84ce73..8823a84 100644 --- a/documentation/architecture/decisions/index.rst +++ b/documentation/architecture/decisions/index.rst @@ -24,8 +24,7 @@ Architectural Decision Records .. toctree:: :maxdepth: 2 - -.. todo:: Add architectural decision records to toctree. + suggested-adrs For ADR format and guidance, see the `architecture documentation guide `_. \ No newline at end of file diff --git a/documentation/architecture/decisions/suggested-adrs.rst b/documentation/architecture/decisions/suggested-adrs.rst new file mode 100644 index 0000000..774f40d --- /dev/null +++ b/documentation/architecture/decisions/suggested-adrs.rst @@ -0,0 +1,107 @@ +.. vim: set fileencoding=utf-8: +.. -*- coding: utf-8 -*- +.. +--------------------------------------------------------------------------+ + | | + | Licensed under the Apache License, Version 2.0 (the "License"); | + | you may not use this file except in compliance with the License. | + | You may obtain a copy of the License at | + | | + | http://www.apache.org/licenses/LICENSE-2.0 | + | | + | Unless required by applicable law or agreed to in writing, software | + | distributed under the License is distributed on an "AS IS" BASIS, | + | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | + | See the License for the specific language governing permissions and | + | limitations under the License. | + | | + +--------------------------------------------------------------------------+ + + +******************************************************************************* +Suggested Architectural Decision Records +******************************************************************************* + +This document lists potential ADRs that could be created to document the +architectural decisions already implemented in the codebase. These are provided +as suggestions for future documentation efforts. + +ADR-001: Metaclass-Based Interception for Accretive Behavior +=============================================================================== + +**Decision**: Use metaclass-based interception via ``__setattr__`` and +``__delattr__`` hooks that delegate to a configurable ``assigner_core`` +function. + +**Context**: Need to intercept attribute assignment to enforce immutability +after first assignment. Multiple approaches available: descriptors, +``__getattribute__``/``__setattr__`` overrides, proxies, metaclasses. + +**Key Alternatives**: + +* Descriptors: Only work for class-level attributes, not instance attributes +* Direct ``__setattr__`` override: Doesn't integrate well with class factory + pattern +* Proxies: Add indirection and complicate type checking + +**Consequences**: Consistent behavior across all accretive types, integration +with classcore's class factory system, single metaclass constraint, clean +separation of assignment logic from type definitions. + +ADR-002: Grow-Only Semantics vs Other Immutability Patterns +=============================================================================== + +**Decision**: Implement accretive (grow-only) semantics: values can be added +but never modified or removed. + +**Context**: Need immutability guarantees for collections. Multiple patterns +available: fully immutable, copy-on-write, persistent data structures, +accretive (grow-only). + +**Key Alternatives**: + +* Fully immutable: No growth after initialization (frozen dataclasses, tuples) +* Copy-on-write: Performance overhead, memory consumption +* Persistent data structures: Complexity, unfamiliar APIs + +**Consequences**: Middle ground between mutable and immutable, useful for +registries/plugins/caches, shallow immutability only, clear use case +differentiation from existing libraries. + +ADR-003: Integration with classcore Class Factory +=============================================================================== + +**Decision**: Build on classcore's ``class_factory`` and behavior configuration +system. + +**Context**: Need consistent behavior configuration across multiple class types +(Class, Dataclass, Module, etc.). Could implement from scratch or build on +existing infrastructure. + +**Key Alternatives**: + +* Implement custom metaclass infrastructure: Duplication, maintenance burden +* Use standard Python mechanisms only: Less flexibility, more boilerplate + +**Consequences**: Dependency on classcore package, consistent configuration API +across all types, reuse of well-tested behavior management code, leverages +dynadoc integration and behavior exclusions (mutables predicates/regexes). + +ADR-004: Exception Hierarchy Multiple Inheritance +=============================================================================== + +**Decision**: Use multiple inheritance for exceptions: inherit from both package +base (``Omnierror``) and appropriate standard library exceptions +(``AttributeError``, ``TypeError``, ``ValueError``). + +**Context**: Need exceptions that are both package-specific (for targeted +catching) and compatible with standard library exception handling patterns. + +**Key Alternatives**: + +* Only inherit from package base: Breaks compatibility with standard exception + handlers +* Only inherit from stdlib: Can't catch all package errors with single base + +**Consequences**: Both specific (``catch AttributeImmutability``) and general +(``catch Omnierror``) handling possible, compatible with standard exception +hierarchies, clear isinstance checks work as expected. diff --git a/documentation/architecture/filesystem.rst b/documentation/architecture/filesystem.rst index 98c8ffc..5942064 100644 --- a/documentation/architecture/filesystem.rst +++ b/documentation/architecture/filesystem.rst @@ -57,15 +57,22 @@ The main Python package follows the standard ``sources/`` directory pattern: .. code-block:: sources/ - ├── accretive/ # Main Python package - │ ├── __/ # Centralized import hub - │ │ ├── __init__.py # Re-exports core utilities - │ │ ├── imports.py # External library imports - │ │ └── nomina.py # python-accretive-specific naming constants - │ ├── __init__.py # Package entry point - │ ├── py.typed # Type checking marker - │ ├── exceptions.py # Package exception hierarchy - │ └── [modules].py # Feature-specific modules + └── accretive/ # Main Python package + ├── __/ # Centralized import hub + │ ├── __init__.py # Re-exports core utilities + │ ├── dictionaries.py # Internal dictionary utilities and type aliases + │ ├── doctab.py # Documentation fragment table + │ ├── exceptions.py # Internal exception utilities + │ ├── imports.py # External library imports + │ └── nomina.py # Package-specific naming constants + ├── __init__.py # Package entry point + ├── py.typed # Type checking marker + ├── classes.py # Accretive class metaclasses and decorators + ├── dictionaries.py # Accretive dictionary implementations + ├── exceptions.py # Package exception hierarchy + ├── iclasses.py # Internal class implementations + ├── modules.py # Accretive module implementation + └── namespaces.py # Accretive namespace implementation All package modules use the standard ``__`` import pattern as documented diff --git a/documentation/architecture/index.rst b/documentation/architecture/index.rst index 6f09ef9..1f5e028 100644 --- a/documentation/architecture/index.rst +++ b/documentation/architecture/index.rst @@ -28,7 +28,4 @@ Architecture filesystem decisions/index designs/index - testplans/index - - -.. todo:: Populate architecture documentation sections. \ No newline at end of file + testplans/index \ No newline at end of file diff --git a/documentation/architecture/summary.rst b/documentation/architecture/summary.rst index bab368a..b30d38d 100644 --- a/documentation/architecture/summary.rst +++ b/documentation/architecture/summary.rst @@ -21,4 +21,200 @@ System Overview ******************************************************************************* -.. todo:: Describe the high-level system architecture, major components, and their relationships. \ No newline at end of file +Accretive provides a family of data structures that enforce a grow-only +constraint: values can be added but never modified or removed once set. This +library addresses the need for collections that accumulate state with +immutability guarantees, useful for configuration registries, plugin systems, +and scenarios requiring sticky state. + +Core Architectural Concept +=============================================================================== + +The library implements accretion through attribute assignment interception at +the metaclass level. When an assignment is attempted, the system checks whether +the attribute already exists and whether it is marked as mutable. If the +attribute exists and is not mutable, an exception is raised. + +Major Components +=============================================================================== + +The architecture is organized into four primary component categories: + +Accretive Dictionaries +------------------------------------------------------------------------------- + +Mapping-based collections that prevent modification of existing entries: + +* **AbstractDictionary**: Base class defining the accretive dictionary + interface. Implements ``collections.abc.Mapping`` with custom ``__setitem__`` + to enforce immutability of existing entries. + +* **Dictionary**: Standard accretive dictionary implementation. Supports + initialization from multiple iterables and keyword arguments. + +* **ProducerDictionary**: Auto-generates values for missing keys via factory + function. Similar to ``collections.defaultdict`` with accretive behavior. + +* **ValidatorDictionary**: Validates entries before addition using predicate + function. Invalid entries are rejected rather than added. + +* **ProducerValidatorDictionary**: Combines producer and validator behaviors. + Generated values must pass validation before being stored. + +Accretive Namespaces +------------------------------------------------------------------------------- + +Attribute-based containers modeled after ``types.SimpleNamespace``: + +* **Namespace**: Allows dynamic attribute addition with immutability after + assignment. Uses custom metaclass to intercept attribute assignment via + ``__setattr__`` and ``__delattr__``. + +Accretive Classes +------------------------------------------------------------------------------- + +Metaclasses and decorators for creating user-defined accretive types: + +* **Class**: Standard metaclass for classes with accretive instances. + +* **Dataclass**: Metaclass for dataclasses with immutable instances. + +* **DataclassMutable**: Metaclass for dataclasses with mutable instance + attributes but immutable class-level behavior. + +* **Object**: Concrete class providing standard accretive behavior via + composition rather than metaclass. + +These leverage the ``classcore`` library's class factory system to provide +consistent behavior configuration across all class types. + +Accretive Modules +------------------------------------------------------------------------------- + +Runtime module reclassification for enforcing module-level immutability: + +* **Module**: Accretive variant of ``types.ModuleType``. + +* **finalize_module**: Utility to reclassify existing modules as accretive, + optionally processing entire package hierarchies recursively. + +Component Relationships +=============================================================================== + +Architecture Layers +------------------------------------------------------------------------------- + +The system is organized in layers of abstraction:: + + ┌─────────────────────────────────────────────────────────┐ + │ Public API Layer │ + │ (dictionaries, namespaces, classes, modules) │ + └─────────────────────────────────────────────────────────┘ + │ + ↓ + ┌─────────────────────────────────────────────────────────┐ + │ Behavior Implementation Layer (iclasses) │ + │ (assign_attribute_if_absent_mutable) │ + └─────────────────────────────────────────────────────────┘ + │ + ↓ + ┌─────────────────────────────────────────────────────────┐ + │ Foundation Layer (classcore) │ + │ (class_factory, assigner system) │ + └─────────────────────────────────────────────────────────┘ + +External Dependencies +------------------------------------------------------------------------------- + +* **classcore**: Provides the class factory system and behavior configuration + mechanisms. The ``class_factory`` function creates metaclasses with + configurable attribute assignment interceptors. + +* **dynadoc**: Automatic docstring generation from type annotations and + documentation fragments. + +* **absence**: Sentinel value for optional parameters, distinguishing between + ``None`` and truly absent values. + +* **frigid**: Immutable data structures used internally for storing + configuration and metadata. + +Key Architectural Patterns +=============================================================================== + +Metaclass-Based Interception +------------------------------------------------------------------------------- + +All accretive behavior is implemented via metaclass ``__setattr__`` and +``__delattr__`` hooks that delegate to the ``assigner_core`` function. This +allows consistent behavior across all accretive types while maintaining +compatibility with standard Python semantics. + +Assignment Core Strategy +------------------------------------------------------------------------------- + +The ``assign_attribute_if_absent_mutable`` function implements the core logic: + +1. Check if attribute exists using ``hasattr`` +2. If absent, allow assignment +3. If present, check immutability behaviors configuration +4. Check mutables exclusions (names, predicates, regexes) +5. If not mutable, raise ``AttributeImmutability`` exception +6. Otherwise, allow assignment + +Cascading Import Hub Pattern +------------------------------------------------------------------------------- + +The ``__`` subpackage centralizes all external imports, providing consistent +namespace management and reducing import duplication. All modules use +``from . import __`` to access common dependencies. + +Data Flow +=============================================================================== + +Entry Addition Flow (Dictionaries) +------------------------------------------------------------------------------- + +1. User calls ``dict[key] = value`` or ``dict.update(...)`` +2. ``__setitem__`` checks if key exists +3. If key exists, raises ``EntryImmutability`` exception +4. If key absent, calls ``_pre_setitem_`` for validation +5. Calls ``_store_item_`` to persist entry +6. Entry becomes immutable + +Attribute Assignment Flow (Namespaces, Classes, Modules) +------------------------------------------------------------------------------- + +1. User assigns ``obj.attr = value`` or ``del obj.attr`` +2. Metaclass intercepts via ``__setattr__`` or ``__delattr__`` +3. Delegates to ``assign_attribute_if_absent_mutable`` +4. Function checks existence and mutability status +5. If immutable and exists, raises ``AttributeImmutability`` exception +6. Otherwise completes assignment/deletion + +Performance Considerations +=============================================================================== + +* **Import Centralization**: The ``__`` pattern front-loads import costs to + package initialization time rather than individual module import time. + +* **Attribute Lookup**: Immutability checks require metadata lookups + (behaviors, mutables predicates) on each assignment attempt. Cached lookups + minimize this overhead. + +* **Dictionary Storage**: Uses standard ``dict`` internally for O(1) lookups. + +Error Handling Strategy +=============================================================================== + +The package defines a clear exception hierarchy rooted in ``Omniexception``: + +* **Omnierror**: Base for all operational errors +* **AttributeImmutability**: Raised when attempting to modify immutable + attributes (inherits from ``AttributeError`` and ``TypeError``) +* **EntryImmutability**: Raised when attempting to modify dictionary entries +* **EntryInvalidity**: Raised when validation fails in validator dictionaries +* **ErrorProvideFailure**: Raised when error class lookup fails + +This design allows both specific exception handling (catch +``AttributeImmutability``) and general handling (catch ``Omnierror``). \ No newline at end of file diff --git a/documentation/architecture/testplans/summary.rst b/documentation/architecture/testplans/summary.rst index d480c7f..a4bbb29 100644 --- a/documentation/architecture/testplans/summary.rst +++ b/documentation/architecture/testplans/summary.rst @@ -60,7 +60,29 @@ The test planning process systematically addresses: Test Module Numbering Scheme =============================================================================== -.. todo:: Define project-specific test module numbering conventions. +The test suite uses a hierarchical numbering system for clear organization: + +**Package-Level Organization** + +- **test_000_accretive/**: Main test package for the accretive package + - **test_000_package.py**: Package-level tests (imports, version, metadata) + - **test_010_base.py**: Base functionality and common test utilities + - **test_013_dictionaries.py**: Early dictionary-related utilities or base classes + - **test_100_classes.py**: Tests for accretive classes (Class, Dataclass, Object) + - **test_110_iclasses.py**: Tests for internal class implementations + - **test_200_exceptions.py**: Exception hierarchy testing + - **test_300_namespaces.py**: Namespace class tests + - **test_400_modules.py**: Module class and finalize_module tests + - **test_500_dictionaries.py**: Dictionary classes tests + +**Numbering Conventions** + +- **000-099**: Package infrastructure and shared utilities +- **100-199**: Class and metaclass functionality +- **200-299**: Exception handling and error cases +- **300-399**: Namespace implementations +- **400-499**: Module implementations +- **500-599**: Dictionary implementations Test Function Numbering =============================================================================== diff --git a/documentation/prd.rst b/documentation/prd.rst index 85bf640..c10568a 100644 --- a/documentation/prd.rst +++ b/documentation/prd.rst @@ -21,7 +21,404 @@ Product Requirements Document ******************************************************************************* -.. todo:: Define product requirements, user stories, and acceptance criteria. +Executive Summary +=============================================================================== -For PRD format and guidance, see the `requirements documentation guide -`_. \ No newline at end of file +The package provides data structures that enforce a grow-only constraint: values +can be added but never modified or removed once set. It offers accretive +variants of familiar Python types (dictionaries, namespaces, classes, modules) +with consistent APIs and flexible configuration options for selective +mutability. + +The package addresses the need for collections that accumulate state with +immutability guarantees, particularly valuable for configuration registries, +plugin systems, and scenarios requiring sticky state. By providing a middle +ground between fully immutable and fully mutable collections, the package +enables developers to build safer, more predictable systems. + +Problem Statement +=============================================================================== + +Who Experiences the Problem +------------------------------------------------------------------------------- + +Python developers building systems that require: + +* Configuration registries where entries must persist once registered +* Plugin architectures where registered extensions must remain available +* Caching systems where entries should never be invalidated +* Event handlers or callback registries with guaranteed availability +* Any scenario requiring grow-only collections with immutability guarantees + +When and Where It Occurs +------------------------------------------------------------------------------- + +The problem manifests in production systems when: + +* Configuration values are accidentally overwritten, causing unpredictable behavior +* Plugin registrations are removed, breaking dependent functionality +* Cached entries are invalidated prematurely, causing performance issues +* State mutation creates race conditions in concurrent systems +* Debugging reveals unexpected state changes with unclear origins + +Impact and Consequences +------------------------------------------------------------------------------- + +Without accretive data structures: + +* **Correctness Issues**: Accidental state mutation leads to bugs that are + difficult to reproduce and diagnose +* **Concurrency Problems**: Mutable shared state creates race conditions and + synchronization complexity +* **Maintenance Burden**: Developers must manually enforce immutability through + documentation and code review +* **Runtime Failures**: State tampering can cause critical system failures in + production environments +* **Testing Complexity**: Mutable state makes unit tests fragile and dependent + on execution order + +Current Workarounds and Limitations +------------------------------------------------------------------------------- + +Existing approaches include: + +* **Frozen dataclasses**: Provide immutability but prevent any growth; cannot + add new attributes after initialization +* **Manual immutability enforcement**: Requires discipline, documentation, and + code review; error-prone and not enforceable at runtime +* **Copy-on-write patterns**: Add performance overhead and memory consumption; + complexity scales with collection size +* **Read-only wrappers**: Limited to specific collection types; do not support + selective mutability or initialization phases + +These solutions fail to provide the specific combination of: + +* Allowing growth (new entries/attributes) +* Preventing modification of existing entries/attributes +* Supporting flexible initialization patterns +* Maintaining familiar Python APIs +* Enabling selective mutability when needed + +Goals and Objectives +=============================================================================== + +Primary Objectives +------------------------------------------------------------------------------- + +**REQ-OBJ-001 [Critical]: Accretive Behavior** + +Provide data structures that enforce grow-only semantics: new values can be +added, but existing values cannot be modified or removed. + +Success Metrics: + +* 100% prevention of modification attempts on existing entries +* Clear, informative exceptions when immutability is violated +* Zero false positives (legitimate additions incorrectly rejected) + +**REQ-OBJ-002 [Critical]: Familiar APIs** + +Maintain APIs consistent with standard Python types (dict, SimpleNamespace, +type, ModuleType) to minimize learning curve. + +Success Metrics: + +* All standard collection operations supported except mutation +* Initialization patterns match standard library types +* Drop-in replacement possible in most use cases + +**REQ-OBJ-003 [High]: Flexible Mutability** + +Support selective mutability for specific attributes/entries when needed during +initialization or for specific use cases. + +Success Metrics: + +* Configuration options for mutable attribute patterns +* Support for unprotected initialization phases +* Compatibility with standard decorators (dataclasses, etc.) + +Secondary Objectives +------------------------------------------------------------------------------- + +**REQ-OBJ-004 [Medium]: Comprehensive Type Coverage** + +Provide accretive variants for common Python types beyond basic collections. + +Success Metrics: + +* Dictionary types with standard, producer, and validator variants +* Namespace types matching SimpleNamespace functionality +* Class metaclasses supporting dataclasses and standard classes +* Module reclassification utilities + +Functional Requirements +=============================================================================== + +Accretive Dictionary Types +------------------------------------------------------------------------------- + +**REQ-DICT-001 [Critical]: Basic Dictionary** + +Standard accretive dictionary implementation that allows adding new entries but +prevents modifying or removing existing ones. + +Acceptance Criteria: + +* Supports initialization from iterables and keyword arguments +* Implements collections.abc.Mapping protocol +* Allows ``__setitem__`` for new keys only +* Raises ``EntryImmutability`` exception on modification attempts +* Prevents ``__delitem__`` operations on existing keys +* Supports all read operations (get, keys, values, items, etc.) + +**REQ-DICT-002 [High]: Producer Dictionary** + +Dictionary that auto-generates values for missing keys using a factory function, +similar to collections.defaultdict but with accretive behavior. + +Acceptance Criteria: + +* Accepts factory function for generating default values +* Generates value on first access to missing key +* Generated values become immutable after creation +* Behaves identically to Dictionary for existing keys + +**REQ-DICT-003 [Medium]: Validator Dictionary** + +Dictionary that validates entries before addition using a predicate function, +ensuring only valid data can be added. + +Acceptance Criteria: + +* Accepts predicate function for validation +* Calls predicate with (key, value) on each addition attempt +* Raises ``EntryInvalidity`` exception on validation failure +* Allows only valid entries to be added and made immutable + +**REQ-DICT-004 [Medium]: Combined Producer-Validator** + +Dictionary combining auto-generation and validation behaviors. + +Acceptance Criteria: + +* Generated default values must pass validation +* Validation failures raise clear exceptions +* Behaves as expected from both parent classes + +Accretive Namespace Types +------------------------------------------------------------------------------- + +**REQ-NS-001 [Critical]: Basic Namespace** + +Accretive namespace similar to types.SimpleNamespace that allows adding +attributes dynamically but prevents modification or deletion of existing +attributes. + +Acceptance Criteria: + +* Allows dynamic attribute assignment with dot notation +* Prevents modification of existing attributes +* Prevents deletion of existing attributes +* Raises ``AttributeImmutability`` exception on violations +* Supports initialization from iterables and keyword arguments +* Provides readable ``__repr__`` listing all attributes + +Accretive Class Types +------------------------------------------------------------------------------- + +**REQ-CLASS-001 [Critical]: Standard Metaclass** + +Metaclass for creating classes with accretive instances where instance +attributes become immutable after first assignment. + +Acceptance Criteria: + +* Works as a metaclass (``metaclass=Class``) +* Instance attributes become immutable after first assignment +* Supports selective mutability via configuration +* Integrates with classcore class factory system +* Supports dynadoc documentation generation + +**REQ-CLASS-002 [High]: Dataclass Metaclass** + +Metaclass for dataclasses with accretive instances, compatible with the +@dataclass decorator. + +Acceptance Criteria: + +* Compatible with @dataclass decorator +* Frozen instances by default +* Supports kw_only parameters +* Field values immutable after initialization +* Proper dataclass_transform type checking support + +**REQ-CLASS-003 [Medium]: Mutable Dataclass Metaclass** + +Metaclass for dataclasses with selectively mutable instances. + +Acceptance Criteria: + +* Instance attributes can be declared mutable +* Class-level immutability maintained +* Supports standard dataclass features +* Clear documentation of mutability patterns + +Accretive Module Types +------------------------------------------------------------------------------- + +**REQ-MOD-001 [High]: Module Reclassification** + +Utilities to reclassify existing modules as accretive, making module-level +attributes immutable after finalization. + +Acceptance Criteria: + +* ``Module`` class extends types.ModuleType +* Module attributes become immutable after finalization +* ``finalize_module`` utility for reclassification +* Recursive reclassification for package hierarchies +* Integration with dynadoc for documentation + +Error Handling +------------------------------------------------------------------------------- + +**REQ-ERR-001 [Critical]: Exception Hierarchy** + +Clear exception hierarchy for accretive violations with informative error +messages. + +Acceptance Criteria: + +* ``Omnierror`` base class for all package errors +* ``AttributeImmutability`` for attribute violations +* ``EntryImmutability`` for dictionary entry violations +* ``EntryInvalidity`` for validation failures +* Exception messages include attribute/key names and context +* Exceptions inherit from appropriate standard types (TypeError, ValueError) + +Non-Functional Requirements +=============================================================================== + +Compatibility Requirements +------------------------------------------------------------------------------- + +**REQ-COMPAT-001**: Support Python 3.10 and above. + +**REQ-COMPAT-002**: Compatible with static type checkers (mypy, pyright). + +**REQ-COMPAT-003**: Compatible with standard decorators (@dataclass, @property, +etc.). + +**REQ-COMPAT-004**: Works correctly with pickling and unpickling. + +Usability Requirements +------------------------------------------------------------------------------- + +**REQ-USE-001**: API matches standard library conventions where possible. + +**REQ-USE-002**: Error messages clearly identify violation source and suggest +fixes. + +**REQ-USE-003**: Comprehensive documentation with practical examples. + +**REQ-USE-004**: Docstrings for all public APIs generated via dynadoc. + +Reliability Requirements +------------------------------------------------------------------------------- + +**REQ-REL-001**: 100% test coverage for core functionality. + +**REQ-REL-002**: Zero known bugs in immutability enforcement. + +**REQ-REL-003**: Comprehensive test suite covering edge cases. + +Maintainability Requirements +------------------------------------------------------------------------------- + +**REQ-MAINT-001**: Follows project-standard filesystem organization. + +**REQ-MAINT-002**: Uses cascading import hub pattern (``__`` subpackage). + +**REQ-MAINT-003**: Integrates with classcore for consistent behavior. + +**REQ-MAINT-004**: Clear separation between public API and internal implementation. + +Constraints and Assumptions +=============================================================================== + +Technical Constraints +------------------------------------------------------------------------------- + +* **Python Immutability Limitations**: True immutability is impossible in + Python; enforcement is best-effort and can be circumvented by determined users + with intermediate Python knowledge. The package encourages immutability rather + than guarantees it. + +* **Metaclass Limitations**: Classes can only have one metaclass; users cannot + combine accretive metaclasses with other custom metaclasses without multiple + inheritance or creative workarounds. + +* **Performance Overhead**: Attribute assignment interception adds overhead + compared to standard types; acceptable for most use cases but may be + prohibitive for performance-critical inner loops. + +Dependencies +------------------------------------------------------------------------------- + +* **classcore**: Core dependency providing class factory system and behavior + configuration mechanisms. + +* **dynadoc**: Documentation generation from type annotations and fragments. + +* **absence**: Sentinel values for distinguishing absent vs None parameters. + +* **frigid**: Immutable data structures for internal configuration storage. + +Assumptions +------------------------------------------------------------------------------- + +* Users have intermediate to advanced Python knowledge +* Users understand the limitations of Python immutability enforcement +* Users prioritize correctness and safety over maximum performance +* Users accept minimal performance overhead for immutability guarantees +* Standard library types (dict, object, module) will maintain backward + compatibility + +Out of Scope +=============================================================================== + +The following features are explicitly excluded from the current product scope: + +**Deep Immutability** + +The package does not enforce immutability of nested values. If a dictionary +entry is itself mutable (e.g., a list), that object can still be modified. Only +the binding between key and value is immutable. + +**Cryptographic Guarantees** + +The package does not provide cryptographic verification of immutability or +tamper detection. Immutability enforcement is best-effort in Python's dynamic +environment. + +**Multi-Process Synchronization** + +The package does not provide synchronization primitives for multi-process +scenarios. Thread-safety within a single process is supported, but distributed +consistency is out of scope. + +**Migration Tools** + +Automatic migration from standard types to accretive types is not provided. +Users must manually adopt accretive types in their codebases. + +**Performance Optimization Beyond Standard Types** + +While performance overhead should be minimal, optimizations to make accretive +types faster than standard types are not a goal. + +**Alternative Immutability Models** + +Other immutability patterns (copy-on-write, persistent data structures, etc.) +are not provided. The package focuses exclusively on accretive semantics. \ No newline at end of file