# Ahgraber Skills Python Types Contracts

> Python Types and Contracts

- Skill: `tomevault-io/ahgraber-skills-python-types-contracts` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ahgraber-skills-python-types-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ahgraber-skills-python-types-contracts/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/ahgraber-skills-python-types-contracts

---


# Python Types and Contracts

## Overview

Treat type hints as interface design, not decoration.
Focus on explicit contracts, stable public APIs, and boundary-safe modeling.

These are preferred defaults for common cases, not universal rules.
When a default conflicts with project constraints, suggest a better-fit alternative and explain tradeoffs and compensating controls.

## When to Use

- Public API signatures lack type annotations or use overly broad types.
- Pydantic models are scattered throughout internal logic instead of at trust boundaries.
- Contract changes risk breaking downstream consumers without migration paths.
- Interfaces accept `Any`, `object`, or untyped dicts where narrower types apply.
- Schema boundaries between layers (API, DB, domain) are implicit or inconsistent.
- Adding or evolving protocols, abstract base classes, or structural subtyping.

**When NOT to use:**

- Pure implementation-level code with no public interface.
- Throwaway scripts or one-off data munging where type rigor adds no value.
- Performance-critical inner loops where typing overhead matters more than safety.

## Quick Reference

- Type public APIs and keep contracts explicit.
- Prefer narrow interfaces and boundary protocols over broad parameter types.
- Use pydantic at trust boundaries by default, not everywhere.
- Make compatibility and migration impact explicit for any contract change.
- Favor `Protocol` for structural subtyping over deep inheritance hierarchies.
- Return concrete types from public functions; accept protocols or unions as inputs.

## Common Mistakes

- **Typing everything identically.**
  Internal helpers don't need the same rigor as public APIs.
  Over-annotating private code adds noise without safety.
- **Pydantic everywhere.**
  Using pydantic models for internal data flow instead of reserving them for validation at trust boundaries (API ingress, config loading, external data).
- **Broad return types.**
  Returning `Any` or `dict` from public functions forces callers to guess structure.
  Return concrete types or TypedDicts.
- **Breaking contracts silently.**
  Changing function signatures, removing fields, or narrowing accepted types without versioning, deprecation warnings, or migration notes.
- **Ignoring `None`.**
  Omitting `Optional` or union with `None` when a value can legitimately be absent, hiding null-safety bugs until runtime.

## Scope Note

- Treat these recommendations as preferred defaults for common cases, not universal rules.
- If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
- When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

## Invocation Notice

- Inform the user when this skill is being invoked by name: `python-design-modularity`.

## References

- `references/typing-policy.md`
- `references/contract-evolution.md`
- `references/pydantic-boundaries.md`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/ahgraber) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->