From c27333a4b0fdb177820ef93d9a98efa4515d30b0 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 03:27:12 +0000 Subject: [PATCH 1/2] docs: populate openspec project.md Populates `documentation/architecture/openspec/project.md` with project details, tech stack, and conventions. References architectural documentation as requested. --- .../architecture/openspec/project.md | 51 +++++++++++++++---- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/documentation/architecture/openspec/project.md b/documentation/architecture/openspec/project.md index 3da5119..bca16a9 100644 --- a/documentation/architecture/openspec/project.md +++ b/documentation/architecture/openspec/project.md @@ -1,31 +1,62 @@ # Project Context ## Purpose -[Describe your project's purpose and goals] +The `frigid` project provides a Python library for **immutable data structures** - collections and objects which cannot be modified after creation. It aims to offer drop-in replacements for mutable built-in types (like `dict` and `SimpleNamespace`) and mechanisms to make arbitrary classes immutable, enhancing safety and predictability in Python programs while maintaining compatibility with standard Python idioms. ## Tech Stack -- [List your primary technologies] -- [e.g., TypeScript, React, Node.js] +- **Language**: Python >= 3.10 +- **Build System**: Hatch +- **Testing**: Pytest, Coverage +- **Linting & Formatting**: Ruff, Isort +- **Type Checking**: Pyright +- **Documentation**: Sphinx (with Dynadoc) +- **Changelog**: Towncrier ## Project Conventions ### Code Style -[Describe your code style preferences, formatting rules, and naming conventions] +- **Linter/Formatter**: Strict adherence to `Ruff` configuration (line length 79). +- **Imports**: Organized by `isort` and centralized via the `__` subpackage. +- **Typing**: Static typing checked by `Pyright`. +- **Docstrings**: Uses `dynadoc` fragments for consistency. +- **Naming**: Follows standard Python conventions, with internal implementations often suffixed or using specific patterns (e.g., `_data_`). ### Architecture Patterns -[Document your architectural decisions and patterns] +For detailed architectural documentation, see: +- [System Overview](../summary.rst) +- [Filesystem Organization](../filesystem.rst) + +**Key Patterns:** +- **Centralized Imports**: Uses a `sources/frigid/__` subpackage as a central hub for internal and external dependencies. +- **Wrapper Pattern**: Public classes often wrap internal implementations (e.g., `Dictionary` wraps `ImmutableDictionary`). +- **Delegation**: Delegates core class creation and protection logic to the `classcore` library. +- **Initialization Window**: Allows mutation during `__init__` before enforcing immutability. ### Testing Strategy -[Explain your testing approach and requirements] +See [Test Plans](../testplans/index.rst). + +- **Structure**: Tests mirror the source package structure. +- **Coverage**: Targets >95% line coverage and 100% public API coverage. +- **Doctests**: Examples in documentation are tested. +- **Markers**: Uses `slow` marker for long-running tests. ### Git Workflow -[Describe your branching strategy and commit conventions] +- **Pre-commit**: Uses pre-commit hooks for validation. +- **Pull Requests**: Changes are submitted via PRs. +- **OpenSpec**: Follows the OpenSpec workflow for spec-driven development (see `AGENTS.md` in this directory). ## Domain Context -[Add domain-specific knowledge that AI assistants need to understand] +- **Immutability**: The core domain is preventing state modification after initialization. +- **Practical Immutability**: Acknowledges that Python allows circumvention (e.g., via `object.__setattr__`), so the goal is safety against accidental modification, not absolute security. +- **Metaprogramming**: Heavy use of metaclasses and decorators to enforce behaviors. ## Important Constraints -[List any technical, business, or regulatory constraints] +- **Python Version**: Must support Python 3.10 and newer. +- **Performance**: Wrappers should introduce minimal overhead. +- **Compatibility**: Must work with `dataclasses` and other standard Python features. ## External Dependencies -[Document key external services, APIs, or systems] +- **absence**: Sentinel values. +- **classcore**: Class factories and attribute protection. +- **dynadoc**: Dynamic documentation generation. +- **typing-extensions**: For compatibility. From 37be6e1d46b57094f0402b3662cfa9570857d456 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 04:15:51 +0000 Subject: [PATCH 2/2] docs: use generic project name in openspec project.md Replaces hardcoded project name with "This project" in the Purpose section to improve maintainability. --- documentation/architecture/openspec/project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/architecture/openspec/project.md b/documentation/architecture/openspec/project.md index bca16a9..3b47b80 100644 --- a/documentation/architecture/openspec/project.md +++ b/documentation/architecture/openspec/project.md @@ -1,7 +1,7 @@ # Project Context ## Purpose -The `frigid` project provides a Python library for **immutable data structures** - collections and objects which cannot be modified after creation. It aims to offer drop-in replacements for mutable built-in types (like `dict` and `SimpleNamespace`) and mechanisms to make arbitrary classes immutable, enhancing safety and predictability in Python programs while maintaining compatibility with standard Python idioms. +This project provides a Python library for **immutable data structures** - collections and objects which cannot be modified after creation. It aims to offer drop-in replacements for mutable built-in types (like `dict` and `SimpleNamespace`) and mechanisms to make arbitrary classes immutable, enhancing safety and predictability in Python programs while maintaining compatibility with standard Python idioms. ## Tech Stack - **Language**: Python >= 3.10