Use type hints to document an integration boundary

Type hints let callers and tools see the intended contract, but Python annotations alone do not validate untrusted JSON. Use them with explicit runtime parsing.

Inspect a typed function

The engineering foundations lab exposes a synthetic order boundary.

from engineering_cases import type_boundary_case

result = type_boundary_case()
assert "order_id: 'str'" in result["signature"]
assert result["sample"] == {"order_id": "O-1", "amount": 12.5, "dry_run": True}
assert result["annotations"]["amount"] == "float"

Name domain values, return typed models rather than ambiguous dictionaries, and distinguish None from absent fields. Protocols can describe clients; TypedDict or data models can describe records. Keep network payload parsing at the boundary so internal code receives validated values.

Run a static checker in CI, but test runtime failures too: wrong type, missing field, extra field, invalid range and upstream schema drift. Never assume an API obeys its documented type.

The FDE for Freshers course uses typing across Python packages, FastAPI and integration adapters.

Exercise

Type a payment-adapter interface and two implementations. Feed malformed JSON through the parser and prove invalid data cannot reach either implementation.

Continue learning

This article is part of the FDE engineering foundations sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Design a small package with explicit dependencies.
• Continue with Write unit tests around a business rule.

Reference: Python typing documentation.