typing-inspection 0.4.4: typing_inspection.introspection.inspect_annotation

# typing-inspection Type Annotation Introspection

This sample pins `typing-inspection` 0.4.4 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` handles bare qualifier forms returning `UNKNOWN` type.
- `inspect_annotation` raises `ForbiddenQualifier` when a qualifier is invalid for the specified `AnnotationSource` context.
- `inspect_annotation` supports unpacking `Annotated` metadata from `TypeAliasType` with `unpack_type_aliases` parameter.
- `get_literal_values` extracts and recursively flattens literal values from `typing.Literal` definitions.
- `is_union_origin` and `typing_objects` predicates correctly inspect types and origins.

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.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/typing-inspection@0.4.4
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:563049a9921f26b07021ecdf5ef0d517ea2ac180437722059a7d38104527e762","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.","inspect_annotation supports unpacking Annotated metadata from TypeAliasType.","get_literal_values extracts and recursively flattens literal values from typing.Literal definitions."],"goal":"verify pkg:pypi/typing-inspection@0.4.4","kind":"HOW","packages":["pkg:pypi/typing-inspection@0.4.4"],"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.4"],"schemaVersion":1,"subject":"pkg:pypi/typing-inspection@0.4.4","symbols":["typing_inspection.introspection.inspect_annotation"],"verifierAdapter":"python@1"}

typing-inspection==0.4.4
typing-extensions==4.16.0

{
  "schemaVersion": 1,
  "goal": "verify pkg:pypi/typing-inspection@0.4.4",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/typing-inspection@0.4.4"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

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

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

# 1. Verify bare annotation inspection and metadata unwrapping
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, Required, 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}"

# Bare qualifier forms yield UNKNOWN type
bare_final = inspect_annotation(Final, annotation_source=AnnotationSource.CLASS)
assert bare_final.type is UNKNOWN
assert bare_final.qualifiers == {"final"}

bare_initvar = inspect_annotation(InitVar, annotation_source=AnnotationSource.DATACLASS)
assert bare_initvar.type is UNKNOWN
assert bare_initvar.qualifiers == {"init_var"}

# 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 TypeAliasType unpacking with unpack_type_aliases modes
AliasWithMeta = TypeAliasType("AliasWithMeta", Annotated[str, "alias_tag"])
unpacked = inspect_annotation(AliasWithMeta, annotation_source=AnnotationSource.BARE, unpack_type_aliases="eager")
assert unpacked.type is str, f"Expected str, got {unpacked.type}"
assert unpacked.metadata == ["alias_tag"], f"Expected alias_tag metadata, got {unpacked.metadata}"

skipped = inspect_annotation(AliasWithMeta, annotation_source=AnnotationSource.BARE, unpack_type_aliases="skip")
assert skipped.type is AliasWithMeta, f"Expected AliasWithMeta, got {skipped.type}"
assert skipped.metadata == [], f"Expected empty metadata, got {skipped.metadata}"

# 7. 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}"

# 8. 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"
assert to.is_required(Required), "is_required must return True for Required"
assert to.is_notrequired(NotRequired), "is_notrequired must return True for NotRequired"
assert to.is_readonly(ReadOnly), "is_readonly must return True for ReadOnly"
assert to.is_typealiastype(AliasWithMeta), "is_typealiastype must return True for TypeAliasType"

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