From fcfe8be3733c60516975bb62dc079e39f7ad4c57 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 7 Dec 2025 01:54:41 +0000 Subject: [PATCH 1/2] docs: update openspec/project.md with project details and conventions - Filled out `documentation/architecture/openspec/project.md` with details about the `absence` project. - Documented purpose, tech stack (Python, Hatch, Ruff, etc.), and project conventions. - Referenced `documentation/architecture/filesystem.rst` and `summary.rst` as requested. --- .../architecture/openspec/project.md | 48 +++++++++++++++---- 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/documentation/architecture/openspec/project.md b/documentation/architecture/openspec/project.md index 3da5119..b1193d6 100644 --- a/documentation/architecture/openspec/project.md +++ b/documentation/architecture/openspec/project.md @@ -1,31 +1,59 @@ # Project Context ## Purpose -[Describe your project's purpose and goals] +The `absence` project provides a falsey sentinel singleton and factory for representing absent values in contexts where `None` or `False` might be valid values. It offers a type-safe, immutable alternative to `None` for distinguishing between "empty" and "missing" states. ## Tech Stack -- [List your primary technologies] -- [e.g., TypeScript, React, Node.js] +- **Language**: Python 3.10+ +- **Build System**: Hatch +- **Linting & Formatting**: Ruff, isort, emcd-vibe-linter +- **Type Checking**: Pyright +- **Testing**: pytest, coverage +- **Documentation**: Sphinx +- **Release Management**: Towncrier ## Project Conventions ### Code Style -[Describe your code style preferences, formatting rules, and naming conventions] +- **Formatting**: 4-space indentation, 79-character line length (enforced by Ruff/isort). +- **Import Style**: Centralized external imports in `__/imports.py` and package re-exports in `__/`. Modules import from `.` or `.__` (e.g., `from . import __`). +- **Linter Rules**: Strict adherence to Ruff rulesets (A, B, C, E, F, PL, etc.) as defined in `pyproject.toml`. +- **References**: + - `documentation/architecture/filesystem.rst` (Source Code Organization, Component Integration) ### Architecture Patterns -[Document your architectural decisions and patterns] +- **Module Structure**: Flat module structure (`objects`, `installers`, `exceptions`, `__`) to maintain simplicity and avoid circular dependencies. +- **Patterns**: + - **Singleton Pattern**: Used for the global `absent` sentinel. + - **Factory Pattern**: `AbsenceFactory` for creating custom sentinels. + - **Inheritance**: Inherits falsey behavior from `falsifier.Falsifier`. +- **References**: + - `documentation/architecture/summary.rst` (System Overview, Key Architectural Patterns) + - `documentation/architecture/filesystem.rst` (Dependency Graph) ### Testing Strategy -[Explain your testing approach and requirements] +- **Framework**: `pytest` with `coverage`. +- **Structure**: Tests mirror source structure in `tests/` directory. +- **Naming**: Test files `test_*.py`. Test functions use numbered prefixes (e.g., `test_100_exceptions`, `test_201_absent_singleton_identity`) for systematic coverage. +- **References**: + - `documentation/architecture/filesystem.rst` (Testing Integration) ### Git Workflow -[Describe your branching strategy and commit conventions] +- **Branching**: Standard feature branching. +- **Commits**: Conventional commits suggested (Towncrier is used for changelog generation). +- **Updates**: Project structure updated via Copier. ## Domain Context -[Add domain-specific knowledge that AI assistants need to understand] +- **Absence vs None**: The core domain concept is the distinction between `None` (a specific value often meaning "null") and `absent` (meaning "no value provided"). +- **Falsiness**: The sentinel is "falsey" (evaluates to False in boolean contexts) to play nicely with Python control flow, but unique to allow distinguishing from other falsey values (0, False, empty list). ## Important Constraints -[List any technical, business, or regulatory constraints] +- **Minimal Dependencies**: Keep dependency footprint small (`classcore`, `dynadoc`, `falsifier`, `typing-extensions`). +- **Pickling**: The `absent` sentinel and factory instances explicitly prevent pickling to ensure process-wide uniqueness. +- **Backward Compatibility**: Public API at `absence.*` must remain stable. ## External Dependencies -[Document key external services, APIs, or systems] +- `classcore`: Attribute visibility and object utilities. +- `dynadoc`: Documentation tools. +- `falsifier`: Base class for falsey objects. +- `typing-extensions`: Type hinting support. From 25d3af58d37dad6f603a20f27463f0d22bf0c266 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:01:38 +0000 Subject: [PATCH 2/2] docs: address review comments on openspec/project.md - Use "This project" instead of "The `absence` project". - Remove specific Ruff rulesets list. - Remove mentions of Conventional Commits and standard feature branching. - Clarify pickling constraint. --- documentation/architecture/openspec/project.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/documentation/architecture/openspec/project.md b/documentation/architecture/openspec/project.md index b1193d6..5a692a3 100644 --- a/documentation/architecture/openspec/project.md +++ b/documentation/architecture/openspec/project.md @@ -1,7 +1,7 @@ # Project Context ## Purpose -The `absence` project provides a falsey sentinel singleton and factory for representing absent values in contexts where `None` or `False` might be valid values. It offers a type-safe, immutable alternative to `None` for distinguishing between "empty" and "missing" states. +This project provides a falsey sentinel singleton and factory for representing absent values in contexts where `None` or `False` might be valid values. It offers a type-safe, immutable alternative to `None` for distinguishing between "empty" and "missing" states. ## Tech Stack - **Language**: Python 3.10+ @@ -17,7 +17,7 @@ The `absence` project provides a falsey sentinel singleton and factory for repre ### Code Style - **Formatting**: 4-space indentation, 79-character line length (enforced by Ruff/isort). - **Import Style**: Centralized external imports in `__/imports.py` and package re-exports in `__/`. Modules import from `.` or `.__` (e.g., `from . import __`). -- **Linter Rules**: Strict adherence to Ruff rulesets (A, B, C, E, F, PL, etc.) as defined in `pyproject.toml`. +- **Linter Rules**: Strict adherence to Ruff rulesets as defined in `pyproject.toml`. - **References**: - `documentation/architecture/filesystem.rst` (Source Code Organization, Component Integration) @@ -39,8 +39,6 @@ The `absence` project provides a falsey sentinel singleton and factory for repre - `documentation/architecture/filesystem.rst` (Testing Integration) ### Git Workflow -- **Branching**: Standard feature branching. -- **Commits**: Conventional commits suggested (Towncrier is used for changelog generation). - **Updates**: Project structure updated via Copier. ## Domain Context @@ -49,7 +47,7 @@ The `absence` project provides a falsey sentinel singleton and factory for repre ## Important Constraints - **Minimal Dependencies**: Keep dependency footprint small (`classcore`, `dynadoc`, `falsifier`, `typing-extensions`). -- **Pickling**: The `absent` sentinel and factory instances explicitly prevent pickling to ensure process-wide uniqueness. +- **Pickling**: The `absent` sentinel and factory instances do not support pickling. - **Backward Compatibility**: Public API at `absence.*` must remain stable. ## External Dependencies