Absence Gate¶
Category: Gate Pattern
Overview¶
An absence gate asserts that something removed from a codebase stays removed. It is the simplest gate to write and the one whose assertion carries the least information: assert not hasattr(module, "NAME") tells a future reader what is checked but nothing about why. The value of the pattern lies in the recorded reason, which is what stops a withdrawn name from being reintroduced by someone who never learned why it went.
Concepts¶
Withdrawn Name¶
A record of something deliberately removed: the name, the date it was withdrawn, and the failure that motivated the removal. The date and the failure are the payload; the name alone is recoverable from the assertion.
Reintroduction¶
The failure mode the gate detects. A withdrawn name reappears because the absence looked like an oversight rather than a decision. Without a recorded reason, reintroduction is indistinguishable from a missing feature being supplied.
Usage Guidelines¶
Use when:
- Something was deleted for a reason that is not obvious from its absence
- A feature was withdrawn after causing a failure that would recur if it returned
- A name encoded an assumption that turned out to be wrong
Avoid when:
- The absence is self-evident, such as a name the type checker or a compiler would reject
- The removal was cosmetic, such as a rename with no behavioural consequence
- The construct cannot be reintroduced by accident because nothing in the design has a place for it
Implementation¶
from dataclasses import dataclass
@dataclass(frozen=True)
class WithdrawnName:
"""A name removed on purpose, with the failure that caused the removal."""
name: str
withdrawn_on: str
reason: str
def message(self) -> str:
"""Failure text naming the date and the original failure."""
return (
f"{self.name} was withdrawn on {self.withdrawn_on} and has been "
f"reintroduced. {self.reason} Remove it again, or record why the "
f"original failure no longer applies."
)
class AbsenceGate:
"""Fails when any withdrawn name is present in a namespace."""
def __init__(self, withdrawn: list[WithdrawnName]) -> None:
self._withdrawn = list(withdrawn)
def violations(self, namespace: object) -> list[str]:
"""Messages for every withdrawn name found on the namespace."""
return [
entry.message()
for entry in self._withdrawn
if hasattr(namespace, entry.name)
]
def check(self, namespace: object) -> None:
"""Raise AssertionError listing every reintroduced name."""
violations = self.violations(namespace)
if violations:
raise AssertionError("\n".join(violations))
Usage¶
IMPORT_SUFFIX = WithdrawnName(
name="IMPORTED_SUFFIX",
withdrawn_on="260806",
reason=(
"The suffix described how a record reached the system rather than what "
"it was, and deriving it from a mutable field broke every re-import "
"after a rename."
),
)
gate = AbsenceGate([IMPORT_SUFFIX])
gate.check(importer_module) # raises if IMPORTED_SUFFIX is back
Trade-offs¶
Benefits:
- Converts a deletion decision into a check the build enforces
- Carries the original failure forward to whoever next considers the feature
- Costs almost nothing to write and to run
Drawbacks:
- Detects reintroduction under the original name only; the same idea under a new name passes
- Accumulates entries that eventually describe a codebase nobody remembers
- Reads as an obstacle when the reason is missing or vague, inviting deletion of the gate itself
Real-World Examples¶
- Deprecation gates that fail when a removed configuration key reappears
- Lint rules banning an API that caused a production incident
- Database migration checks asserting that a dropped column is not recreated
Related Patterns¶
- Population Gate detects unwanted duplication rather than unwanted return
- Boundary Gate applies the same recorded-reason discipline to layering
- Grandfathered-Debt Gate records measurements where this records decisions
API Reference¶
design_patterns.gates.absence
¶
Absence Gate: assert that a withdrawn name stays withdrawn.
The assertion in an absence gate carries almost no information on its own.
assert not hasattr(module, "NAME") tells a future reader what is checked but
not why, and a check whose purpose is unclear is deleted as an obstacle. This
module therefore pairs each check with the date of the removal and the failure
that motivated it, and puts both into the failure message.
AbsenceGate
¶
Fails when any withdrawn name is present in a namespace.
Example
Source code in src/design_patterns/gates/absence.py
__init__(withdrawn)
¶
Record the names that must stay absent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
withdrawn
|
Sequence[WithdrawnName]
|
The removal decisions this gate enforces. |
required |
check(namespace)
¶
Assert that no withdrawn name is present.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
object
|
A module, class, or object to inspect. |
required |
Raises:
| Type | Description |
|---|---|
AssertionError
|
If any withdrawn name has been reintroduced. The message lists every reintroduction with its recorded reason. |
Source code in src/design_patterns/gates/absence.py
violations(namespace)
¶
Find every withdrawn name present on a namespace.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
object
|
A module, class, or object to inspect. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: One message per reintroduced name, in the order the names were recorded. |
Source code in src/design_patterns/gates/absence.py
WithdrawnName
dataclass
¶
A name removed on purpose, with the failure that caused the removal.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The attribute name that must not reappear. |
withdrawn_on |
str
|
Date of the removal in YYMMDD format. |
reason |
str
|
The failure the removal prevents, stated in the past tense. |
Example
Source code in src/design_patterns/gates/absence.py
message()
¶
Build the failure text for a reintroduction.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Text naming the withdrawn name, the date, the original failure, and the action the reader should take. |