Skip to content

Update openspec/project.md with project details #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emcd merged 2 commits into from
Dec 10, 2025
Merged

Update openspec/project.md with project details #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0563f0c
Update openspec/project.md with project details
google-labs-jules[bot] Dec 7, 2025
dbcf251
Update openspec/project.md based on feedback
google-labs-jules[bot] Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 41 additions & 10 deletions documentation/architecture/openspec/project.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,62 @@
# Project Context

## Purpose
[Describe your project's purpose and goals]
This package provides foundational class factories and decorators for providing classes with attribute immutability, concealment, and other custom behaviors. It aims to make Python programs safer by encouraging immutability and controlled attribute access, while integrating seamlessly with standard Python features like dataclasses and protocols.

## Tech Stack
- [List your primary technologies]
- [e.g., TypeScript, React, Node.js]
- **Languages**: Python 3.10+
- **Build System**: Hatch
- **Package Management**: uv (recommended installation), pip
- **Testing**: pytest, coverage
- **Linting/Formatting**: ruff, isort, pyright, vulture
- **Documentation**: Sphinx, dynadoc
- **Release**: towncrier

## Project Conventions

### Code Style
[Describe your code style preferences, formatting rules, and naming conventions]
- **Line Length**: 79 characters.
- **Imports**: Sorted by `isort` with specific configuration (see `pyproject.toml`).
- **Linting**: Enforced by `ruff` and `pyright`.
- **Typing**: Strict type checking with `pyright`.
- **Import Hub Pattern**: Centralized import management via `sources/classcore/__/`.

### Architecture Patterns
[Document your architectural decisions and patterns]
- **Metaclass & Decorator Factories**: Use of factory functions to produce metaclass components and decorators.
- **Composable Behaviors**: Behaviors are applied via composable decorators and metaclasses.
- **Verifier Pattern**: Use of verifiers (names, regexes, predicates) for behavior configuration.
- **Core Function Replacement**: Dependency injection for core behaviors.
- **Module Reclassification**: Applying class behaviors to modules.
- See [System Overview](../summary.rst) for a comprehensive architectural summary.

### Filesystem Organization
- The project follows a strict filesystem organization pattern.
- See [Filesystem Organization](../filesystem.rst) for detailed conventions.
- **Source**: `sources/classcore/`
- **Tests**: `tests/`
- **Docs**: `documentation/`
- **Dev**: `.auxiliary/`

### Testing Strategy
[Explain your testing approach and requirements]
- **Runner**: `pytest`
- **Coverage**: Strict coverage requirements enforced.
- **Structure**: Tests located in `tests/`, files named `test_*.py`.
- **Naming**: Test functions named `test_[0-9][0-9][0-9]_*`.

### Git Workflow
[Describe your branching strategy and commit conventions]
- **Changelog**: Managed by `towncrier` with fragments in `.auxiliary/data/towncrier`.
- **Commit Messages**: Should align with `towncrier` categories (enhance, notify, remove, repair).
- **Versioning**: Managed by Hatch.

## Domain Context
[Add domain-specific knowledge that AI assistants need to understand]
- **Immutability in Python**: Python does not support true immutability. This library provides "advisory" immutability that can be circumvented but prevents accidental modification.
- **Metaprogramming**: Heavy use of metaclasses (`__new__`, `__init__`) and decorators.
- **Mangled Names**: Use of SHA-256 for name mangling to avoid collisions.

## Important Constraints
[List any technical, business, or regulatory constraints]
- **Python Version Compatibility**: Must support Python 3.10 through 3.14 (and PyPy).
- **Performance**: Runtime overhead must be minimized; import costs centralized.

## External Dependencies
[Document key external services, APIs, or systems]
- **Standard Library**: `dataclasses`, `typing`, `functools`, `inspect`, etc.
- **Runtime**: `dynadoc`, `typing-extensions`.