annotated-types 0.8.0: annotated_types

# annotated-types core protocols, constraints, and typing.Annotated reflection

This sample pins `annotated-types` 0.8.0 and verifies core protocols, constraints, and documentation metadata: `BaseMetadata`, `GroupedMetadata`, `MultipleOf`, `Timezone`, `Unit`, `doc`/`DocInfo`, and predefined predicate type aliases (`LowerCase`, `UpperCase`, `IsDigits`, `IsFinite`, etc.).

The contract verifies:
- Top-level package version and exports (`__version__ == '0.8.0'`, `__all__`, `BaseMetadata`, `GroupedMetadata`).
- Protocol enforcement for `GroupedMetadata` ensuring subclasses define `__iter__` or raise `TypeError`.
- Frozen constraint metadata (`MultipleOf`, `Timezone`, `Unit`) inheriting from `BaseMetadata` with equality, hash, and attribute semantics.
- Timezone awareness metadata accepting `None` (naive), `...` (aware), `datetime.timezone` objects, or strings.
- Documentation metadata `doc` / `Doc` / `DocInfo` storing description strings under PEP 727.
- Standard predicate type aliases wrapping `Predicate` with standard validation functions.
- Offline reflection with standard `typing.Annotated`, `typing.get_type_hints(..., include_extras=True)`, and `typing.get_args(...)`.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify annotated_types in pkg:pypi/annotated-types@0.8.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/annotated-types@0.8.0
Demonstrate these symbols/APIs:
  - annotated_types

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:08ffb6cc3fd984cd4938df43433c4fc5f56d3bae4e6d559571ea953f18ecbf8c","contract":["annotated_types exports __version__ 0.8.0 and core metadata protocols including BaseMetadata and GroupedMetadata.","GroupedMetadata enforces protocol implementation requiring subclasses to define __iter__ or raise TypeError upon subclassing.","MultipleOf, Timezone, and Unit provide frozen constraint metadata inheriting from BaseMetadata with equality and hash semantics.","Predefined predicate type aliases such as LowerCase, UpperCase, IsDigits, and IsFinite wrap Predicate with standard validation functions.","annotated_types metadata integrates with typing.Annotated for parameter and return type reflection retrievable via typing.get_type_hints."],"goal":"verify annotated_types in pkg:pypi/annotated-types@0.8.0","kind":"HOW","packages":["pkg:pypi/annotated-types@0.8.0"],"schemaVersion":1,"symbols":["annotated_types"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","executionContext":"python","language":"python","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/annotated-types@0.8.0"],"schemaVersion":1,"subject":"pkg:pypi/annotated-types@0.8.0","symbols":["annotated_types"],"verifierAdapter":"python@1"}

annotated-types==0.8.0

{
  "schemaVersion": 1,
  "goal": "verify annotated_types in pkg:pypi/annotated-types@0.8.0",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/annotated-types@0.8.0"
  ],
  "symbols": [
    "annotated_types"
  ]
}

import math
from datetime import datetime, timezone
from typing import Annotated, get_args, get_type_hints
import annotated_types
from annotated_types import (
    BaseMetadata,
    Doc,
    DocInfo,
    GroupedMetadata,
    IsAscii,
    IsDigits,
    IsFinite,
    IsInfinite,
    IsNan,
    IsNotFinite,
    IsNotInfinite,
    IsNotNan,
    LowerCase,
    MultipleOf,
    Predicate,
    Timezone,
    Unit,
    UpperCase,
    doc,
)

# 1. Package metadata and top-level exports
assert hasattr(annotated_types, "__version__"), "annotated_types must define __version__"
assert annotated_types.__version__ == "0.8.0", f"Expected version 0.8.0, got {annotated_types.__version__}"
assert "BaseMetadata" in annotated_types.__all__
assert "GroupedMetadata" in annotated_types.__all__
assert "MultipleOf" in annotated_types.__all__
assert "Timezone" in annotated_types.__all__
assert "doc" in annotated_types.__all__
assert "DocInfo" in annotated_types.__all__
assert "LowerCase" in annotated_types.__all__
assert "UpperCase" in annotated_types.__all__
assert "IsDigits" in annotated_types.__all__
assert "IsFinite" in annotated_types.__all__
assert hasattr(annotated_types, "Unit")

# 2. BaseMetadata & GroupedMetadata protocol enforcement
assert hasattr(BaseMetadata, "__slots__")
base_instance = BaseMetadata()
assert isinstance(base_instance, BaseMetadata)

class CustomGroup(GroupedMetadata):
    def __init__(self, *items):
        self.items = items

    def __iter__(self):
        return iter(self.items)

