Status docstring should warn that synthesized unknown-code members are not identity-stable #14

Problem

Status is an IntEnum with lenient lookup: any integer in the HTTP range 100..599 that has no named member is synthesized into a pseudo-member named UNKNOWN_<code>. Named members behave like normal enum singletons, so Status(200) is Status.OK. Synthesized members do not: _missing_ mints a brand-new instance via int.__new__(cls, value) on every call and never caches it, so Status(218) is Status(218) is False. The class docstring describes the lenient-lookup feature in detail but never mentions this asymmetry, which sets up an easy trap — is is the idiomatic way to compare enum members and works for every named member, so a reader naturally assumes it works for unknown codes too.

Where

packages/dexpace-sdk-core/src/dexpace/sdk/core/http/response/status.py:99-116

@classmethod
def _missing_(cls, value: object) -> Status | None:
    ...
    if isinstance(value, int) and 100 <= value <= 599:
        pseudo = int.__new__(cls, value)
        pseudo._name_ = f"UNKNOWN_{value}"
        pseudo._value_ = value
        return pseudo
    return None

Each lookup returns a fresh object; there is no caching (and caching here would be wrong, since it would leak unbounded entries into __members__).

Impact

Equality (==) and the band predicates (is_success, is_server_error, ...) are all correct, so this is not a correctness bug in those paths. But a consumer who compares a status with is — natural enum reflex, and demonstrably valid for named members — gets a silently wrong False for unknown codes only:

status = response.status            # e.g. Status(218) from an upstream proxy
if status is Status(218):           # always False for unknown codes
    handle_unusual_case()           # never runs

The same code with a named member (status is Status.OK) would work, so the failure mode is inconsistent and hard to spot.

Suggested fix

Add a short caveat to the Status class docstring stating that synthesized UNKNOWN_<code> pseudo-members are value- and equality-comparable but are not identity-stable across lookups, so callers should compare unknown statuses with == or the band predicates rather than is. No behaviour change is needed.