annotated-doc 0.0.5: annotated_doc.Doc

# annotated-doc API and typing.Annotated metadata

This sample pins `annotated-doc` 0.0.5 and verifies `annotated_doc.Doc` for inline type annotation documentation.

The contract verifies:
- `Doc` initialization with positional-only documentation string and `.documentation` attribute access.
- `Doc` value equality (`__eq__`), hashing (`__hash__`), and string representation (`__repr__`).
- Integration with standard `typing.Annotated` for function parameter, return type, and class attribute metadata extraction via `typing.get_type_hints(..., include_extras=True)` and `typing.get_args(...)`.
- TypeError enforcement when invoked with missing arguments or keyword arguments (positional-only parameter).

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/annotated-doc@0.0.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/annotated-doc@0.0.5
Demonstrate these symbols/APIs:
  - annotated_doc.Doc

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:725df5fe2284f9f089f1b224b4dc859ee564d7f4cfb882919169a5a90d0ba4b9","contract":["Doc accepts a positional-only documentation string and exposes it via the documentation attribute.","Doc implements equality (__eq__) and hashing (__hash__) matching the documentation string value.","Doc representation (__repr__) formats as Doc('...') with the exact documentation string.","Doc metadata integrates with typing.Annotated and is retrievable via typing.get_type_hints and typing.get_args.","Doc raises TypeError when instantiated without arguments or with keyword arguments."],"goal":"verify pkg:pypi/annotated-doc@0.0.5","kind":"HOW","packages":["pkg:pypi/annotated-doc@0.0.5"],"schemaVersion":1,"symbols":["annotated_doc.Doc"]},"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-doc@0.0.5"],"schemaVersion":1,"subject":"pkg:pypi/annotated-doc@0.0.5","symbols":["annotated_doc.Doc"],"verifierAdapter":"python@1"}

annotated-doc==0.0.5

{
  "schemaVersion": 1,
  "goal": "verify pkg:pypi/annotated-doc@0.0.5",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/annotated-doc@0.0.5"
  ],
  "symbols": [
    "annotated_doc.Doc"
  ]
}

from typing import Annotated, get_args, get_type_hints
import annotated_doc
from annotated_doc import Doc

# 1. Verify package version and Doc initialization with positional-only string
assert hasattr(annotated_doc, "__version__"), "annotated_doc must define __version__"
assert annotated_doc.__version__ == "0.0.5", f"Expected version 0.0.5, got {annotated_doc.__version__}"

doc = Doc("The user unique identifier")
assert isinstance(doc, Doc), f"Expected Doc instance, got {type(doc)}"
assert doc.documentation == "The user unique identifier", f"Expected documentation string, got {doc.documentation}"

# 2. Verify Doc string representation, equality, and hashing
assert repr(doc) == "Doc('The user unique identifier')", f"Unexpected repr: {repr(doc)}"
doc_same = Doc("The user unique identifier")
doc_diff = Doc("Different description")
assert doc == doc_same, "Doc instances with identical documentation strings must be equal"
assert doc != doc_diff, "Doc instances with different documentation strings must not be equal"
assert doc != "The user unique identifier", "Doc instance should not be equal to raw string"
assert hash(doc) == hash(doc_same), "Equal Doc instances must produce identical hash values"
assert hash(doc) == hash("The user unique identifier"), "Doc hash should match hash of documentation string"

# 3. Verify Doc usage in typing.Annotated with function parameters and return type
def create_greeting(
    name: Annotated[str, Doc("Name of the recipient to greet")],
    count: Annotated[int, Doc("Number of times to repeat greeting")] = 1,
) -> Annotated[str, Doc("Formatted greeting message")]:
    return " ".join([f"Hello, {name}!"] * count)

hints = get_type_hints(create_greeting, include_extras=True)
assert "name" in hints and "count" in hints and "return" in hints

name_args = get_args(hints["name"])
assert name_args[0] is str
assert isinstance(name_args[1], Doc)
assert name_args[1].documentation == "Name of the recipient to greet"

count_args = get_args(hints["count"])
assert count_args[0] is int
assert isinstance(count_args[1], Doc)
assert count_args[1].documentation == "Number of times to repeat greeting"

return_args = get_args(hints["return"])
assert return_args[0] is str
assert isinstance(return_args[1], Doc)
assert return_args[1].documentation == "Formatted greeting message"

# 4. Verify Doc metadata on class attribute type annotations
class UserProfile:
    user_id: Annotated[int, Doc("Primary identifier for user account")]
    email: Annotated[str, Doc("Email address for notifications")]

class_hints = get_type_hints(UserProfile, include_extras=True)
user_id_args = get_args(class_hints["user_id"])
assert user_id_args[0] is int
assert user_id_args[1] == Doc("Primary identifier for user account")

email_args = get_args(class_hints["email"])
assert email_args[0] is str
assert email_args[1] == Doc("Email address for notifications")

# 5. Verify type safety: missing arguments and keyword arguments raise TypeError
try:
    Doc()
    raise AssertionError("Doc() without arguments must raise TypeError")
except TypeError:
    pass

try:
    Doc(documentation="Keyword argument not allowed")
    raise AssertionError("Doc(documentation=...) keyword invocation must raise TypeError")
except TypeError:
    pass

print("CONTRACT PASS: pkg:pypi/annotated-doc@0.0.5 verified offline")