# Absence Architecture

The `absence` package provides a falsey sentinel singleton and factory for
representing absent values in contexts where `None` or `False` might be
valid values. This is a focused, single-purpose library designed around
simplicity and type safety.

## Major Components

The system consists of five primary components organized in a flat module
structure:

### Sentinel Factory (`objects.py`)

**AbsenceFactory**
  Base class for creating arbitrary absence sentinels. Inherits from
  `falsifier.Falsifier` to ensure falsey behavior in boolean contexts.
  Provides customization hooks for `__repr__` and `__str__` representations.
  Explicitly prevents pickling to maintain singleton semantics.

**AbsentSingleton**
  Specialized subclass implementing the global `absent` sentinel using
  singleton pattern. Overrides `__new__` to ensure only one instance exists
  per process. Provides fixed string representations.

**Type Utilities**
  - `is_absence()`: Type guard checking if value is any AbsenceFactory instance
  - `is_absent()`: Type guard checking if value is the global `absent` singleton
  - `is_present()`: Positive-form type guard, narrows `Absential[T]` to `T`
  - `Absential[T]`: Type alias equivalent to `T | AbsentSingleton`

### Cell Container (`cell.py`)

**AbsenceCell**
  Immutable generic container wrapping `Absential[T]` with a rich API for
  conditional operations. Provides safe extraction (`extract`, `extract_or`),
  evaluation (`evaluate_or`, `evaluate_or_true`, `evaluate_or_false`),
  transformation (`transform`), chaining (`or_else`), and Optional bridging
  (`from_optional`, `to_optional`).

### Dataclass Adapters (`adapters.py`)

**adapt_dataclass()**
  Extracts fields from a dataclass instance into a dictionary, omitting
  fields whose value matches a configurable skip value (default: `None`).
  Bridges CLI dataclasses (which use `None` for "not provided") to functions
  with `Absential[T]` parameters (which default to `absent`). Works with
  TypedDict + `cast()` for type-safe call sites.

### Builtins Integration (`installers.py`)

**install() function**
  Provides optional installation of `absent` sentinel and `is_absent`
  predicate into Python's builtins module, following naming conventions of
  built-in types (`None`, `Ellipsis`) and predicates (`isinstance`).
  Supports customizable names for both components.

### Exception Hierarchy (`exceptions.py`)

**Omniexception/Omnierror**
  Base exception types integrating with `classcore` attribute visibility
  system for consistent exception handling across the package.

**OperationValidityError**
  Raised when invalid operations are attempted (e.g., pickling absence sentinels).

**CellStateError**
  Raised when extracting from an empty AbsenceCell. Inherits from ValueError.

### Import Management (`__/` subpackage)

**Centralized imports hub**
  - `imports.py`: External library imports (`classcore`, `dynadoc`, `typing_extensions`)
  - `nomina.py`: Common type aliases and package-specific names
  - `__init__.py`: Re-exports for consistent access via `from . import __` pattern

## Component Relationships

The architecture maintains strict separation of concerns:

```
__init__.py
├── imports from objects.py
│   ├── AbsenceFactory (base)
│   ├── AbsentSingleton (singleton)
│   ├── absent (global instance)
│   ├── is_absence() (predicate)
│   ├── is_absent() (predicate)
│   ├── is_present() (predicate)
│   └── Absential (type alias)
├── imports from cell.py
│   └── AbsenceCell (container)
├── imports from adapters.py
│   └── adapt_dataclass() (dataclass helper)
├── imports from installers.py
│   └── install() (builtins integration)
└── imports from exceptions.py
    └── exception hierarchy

All modules depend on __/ for imports
objects.py depends on exceptions.py and falsifier
cell.py depends on objects.py and exceptions.py
adapters.py depends on exceptions.py
installers.py depends on objects.py
No circular dependencies
```

## Key Architectural Patterns

**Singleton Pattern**
  `AbsentSingleton` implements singleton via `__new__` override,
  ensuring process-wide uniqueness of the `absent` sentinel.

**Factory Pattern**
  `AbsenceFactory` enables creation of package-specific absence sentinels
  while maintaining consistent behavior.

**Type Safety**
  Type guards (`TypeIs`) and type aliases (`Absential`) provide static
  type checking support for absence detection.

**Inheritance-Based Behavior**
  Falsey behavior inherited from `falsifier.Falsifier` rather than
  implemented directly, following composition over duplication.

**Immutability by Convention**
  Absence sentinels prevent pickling and discourage modification, though
  complete immutability is documented as a future enhancement.

## Data Flow

The package has minimal data flow as it primarily provides sentinel values:

1. Package initialization creates the global `absent` singleton
2. User code imports `absent`, predicates, and types
3. User code uses `absent` as default values or sentinel markers
4. Predicates check identity (`is`) against sentinels
5. Optional: `install()` exposes symbols to builtins namespace

## Deployment Architecture

Pure Python library with no external runtime dependencies beyond:

- `falsifier`: Provides base falsey object behavior
- `classcore`: Standard object utilities and attribute management
- `dynadoc`: Documentation annotation support
- `typing_extensions`: Modern type hint support

Deployed as a standard Python package via PyPI. No services, daemons, or
persistent state.
