From afa0eaa6e915c6779d78ca55df6389d1189bc975 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Nov 2025 01:10:02 +0000 Subject: [PATCH] Documentation: Architecture: Fill out architecture documents. Add comprehensive architecture documentation including: - System overview with layered architecture description - Detailed component responsibilities and data flows - Key architectural patterns and integration points - Product requirements with functional requirements and user stories - Enhanced filesystem documentation with module responsibilities The documentation covers the factory, decorator, behavior, standard, and utility layers, along with class creation and attribute access flows. Also documents extension points, dependencies, and architectural goals. Co-Authored-By: Claude (Sonnet 4.5) --- documentation/architecture/filesystem.rst | 177 +++++++++++++- documentation/architecture/summary.rst | 282 +++++++++++++++++++++- documentation/prd.rst | 264 +++++++++++++++++++- 3 files changed, 710 insertions(+), 13 deletions(-) diff --git a/documentation/architecture/filesystem.rst b/documentation/architecture/filesystem.rst index d3ca1b9..5bb2365 100644 --- a/documentation/architecture/filesystem.rst +++ b/documentation/architecture/filesystem.rst @@ -57,15 +57,138 @@ The main Python package follows the standard ``sources/`` directory pattern: .. code-block:: sources/ - ├── classcore/ # Main Python package - │ ├── __/ # Centralized import hub - │ │ ├── __init__.py # Re-exports core utilities - │ │ ├── imports.py # External library imports - │ │ └── nomina.py # python-classcore-specific naming constants - │ ├── __init__.py # Package entry point - │ ├── py.typed # Type checking marker - │ └── [modules].py # Feature-specific modules - + └── classcore/ # Main Python package + ├── __/ # Centralized import hub + │ ├── __init__.py # Re-exports core utilities + │ ├── imports.py # External library imports + │ ├── nomina.py # Naming constants + │ └── doctab.py # Documentation table fragments + ├── __init__.py # Package entry point + ├── py.typed # Type checking marker + ├── decorators.py # Class decorator utilities + ├── exceptions.py # Package exception classes + ├── factories.py # Metaclass factory functions + ├── nomina.py # Public naming types and utilities + ├── utilities.py # Class manipulation utilities + └── standard/ # Standard behaviors subpackage + ├── __.py # Inherits parent imports + ├── __init__.py # Subpackage entry point + ├── behaviors.py # Immutability and concealment logic + ├── classes.py # Standard metaclasses and base classes + ├── decorators.py # Standard class decorators + ├── dynadoc.py # Documentation configuration + ├── modules.py # Module reclassification utilities + └── nomina.py # Standard-specific naming types + +Module Responsibilities +------------------------------------------------------------------------------- + +Core Package (``sources/classcore/``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``__/__init__.py`` + Re-exports commonly used imports from ``imports.py`` for convenient access + via ``from . import __`` in all package modules. + +``__/imports.py`` + Centralizes all external library imports. Provides abbreviated aliases for + frequently used types and modules (e.g., ``cabc`` for + ``collections.abc``, ``typx`` for ``typing``). + +``__/nomina.py`` + Package-specific naming constants and utilities used internally by the + ``__`` import hub. + +``__/doctab.py`` + Documentation table with reusable fragments for dynadoc interpolation. + +``__init__.py`` + Package entry point. Exports public API, applies standard behaviors to + package module, sets version. + +``decorators.py`` + Class decorator utilities: + + - ``apply_decorators``: Apply decorator sequences with class replacement + handling + - ``decoration_by``: Compose multiple decorators + - ``produce_class_construction_decorator``: Create metaclass ``__new__`` + decorators + - ``produce_class_initialization_decorator``: Create metaclass ``__init__`` + decorators + +``exceptions.py`` + Package exception hierarchy. All exceptions use standard behaviors + (immutability and concealment) themselves. + +``factories.py`` + Metaclass component factories: + + - ``produce_class_constructor``: Generate customizable ``__new__`` with + hooks + - ``produce_class_initializer``: Generate customizable ``__init__`` with + hooks + +``nomina.py`` + Public naming types, type aliases, and protocols used throughout the + package. Defines interfaces for hooks, verifiers, and core functions. + +``utilities.py`` + Class manipulation utilities: + + - ``mangle_name``: Create unique attribute names + - ``getattr0/setattr0/delattr0``: Mangled attribute access + - ``repair_class_reproduction``: Fix closures after class replacement + - ``describe_object``: Generate error message descriptions + +Standard Subpackage (``sources/classcore/standard/``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``__.py`` + Inherits all imports from parent ``__`` via ``from ..__ import *``. + Demonstrates the cascading import pattern for subpackages. + +``__init__.py`` + Subpackage entry point. Exports all standard classes, decorators, and + utilities. Applies standard behaviors to subpackage module. + +``behaviors.py`` + Core implementation of standard behaviors: + + - ``assign_attribute_if_mutable``: Conditional attribute assignment + - ``delete_attribute_if_mutable``: Conditional attribute deletion + - ``survey_visible_attributes``: Filter attributes for ``dir()`` + - Verifier processing for names, regexes, and predicates + +``classes.py`` + Standard metaclasses and base classes: + + - ``Class`` / ``Object``: Standard class with full behaviors + - ``Dataclass`` / ``DataclassObject``: Auto-dataclass with behaviors + - ``Protocol`` / ``ProtocolObject``: Protocol with behaviors + - Mutable variants for each + +``decorators.py`` + Standard class decorators: + + - ``class_with_standard_behaviors``: Apply behaviors to existing class + - ``dataclass_with_standard_behaviors``: Create dataclass with behaviors + - ``protocol_with_standard_behaviors``: Create protocol with behaviors + - ``class_factory``: Generic factory for creating custom metaclasses + +``dynadoc.py`` + Dynadoc configuration for standard behaviors. Provides documentation + fragments that describe behaviors automatically applied to classes. + +``modules.py`` + Module reclassification utilities: + + - ``reclassify_module``: Apply behaviors to single module + - ``finalize_module``: Complete module initialization (used by package) + +``nomina.py`` + Standard-specific naming types and constants. Defines behavior labels + and attribute naming functions. All package modules use the standard ``__`` import pattern as documented in the common architecture guide. @@ -73,6 +196,42 @@ in the common architecture guide. Component Integration =============================================================================== +Import Hub Usage +------------------------------------------------------------------------------- + +All modules access common dependencies through the ``__`` import hub: + +.. code-block:: python + + # In any module at sources/classcore/ + from . import __ + + # Use abbreviated imports + def example( items: __.cabc.Sequence[ str ] ) -> __.typx.Any: + return __.funct.partial( some_function, items ) + +This pattern: + +- Eliminates redundant import statements +- Provides consistent naming across modules +- Centralizes import changes to ``__/imports.py`` +- Reduces module namespace pollution + +Subpackage Extension +------------------------------------------------------------------------------- + +The ``standard/`` subpackage demonstrates the cascading import pattern. +Its ``__.py`` inherits parent imports and can add specialized dependencies: + +.. code-block:: python + + # sources/classcore/standard/__.py + from ..__ import * # Inherit all parent imports + from ..exceptions import * # Add package exceptions + +Modules in ``standard/`` use the same import pattern but gain access to both +parent and subpackage-specific imports. + Architecture Evolution =============================================================================== diff --git a/documentation/architecture/summary.rst b/documentation/architecture/summary.rst index bab368a..9f84935 100644 --- a/documentation/architecture/summary.rst +++ b/documentation/architecture/summary.rst @@ -21,4 +21,284 @@ System Overview ******************************************************************************* -.. todo:: Describe the high-level system architecture, major components, and their relationships. \ No newline at end of file +Classcore is a foundational library for creating classes with customized +behaviors, particularly immutability and concealment. The library operates at +the metaclass level to provide composable, inheritable behaviors while +maintaining compatibility with standard Python features like dataclasses and +protocols. + +Architectural Goals +=============================================================================== + +**Composability** + Enable incremental addition of class behaviors through decorators, + metaclasses, and inheritance without conflicts or unexpected interactions. + +**Transparency** + Work seamlessly with existing Python features (dataclasses, protocols, + ABCs) and tools (type checkers, IDEs). + +**Customizability** + Provide extension points at every layer for users to adapt behaviors to + specific needs through verifiers, hooks, and core function replacements. + +**Performance** + Minimize runtime overhead through strategic caching and lazy evaluation + while centralizing import costs at package initialization. + +High-Level Architecture +=============================================================================== + +The system follows a layered architecture with clear separation of concerns: + +Core Factory Layer +------------------------------------------------------------------------------- + +Location: ``sources/classcore/factories.py`` + +Produces metaclass components with customizable hooks: + +- ``produce_class_constructor``: Creates ``__new__`` implementations with + preprocessor and postprocessor hooks +- ``produce_class_initializer``: Creates ``__init__`` implementations with + completer hooks + +These factories enable the construction of metaclasses that can intercept and +augment class creation at multiple lifecycle points. + +Decorator Layer +------------------------------------------------------------------------------- + +Location: ``sources/classcore/decorators.py`` + +Manages class decoration and replacement: + +- ``apply_decorators``: Applies decorator sequences while handling class + replacements +- ``decoration_by``: Composes multiple decorators with preparation hooks +- ``produce_class_construction_decorator``: Wraps constructor logic into + metaclass ``__new__`` +- ``produce_class_initialization_decorator``: Wraps initializer logic into + metaclass ``__init__`` + +Critical feature: Repairs class closures when decorators replace classes +(e.g., ``dataclass(slots=True)``), ensuring ``super()`` continues to function +correctly. + +Behavior Layer +------------------------------------------------------------------------------- + +Location: ``sources/classcore/standard/behaviors.py`` + +Implements immutability and concealment enforcement: + +- Attribute assignment control with selective mutability +- Attribute deletion control +- Attribute visibility filtering for ``dir()`` +- Verifier system supporting names, regexes, and predicates + +The verifier system allows fine-grained control: specify mutable attributes by +name, pattern, or custom predicate functions. + +Standard Layer +------------------------------------------------------------------------------- + +Location: ``sources/classcore/standard/`` + +Pre-configured implementations for common use cases: + +**Base Classes:** +- ``Object``: Standard class with immutability and concealment +- ``DataclassObject``: Automatic dataclass conversion with standard behaviors +- ``ProtocolObject``: Protocol class with immutability and concealment +- Variants for selective mutability (``ObjectMutable``, etc.) + +**Metaclasses:** +- ``Class``: Metaclass for standard classes +- ``Dataclass``: Metaclass that auto-applies dataclass decorator +- ``Protocol``: Metaclass for protocol classes +- Mutable variants of each + +**Decorators:** +- ``class_with_standard_behaviors``: Add behaviors to existing classes +- ``dataclass_with_standard_behaviors``: Dataclass creation with behaviors +- ``protocol_with_standard_behaviors``: Protocol creation with behaviors + +**Module Utilities:** +- ``reclassify_module``: Apply immutability and concealment to module objects +- ``finalize_module``: Complete module initialization with standard behaviors + +Utility Layer +------------------------------------------------------------------------------- + +Location: ``sources/classcore/utilities.py`` + +Provides essential operations for metaclass machinery: + +- ``mangle_name``: Creates unique attribute names using SHA-256 hashing to + avoid inheritance collisions +- ``getattr0/setattr0/delattr0``: Access mangled attributes while respecting + ``__slots__`` +- ``repair_class_reproduction``: Fixes closure cells when decorators replace + classes (CPython/PyPy-specific) +- ``describe_object``: Generates human-readable object descriptions for error + messages + +Data Flow +=============================================================================== + +Class Creation Flow +------------------------------------------------------------------------------- + +1. User defines class with standard metaclass or inherits from standard base +2. Metaclass ``__new__`` invoked via ``produce_class_constructor`` +3. Preprocessors modify bases, namespace, arguments, decorators +4. Superclass ``__new__`` creates initial class object +5. Progress flag prevents recursive processing +6. Postprocessors execute (e.g., adding behavior configurations) +7. Decorators applied via ``apply_decorators`` +8. If decorator replaces class, closures repaired +9. Metaclass ``__init__`` invoked via ``produce_class_initializer`` +10. Completers execute (e.g., freezing behaviors) +11. Progress flag cleared +12. Fully initialized class returned + +Attribute Access Flow (Instances) +------------------------------------------------------------------------------- + +**Assignment (``obj.attr = value``):** +1. ``__setattr__`` intercepted by assigner core function +2. Check for immutability behavior flag +3. If immutable, verify against mutables (names, regexes, predicates) +4. If allowed, delegate to ligation (super or core override) +5. If denied, raise ``AttributeImmutability`` error + +**Visibility (``dir(obj)``):** +1. ``__dir__`` intercepted by surveyor core function +2. Collect all attributes from object and class hierarchy +3. Check visibility verifiers (names, regexes, predicates) +4. Filter attributes based on verifiers +5. Return filtered set + +Key Architectural Patterns +=============================================================================== + +Factory Pattern +------------------------------------------------------------------------------- + +Metaclass components are produced by factory functions rather than fixed +inheritance hierarchies. This enables composition of behaviors and runtime +customization of class creation logic. + +Decorator Composition +------------------------------------------------------------------------------- + +Multiple decorators can be applied in sequence, with automatic handling of +class replacements. The ``decoration_by`` function enables declarative +composition of decorator stacks. + +Hook-Based Extension +------------------------------------------------------------------------------- + +Every critical point in the class lifecycle offers hooks: + +- Preprocessors: Modify class construction inputs +- Postprocessors: Augment constructed classes +- Completers: Finalize initialized classes +- Preparers: Adjust decorator lists before application + +Verifier Pattern +------------------------------------------------------------------------------- + +Behavior exclusions (mutability, visibility) use a uniform verifier interface: + +- Literal ``'*'``: Allow all +- Sequence of strings: Exact name matches +- Sequence of ``re.Pattern``: Regex matches +- Sequence of callables: Predicate functions + +This provides flexible, user-customizable behavior rules. + +Core Function Replacement +------------------------------------------------------------------------------- + +Critical behaviors (assignment, deletion, visibility) can be replaced entirely +by providing alternative "core" functions. This enables deep customization +without subclassing. + +Integration Points +=============================================================================== + +Dataclasses +------------------------------------------------------------------------------- + +Standard metaclasses automatically apply ``dataclasses.dataclass`` during +class construction, with configurability for ``frozen``, ``slots``, etc. The +decorator application system ensures proper handling of the class replacement +that occurs with ``slots=True``. + +Protocols +------------------------------------------------------------------------------- + +Standard protocol classes combine ``typing.Protocol`` with immutability and +concealment. Special handling for ABC-related mutable attributes +(``_abc_cache``, ``_abc_registry``, etc.) ensures protocol functionality. + +Type Checkers +------------------------------------------------------------------------------- + +Metaclasses use ``@dataclass_transform`` decorator to signal dataclass +behavior to type checkers. This enables proper type inference and checking +for classes produced by standard metaclasses. + +Module Objects +------------------------------------------------------------------------------- + +Module reclassification applies class-level behaviors to module objects, +enabling immutable, concealed module namespaces for API control. + +Dependencies +=============================================================================== + +External Dependencies +------------------------------------------------------------------------------- + +The library depends on standard library modules only: + +- ``dataclasses``: Automatic dataclass generation +- ``functools``: Decorator utilities and partials +- ``hashlib``: Attribute name mangling (SHA-256) +- ``inspect``: Class and function introspection +- ``platform``: Python implementation detection for platform-specific repairs +- ``re``: Regular expression support for verifiers +- ``typing``: Type hints and protocol support +- ``collections.abc``: Abstract base classes + +Internal Dependencies +------------------------------------------------------------------------------- + +- ``dynadoc``: Documentation generation with fragment interpolation +- ``frigid``: Immutable data structures for internal use +- ``falsifier``: Base classes for falsey objects + +Extension Points +=============================================================================== + +Users can extend the library at multiple levels: + +**Decorator Level** + Create custom class decorators and compose with ``decoration_by``. + +**Metaclass Level** + Build custom metaclasses using factory functions with custom hooks. + +**Behavior Level** + Replace core functions for assignment, deletion, visibility, or error + provision. + +**Verifier Level** + Implement custom predicate functions for mutability/visibility rules. + +**Hook Level** + Provide preprocessors, postprocessors, completers, or preparers for + lifecycle customization. \ No newline at end of file diff --git a/documentation/prd.rst b/documentation/prd.rst index 85bf640..e515dc9 100644 --- a/documentation/prd.rst +++ b/documentation/prd.rst @@ -21,7 +21,265 @@ Product Requirements Document ******************************************************************************* -.. todo:: Define product requirements, user stories, and acceptance criteria. +Product Vision +=============================================================================== -For PRD format and guidance, see the `requirements documentation guide -`_. \ No newline at end of file +Classcore provides foundational class factories and decorators for Python +developers who need to create classes with immutable and concealed attributes. +The library enables safer, more maintainable code by making immutability and +API control first-class features that integrate seamlessly with standard Python +constructs like dataclasses and protocols. + +Target Audience +=============================================================================== + +Primary Users +------------------------------------------------------------------------------- + +**Library Authors** + Developers creating reusable packages who want to provide stable APIs with + controlled modification and clear public interfaces. + +**Application Developers** + Engineers building systems that benefit from immutable data structures and + controlled state management (configuration objects, DTOs, domain models). + +**Framework Developers** + Authors of frameworks and plugin systems who need controlled extension + points and stable interfaces. + +Secondary Users +------------------------------------------------------------------------------- + +**Data Scientists** + Practitioners working with immutable data pipelines and reproducible + analysis workflows. + +**API Designers** + Architects defining service interfaces and contracts with strict stability + guarantees. + +Core Requirements +=============================================================================== + +FR-1: Attribute Immutability +------------------------------------------------------------------------------- + +**Requirement** + Provide mechanisms to make class and instance attributes immutable after + initialization. + +**Rationale** + Immutability prevents accidental state modification, reduces bugs, and + enables safer concurrent access. + +**Acceptance Criteria** + +- Classes produced by standard metaclasses have immutable attributes +- Instances of standard classes have immutable attributes +- Immutability applies after ``__init__`` and ``__post_init__`` complete +- Attempting to modify immutable attributes raises ``AttributeImmutability`` +- Attempting to delete immutable attributes raises ``AttributeImmutability`` + +FR-2: Selective Mutability +------------------------------------------------------------------------------- + +**Requirement** + Allow users to specify exceptions to immutability rules using names, + regexes, or custom predicates. + +**Rationale** + Some attributes (cache values, internal state) need mutability while + maintaining immutability for public API attributes. + +**Acceptance Criteria** + +- Support ``class_mutables`` argument for class-level selective mutability +- Support ``instances_mutables`` argument for instance-level selective + mutability +- Accept attribute names as strings for exact matches +- Accept compiled regex patterns for pattern-based matching +- Accept predicate functions for custom matching logic +- Support literal ``'*'`` to disable immutability entirely +- Mutability verifiers are inherited and composable + +FR-3: Attribute Concealment +------------------------------------------------------------------------------- + +**Requirement** + Provide mechanisms to conceal non-public attributes from ``dir()`` output. + +**Rationale** + Reduces API noise, makes documentation cleaner, and clearly communicates + public interfaces. + +**Acceptance Criteria** + +- By default, only public attributes (not starting with ``_``) visible in + ``dir()`` +- Non-public attributes remain accessible but concealed from introspection +- Concealment applies to both classes and instances +- Users can customize visibility via ``class_visibles`` and + ``instances_visibles`` +- Visibility verifiers support names, regexes, and predicates +- Literal ``'*'`` provides full visibility (Python default) + +FR-4: Dataclass Integration +------------------------------------------------------------------------------- + +**Requirement** + Automatically convert classes to dataclasses while applying immutability and + concealment. + +**Rationale** + Dataclasses are widely used for data containers. Integration should be + seamless and preserve all dataclass functionality. + +**Acceptance Criteria** + +- ``Dataclass`` metaclass auto-applies ``@dataclass`` decorator +- ``DataclassObject`` base class produces dataclass with standard behaviors +- ``dataclass_with_standard_behaviors`` decorator creates dataclass with + behaviors +- ``__post_init__`` can modify attributes before immutability enforced +- Compatible with ``dataclass`` arguments (``frozen``, ``slots``, ``kw_only``, + etc.) +- Proper handling of class replacement when ``slots=True`` +- Type checkers recognize classes as dataclasses via ``@dataclass_transform`` + +FR-5: Protocol Support +------------------------------------------------------------------------------- + +**Requirement** + Provide protocol classes with immutability and concealment that work with + structural subtyping. + +**Rationale** + Protocols enable structural typing. Immutable protocols provide type-safe + interfaces with guaranteed stability. + +**Acceptance Criteria** + +- ``Protocol`` metaclass combines ``typing.Protocol`` with standard behaviors +- ``ProtocolObject`` base class for protocol definitions +- ``protocol_with_standard_behaviors`` decorator for existing protocols +- Protocol functionality preserved (structural subtyping, runtime checks) +- ABC-related mutable attributes (``_abc_cache``, ``_abc_registry``) allowed + by default +- Immutability and concealment inherited by protocol implementations + +FR-6: Module Reclassification +------------------------------------------------------------------------------- + +**Requirement** + Apply immutability and concealment to module objects to protect module + namespaces. + +**Rationale** + Module attributes can be accidentally modified. Reclassification provides + package-level API control. + +**Acceptance Criteria** + +- ``reclassify_module`` function applies behaviors to single module +- ``finalize_module`` applies behaviors and dynadoc configuration +- Support for recursive application to submodules +- Module attributes become immutable after reclassification +- Non-public module attributes concealed from ``dir()`` +- Public module API clearly defined through visibility + +FR-7: Extensibility +------------------------------------------------------------------------------- + +**Requirement** + Provide hooks and factory functions for users to create custom behaviors and + metaclasses. + +**Rationale** + Different use cases require different behaviors. Core machinery should be + reusable for custom implementations. + +**Acceptance Criteria** + +- Factory functions for creating custom metaclasses +- Hook system for class construction (preprocessors, postprocessors) +- Hook system for class initialization (completers) +- Hook system for decoration (preparers) +- Core function replacement (assigner, deleter, surveyor) +- Custom error class provider support +- Composition of decorators via ``decoration_by`` + +FR-8: Type Checker Compatibility +------------------------------------------------------------------------------- + +**Requirement** + Ensure classes produced by classcore are fully compatible with static type + checkers. + +**Rationale** + Type checking is essential for modern Python development. Library must not + interfere with type inference. + +**Acceptance Criteria** + +- All public APIs have complete type annotations +- Metaclasses use ``@dataclass_transform`` for dataclass type checking +- Generic type variables properly constrained +- ``py.typed`` marker included in package +- Pyright strict mode compliance +- No type checker warnings for standard usage patterns + +FR-9: Python Implementation Compatibility +------------------------------------------------------------------------------- + +**Requirement** + Support multiple Python implementations with graceful degradation for + implementation-specific features. + +**Rationale** + Users may deploy on CPython, PyPy, or other implementations. Core + functionality should work everywhere. + +**Acceptance Criteria** + +- Core functionality works on CPython 3.10+ +- Core functionality works on PyPy 3.10+ +- Platform-specific optimizations (closure repair) detected and applied +- No ``exec``, ``eval``, or ``ctypes`` usage +- Rely only on documented Python data model +- Comprehensive test coverage across implementations + +Non-Functional Requirements +=============================================================================== + +Performance +------------------------------------------------------------------------------- + +- Metaclass overhead should be negligible for typical use cases +- Import costs centralized to package initialization +- Attribute access overhead minimal (single method call) +- No unnecessary object allocations in hot paths + +Compatibility +------------------------------------------------------------------------------- + +- Support Python 3.10+ on CPython +- Support Python 3.10+ on PyPy +- Compatible with major type checkers (Pyright, mypy) +- No breaking changes within major version + +Maintainability +------------------------------------------------------------------------------- + +- Comprehensive test coverage (>95%) +- Clear documentation for all public APIs +- Examples for common use cases +- Architecture documentation for contributors + +Usability +------------------------------------------------------------------------------- + +- Clear error messages with actionable information +- Consistent API across classes, decorators, and metaclasses +- Minimal boilerplate for common cases +- Type hints for IDE autocompletion \ No newline at end of file