typing-inspection 0.4.2: typing_inspection.introspection.inspect_annotation

# typing-inspection Type Annotation Introspection

This sample pins `typing-inspection` 0.4.2 and verifies `typing_inspection.introspection.inspect_annotation` for inspecting Python type annotations, qualifiers, and metadata.

The contract verifies:
- `inspect_annotation` unwraps `Annotated` metadata and returns `InspectedAnnotation` with empty qualifiers for `AnnotationSource.BARE`.
- `inspect_annotation` extracts `ClassVar` and `Final` qualifiers and inner metadata for `AnnotationSource.CLASS`.
- `inspect_annotation` extracts `ReadOnly`, `Required`, and `NotRequired` qualifiers for `AnnotationSource.TYPED_DICT`.
- `inspect_annotation` extracts `InitVar` qualifier for `AnnotationSource.DATACLASS`.
- `inspect_annotation` raises `ForbiddenQualifier` when a qualifier is invalid for the specified `AnnotationSource` context.
- `get_literal_values` extracts and recursively flattens literal values from `typing.Literal` definitions.

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 pkg:pypi/typing-inspection@0.4.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/typing-inspection@0.4.2
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:38c86c5acf306e5833fcca7a3cb8fdb456470096f92e9e331c6795781a247133","contract":["inspect_annotation unwraps Annotated metadata and returns InspectedAnnotation with empty qualifiers for AnnotationSource.BARE.","inspect_annotation extracts ClassVar and Final qualifiers and inner metadata for AnnotationSource.CLASS.","inspect_annotation extracts ReadOnly, Required, and NotRequired qualifiers for AnnotationSource.TYPED_DICT.","inspect_annotation extracts InitVar qualifier for AnnotationSource.DATACLASS.","inspect_annotation raises ForbiddenQualifier when a qualifier is invalid for the specified AnnotationSource context.","get_literal_values extracts and recursively flattens literal values from typing.Literal definitions."],"goal":"verify pkg:pypi/typing-inspection@0.4.2","kind":"HOW","packages":["pkg:pypi/typing-inspection@0.4.2"],"schemaVersion":1,"symbols":["typing_inspection.introspection.inspect_annotation"]},"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/typing-inspection@0.4.2"],"schemaVersion":1,"subject":"pkg:pypi/typing-inspection@0.4.2","symbols":["typing_inspection.introspection.inspect_annotation"],"verifierAdapter":"python@1"}

typing-inspection==0.4.2
typing-extensions==4.16.0

{
  "schemaVersion": 1,
  "goal": "verify pkg:pypi/typing-inspection@0.4.2",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/typing-inspection@0.4.2"
  ],
  "symbols": [
    "typing_inspection.introspection.inspect_annotation"
  ]
}

import sys
from typing import Annotated, ClassVar, Final, Literal, Union, get_origin
from typing_extensions import NotRequired, ReadOnly, Required
from dataclasses import InitVar

import typing_inspection
from typing_inspection.introspection import (
    AnnotationSource,
    ForbiddenQualifier,
    InspectedAnnotation,
    get_literal_values,
    inspect_annotation,
    is_union_origin,
)
import typing_inspection.typing_objects as to

# 1. Verify package import and inspect_annotation with bare Annotated unwrap
bare = inspect_annotation(Annotated[int, "meta_1", "meta_2"], annotation_source=AnnotationSource.BARE)
assert isinstance(bare, InspectedAnnotation), "Expected InspectedAnnotation instance"
assert bare.type is int, f"Expected int, got {bare.type}"
assert bare.qualifiers == set(), f"Expected empty qualifiers, got {bare.qualifiers}"
assert bare.metadata == ["meta_1", "meta_2"], f"Expected metadata list, got {bare.metadata}"

# 2. Verify Class annotation with nested qualifiers and metadata
class_ann = inspect_annotation(
    Final[Annotated[ClassVar[Annotated[str, "inner_meta"]], "outer_meta"]],
    annotation_source=AnnotationSource.CLASS,
)
assert class_ann.type is str, f"Expected str, got {class_ann.type}"
assert class_ann.qualifiers == {"class_var", "final"}, f"Expected class_var and final, got {class_ann.qualifiers}"
assert class_ann.metadata == ["inner_meta", "outer_meta"], f"Expected metadata, got {class_ann.metadata}"

# 3. Verify TypedDict qualifiers: ReadOnly and NotRequired
td_ann = inspect_annotation(
    ReadOnly[NotRequired[int]],
    annotation_source=AnnotationSource.TYPED_DICT,
)
assert td_ann.type is int, f"Expected int, got {td_ann.type}"
assert td_ann.qualifiers == {"read_only", "not_required"}, f"Expected read_only and not_required, got {td_ann.qualifiers}"
assert td_ann.metadata == []

# 4. Verify Dataclass qualifiers: InitVar
dc_ann = inspect_annotation(
    InitVar[float],
    annotation_source=AnnotationSource.DATACLASS,
)
assert dc_ann.type is float, f"Expected float, got {dc_ann.type}"
assert dc_ann.qualifiers == {"init_var"}, f"Expected init_var, got {dc_ann.qualifiers}"

# 5. Verify ForbiddenQualifier error handling on mismatched context
try:
    inspect_annotation(Required[str], annotation_source=AnnotationSource.CLASS)
    raise AssertionError("Expected ForbiddenQualifier when Required is used in AnnotationSource.CLASS")
except ForbiddenQualifier as exc:
    assert exc.qualifier == "required", f"Expected qualifier required, got {exc.qualifier}"

try:
    inspect_annotation(ClassVar[int], annotation_source=AnnotationSource.FUNCTION)
    raise AssertionError("Expected ForbiddenQualifier when ClassVar is used in AnnotationSource.FUNCTION")
except ForbiddenQualifier as exc:
    assert exc.qualifier == "class_var", f"Expected qualifier class_var, got {exc.qualifier}"

# 6. Verify get_literal_values extracts and flattens nested Literal values
lit_vals = list(get_literal_values(Literal[Literal["read", "write"], "append", 42]))
assert lit_vals == ["read", "write", "append", 42], f"Expected [read, write, append, 42], got {lit_vals}"

# 7. Verify is_union_origin and typing_objects predicate helpers
assert is_union_origin(get_origin(Union[int, str])), "is_union_origin must return True for Union origin"
assert not is_union_origin(list), "is_union_origin must return False for list"
assert to.is_annotated(Annotated), "is_annotated must return True for Annotated"
assert to.is_annotated(get_origin(Annotated[int, "tag"])), "is_annotated must return True for get_origin(Annotated)"
assert to.is_final(Final), "is_final must return True for Final"
assert to.is_classvar(ClassVar), "is_classvar must return True for ClassVar"
assert to.is_literal(Literal), "is_literal must return True for Literal"

print("CONTRACT PASS: pkg:pypi/typing-inspection@0.4.2 verified offline")