cg = CustomGroup(base_instance)
assert isinstance(cg, GroupedMetadata)
assert cg.__is_annotated_types_grouped_metadata__ is True
assert list(cg) == [base_instance]

try:
    class IncompleteGroup(GroupedMetadata):
        pass
    assert False, "Should have raised TypeError for missing __iter__"
except TypeError as exc:
    assert "Can't subclass GroupedMetadata without implementing __iter__" in str(exc)

# 3. MultipleOf constraint
assert issubclass(MultipleOf, BaseMetadata)
mo5 = MultipleOf(5)
assert mo5.multiple_of == 5
assert mo5 == MultipleOf(5)
assert mo5 != MultipleOf(10)
assert hash(mo5) == hash(MultipleOf(5))

# 4. Timezone constraint (aware, naive, tzinfo, string)
assert issubclass(Timezone, BaseMetadata)
tz_naive = Timezone(None)
tz_aware = Timezone(...)
tz_utc = Timezone(timezone.utc)
tz_str = Timezone("UTC")

assert tz_naive.tz is None
assert tz_aware.tz is ...
assert tz_utc.tz == timezone.utc
assert tz_str.tz == "UTC"
assert tz_utc == Timezone(timezone.utc)
assert tz_naive != tz_aware

# 5. Unit constraint
assert issubclass(Unit, BaseMetadata)
unit_meter = Unit("m")
assert unit_meter.unit == "m"
assert unit_meter == Unit("m")
assert unit_meter != Unit("kg")
assert hash(unit_meter) == hash(Unit("m"))

# 6. Documentation metadata (doc / Doc / DocInfo)
d = doc("Field documentation")
assert isinstance(d, Doc)
assert isinstance(d, DocInfo)
assert d.documentation == "Field documentation"
assert d == Doc("Field documentation")
assert d != Doc("Different text")

# 7. Predefined predicate aliases
lower_args = get_args(LowerCase)
assert len(lower_args) == 2
assert isinstance(lower_args[1], Predicate)
assert lower_args[1].func is str.islower

upper_args = get_args(UpperCase)
assert isinstance(upper_args[1], Predicate)
assert upper_args[1].func is str.isupper

digits_args = get_args(IsDigits)
assert isinstance(digits_args[1], Predicate)
assert digits_args[1].func is str.isdigit

ascii_args = get_args(IsAscii)
assert isinstance(ascii_args[1], Predicate)
assert ascii_args[1].func is str.isascii

finite_args = get_args(IsFinite)
assert isinstance(finite_args[1], Predicate)
assert finite_args[1].func is math.isfinite

not_finite_args = get_args(IsNotFinite)
assert isinstance(not_finite_args[1], Predicate)
assert not_finite_args[1].func(float("inf")) is True
assert not_finite_args[1].func(1.0) is False

nan_args = get_args(IsNan)
assert isinstance(nan_args[1], Predicate)
assert nan_args[1].func is math.isnan

not_nan_args = get_args(IsNotNan)
assert isinstance(not_nan_args[1], Predicate)
assert not_nan_args[1].func(float("nan")) is False
assert not_nan_args[1].func(1.0) is True

inf_args = get_args(IsInfinite)
assert isinstance(inf_args[1], Predicate)
assert inf_args[1].func is math.isinf

not_inf_args = get_args(IsNotInfinite)
assert isinstance(not_inf_args[1], Predicate)
assert not_inf_args[1].func(float("inf")) is False
assert not_inf_args[1].func(1.0) is True

# 8. Integration with typing.Annotated reflection
def validate_entry(
    username: LowerCase,
    step: Annotated[int, MultipleOf(10)],
    timestamp: Annotated[datetime, Timezone(timezone.utc)],
    altitude: Annotated[float, Unit("m")],
    note: Annotated[str, doc("Optional description")],
) -> Annotated[float, Predicate(math.isfinite)]:
    return altitude

hints = get_type_hints(validate_entry, include_extras=True)
assert "username" in hints
assert "step" in hints
assert "timestamp" in hints
assert "altitude" in hints
assert "note" in hints
assert "return" in hints

assert MultipleOf(10) in get_args(hints["step"])
assert Timezone(timezone.utc) in get_args(hints["timestamp"])
assert Unit("m") in get_args(hints["altitude"])
assert doc("Optional description") in get_args(hints["note"])
assert Predicate(math.isfinite) in get_args(hints["return"])

print("CONTRACT PASS: pkg:pypi/annotated-types@0.8.0 verified offline")