diff --git a/documentation/architecture/openspec/specs/falsifier/spec.md b/documentation/architecture/openspec/specs/falsifier/spec.md new file mode 100644 index 0000000..30dcdd0 --- /dev/null +++ b/documentation/architecture/openspec/specs/falsifier/spec.md @@ -0,0 +1,73 @@ +# Falsifier + +## Purpose +The library provides a minimal, focused foundation for creating falsey objects in Python that maintain distinct identities. It serves developers who need sentinel values, absence indicators, or custom falsey types where `None` or `False` may be semantically meaningful values. + +## Requirements + +### Requirement: Boolean Evaluation +The `Falsifier` class SHALL implement `__bool__` to return `False`. + +Priority: Critical + +#### Scenario: Boolean context +- **WHEN** a `Falsifier` instance is used in a boolean context +- **THEN** it evaluates to `False` + +### Requirement: Identity-Based Hashing +The `Falsifier` class SHALL implement `__hash__` using object identity (`id(self)`). + +Priority: High + +#### Scenario: Hashing +- **WHEN** `hash()` is called on a `Falsifier` instance +- **THEN** it returns the integer identity of the object + +### Requirement: String Representations +The `Falsifier` class SHALL provide distinct string representations. + +Priority: Medium + +#### Scenario: String conversion +- **WHEN** `str()` is called on a `Falsifier` instance +- **THEN** it returns `'False_'` + +#### Scenario: Representation +- **WHEN** `repr()` is called on a `Falsifier` instance +- **THEN** it returns the fully qualified class name with empty call syntax + +### Requirement: Equality Comparison +The `Falsifier` class SHALL implement identity-based equality comparison. + +Priority: Critical + +#### Scenario: Identity equality +- **WHEN** a `Falsifier` instance is compared to itself using `==` +- **THEN** it returns `True` + +#### Scenario: Distinct object inequality +- **WHEN** a `Falsifier` instance is compared to a different instance using `==` +- **THEN** it returns `False` + +#### Scenario: Inequality operator +- **WHEN** a `Falsifier` instance is compared to a different instance using `!=` +- **THEN** it returns `True` + +### Requirement: Ordered Comparison Rejection +The `Falsifier` class SHALL implement `__lt__`, `__le__`, `__gt__`, and `__ge__` to return `NotImplemented`. + +Priority: Low + +#### Scenario: Less than comparison +- **WHEN** a `Falsifier` instance is compared using `<` +- **THEN** it raises `TypeError` (assuming other operand returns `NotImplemented`) + +### Requirement: Subclass Compatibility +The `Falsifier` class SHALL support subclassing without requiring special metaclass machinery. + +Priority: Medium + +#### Scenario: Creating a subclass +- **WHEN** a class inherits from `Falsifier` +- **THEN** instances of the subclass evaluate to `False` +- **AND** instances of the subclass maintain distinct identity diff --git a/documentation/prd.rst b/documentation/prd.rst deleted file mode 100644 index 3dfa715..0000000 --- a/documentation/prd.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. 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. | - | | - +--------------------------------------------------------------------------+ - - -******************************************************************************* -Product Requirements Document -******************************************************************************* - -Vision -=============================================================================== - -The ``falsifier`` library provides a minimal, focused foundation for creating -falsey objects in Python that maintain distinct identities. It serves -developers who need sentinel values, absence indicators, or custom falsey -types where ``None`` or ``False`` may be semantically meaningful values. - -Target Audience -=============================================================================== - -* **Library developers** creating packages that need custom sentinel values or - absence indicators with falsey semantics -* **Application developers** implementing domain-specific falsey types for - state machines, validators, or data processing pipelines -* **Framework authors** building systems requiring distinct falsey markers - -Core Capabilities -=============================================================================== - -The library provides a single ``Falsifier`` class that: - -* Evaluates to ``False`` in boolean contexts while maintaining distinct object - identity -* Uses identity-based comparison so each instance is unique and distinguishable -* Implements hashable protocol enabling use in sets and as dictionary keys -* Supports subclassing for creating domain-specific falsey types with custom - string representations -* Maintains compatibility with standard Python object protocols - -Non-Goals -=============================================================================== - -The library explicitly does not provide: - -* **Singleton management**: Users implement singleton patterns themselves -* **Immutability guarantees**: Base class does not enforce immutability -* **Ordered comparisons**: ``<``, ``<=``, ``>``, ``>=`` operations are not supported -* **Serialization support**: No built-in pickle or JSON serialization -* **Thread safety mechanisms**: Users handle concurrency as needed - -Functional Requirements -=============================================================================== - -FR-1: Boolean Evaluation -------------------------------------------------------------------------------- - -The ``Falsifier`` class shall implement ``__bool__`` to return ``False``. - -FR-2: Identity-Based Hashing -------------------------------------------------------------------------------- - -The ``Falsifier`` class shall implement ``__hash__`` using object identity -(``id(self)``). - -FR-3: String Representations -------------------------------------------------------------------------------- - -The ``Falsifier`` class shall provide: - -* ``__str__`` returning ``'False_'`` -* ``__repr__`` returning the fully qualified class name with empty call syntax - -FR-4: Equality Comparison -------------------------------------------------------------------------------- - -The ``Falsifier`` class shall implement: - -* ``__eq__`` returning ``self is other`` -* ``__ne__`` returning ``self is not other`` - -FR-5: Ordered Comparison Rejection -------------------------------------------------------------------------------- - -The ``Falsifier`` class shall implement ``__lt__``, ``__le__``, ``__gt__``, -and ``__ge__`` to return ``NotImplemented``. - -FR-6: Subclass Compatibility -------------------------------------------------------------------------------- - -The ``Falsifier`` class shall support subclassing without requiring special -metaclass machinery. - -Non-Functional Requirements -=============================================================================== - -NFR-1: Minimal Dependencies -------------------------------------------------------------------------------- - -The library shall depend only on: - -* Python standard library -* ``classcore`` for utility functions -* ``dynadoc`` for documentation support -* ``typing_extensions`` for type annotations - -NFR-2: Type Annotation Support -------------------------------------------------------------------------------- - -All public APIs shall include complete type annotations compatible with -``mypy`` and ``pyright``. - -NFR-3: Cross-Version Compatibility -------------------------------------------------------------------------------- - -The library shall support all actively maintained Python versions (currently -3.9+). - -NFR-4: Zero Runtime Overhead -------------------------------------------------------------------------------- - -The ``Falsifier`` class shall impose minimal runtime overhead beyond basic -object creation costs. \ No newline at end of file