python-typing-ops
Python type hints and type safety patterns. Triggers on: type hints, typing, TypeVar, Generic, Protocol, mypy, pyright, type annotation, overload, TypedDict.
Install
npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/python-typing-ops
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
git clone https://github.com/0xDarkMatter/claude-mods.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Python Typing Patterns
Modern type hints for safe, documented Python code.
Basic Annotations
# Variables
name: str = "Alice"
count: int = 42
items: list[str] = ["a", "b"]
mapping: dict[str, int] = {"key": 1}
# Function signatures
def greet(name: str, times: int = 1) -> str:
return f"Hello, {name}!" * times
# None handling
def find(id: int) -> str | None:
return db.get(id) # May return None
Collections
from collections.abc import Sequence, Mapping, Iterable
# Use collection ABCs for flexibility
def process(items: Sequence[str]) -> list[str]:
"""Accepts list, tuple, or any sequence."""
return [item.upper() for item in items]
def lookup(data: Mapping[str, int], key: str) -> int:
"""Accepts dict or any mapping."""
return data.get(key, 0)
# Nested types
Matrix = list[list[float]]
Config = dict[str, str | int | bool]
Optional and Union
# Modern syntax (3.10+)
def find(id: int) -> User | None:
pass
def parse(value: str | int | float) -> str:
pass
# With default None
def fetch(url: str, timeout: float | None = None) -> bytes:
pass
TypedDict
from typing import TypedDict, Required, NotRequired
class UserDict(TypedDict):
id: int
name: str
email: str | None
class ConfigDict(TypedDict, total=False): # All optional
debug: bool
log_level: str
class APIResponse(TypedDict):
data: Required[list[dict]]
error: NotRequired[str]
def process_user(user: UserDict) -> str:
return user["name"] # Type-safe key access
Callable
from collections.abc import Callable
# Function type
Handler = Callable[[str, int], bool]
def register(callback: Callable[[str], None]) -> None:
pass
# With keyword args (use Protocol instead)
from typing import Protocol
class Processor(Protocol):
def __call__(self, data: str, *, verbose: bool = False) -> int:
...
Generics
from typing import TypeVar
T = TypeVar("T")
def first(items: list[T]) -> T | None:
return items[0] if items else None
# Bounded TypeVar
from typing import SupportsFloat
N = TypeVar("N", bound=SupportsFloat)
def average(values: list[N]) -> float:
return sum(float(v) for v in values) / len(values)
Protocol (Structural Typing)
from typing import Protocol
class Readable(Protocol):
def read(self, n: int = -1) -> bytes:
...
def load(source: Readable) -> dict:
"""Accepts any object with read() method."""
data = source.read()
return json.loads(data)
# Works with file, BytesIO, custom classes
load(open("data.json", "rb"))
load(io.BytesIO(b"{}"))
Type Guards
from typing import TypeGuard
def is_string_list(val: list[object]) -> TypeGuard[list[str]]:
return all(isinstance(x, str) for x in val)
def process(items: list[object]) -> None:
if is_string_list(items):
# items is now list[str]
print(", ".join(items))
Literal and Final
from typing import Literal, Final
Mode = Literal["read", "write", "append"]
def open_file(path: str, mode: Mode) -> None:
pass
# Constants
MAX_SIZE: Final = 1024
API_VERSION: Final[str] = "v2"
Quick Reference
| Type | Use Case |
|---|---|
X \| None |
Optional value |
list[T] |
Homogeneous list |
dict[K, V] |
Dictionary |
Callable[[Args], Ret] |
Function type |
TypeVar("T") |
Generic parameter |
Protocol |
Structural typing |
TypedDict |
Dict with fixed keys |
Literal["a", "b"] |
Specific values only |
Final |
Cannot be reassigned |
Type Checker Commands
# mypy (run inside the project env)
uv run mypy src/ --strict
# pyright
uv run pyright src/
# In pyproject.toml
[tool.mypy]
strict = true
python_version = "3.11"
Emerging: ty — Astral's Rust-based type checker (same toolchain as uv +
ruff), dramatically faster than mypy. Still in preview (pre-1.0), so mypy or
pyright remain the production default — but worth watching, and easy to try:
uvx ty check. Adopt for new projects once it stabilizes.
Additional Resources
./references/generics-advanced.md- TypeVar, ParamSpec, TypeVarTuple./references/protocols-patterns.md- Structural typing, runtime protocols./references/type-narrowing.md- Guards, isinstance, assert./references/mypy-config.md- mypy/pyright configuration./references/runtime-validation.md- Pydantic v2, typeguard, beartype./references/overloads.md- @overload decorator patterns
Scripts
./scripts/check-types.sh- Run type checkers with common options
Assets
./assets/pyproject-typing.toml- Recommended mypy/pyright config
See Also
This is a foundation skill with no prerequisites.
Related Skills:
python-pytest-ops- Type-safe fixtures and mocking
Build on this skill:
python-async-ops- Async type annotationspython-fastapi-ops- Pydantic models and validationpython-database-ops- SQLAlchemy type annotations
Files (claude-mods)
-
assets
-
pyproject-typing.toml 2.5 KB
Loading…
-
-
references
-
generics-advanced.md 6.3 KB
Loading… -
mypy-config.md 5.8 KB
Loading… -
overloads.md 6.3 KB
Loading… -
protocols-patterns.md 6.1 KB
Loading… -
runtime-validation.md 7.4 KB
Loading… -
type-narrowing.md 6 KB
Loading…
-
-
scripts
-
check-types.sh 3.2 KB
Loading…
-
-
SKILL.md 5.3 KB
--- name: python-typing-ops description: "Python type hints and type safety patterns. Triggers on: type hints, typing, TypeVar, Generic, Protocol, mypy, pyright, type annotation, overload, TypedDict." license: MIT compatibility: "Python 3.10+ (uses union syntax X | Y). Some patterns require 3.11+ (Self, TypeVarTuple)." allowed-tools: "Read Write" metadata: author: claude-mods related-skills: python-pytest-ops --- # Python Typing Patterns Modern type hints for safe, documented Python code. ## Basic Annotations ```python # Variables name: str = "Alice" count: int = 42 items: list[str] = ["a", "b"] mapping: dict[str, int] = {"key": 1} # Function signatures def greet(name: str, times: int = 1) -> str: return f"Hello, {name}!" * times # None handling def find(id: int) -> str | None: return db.get(id) # May return None ``` ## Collections ```python from collections.abc import Sequence, Mapping, Iterable # Use collection ABCs for flexibility def process(items: Sequence[str]) -> list[str]: """Accepts list, tuple, or any sequence.""" return [item.upper() for item in items] def lookup(data: Mapping[str, int], key: str) -> int: """Accepts dict or any mapping.""" return data.get(key, 0) # Nested types Matrix = list[list[float]] Config = dict[str, str | int | bool] ``` ## Optional and Union ```python # Modern syntax (3.10+) def find(id: int) -> User | None: pass def parse(value: str | int | float) -> str: pass # With default None def fetch(url: str, timeout: float | None = None) -> bytes: pass ``` ## TypedDict ```python from typing import TypedDict, Required, NotRequired class UserDict(TypedDict): id: int name: str email: str | None class ConfigDict(TypedDict, total=False): # All optional debug: bool log_level: str class APIResponse(TypedDict): data: Required[list[dict]] error: NotRequired[str] def process_user(user: UserDict) -> str: return user["name"] # Type-safe key access ``` ## Callable ```python from collections.abc import Callable # Function type Handler = Callable[[str, int], bool] def register(callback: Callable[[str], None]) -> None: pass # With keyword args (use Protocol instead) from typing import Protocol class Processor(Protocol): def __call__(self, data: str, *, verbose: bool = False) -> int: ... ``` ## Generics ```python from typing import TypeVar T = TypeVar("T") def first(items: list[T]) -> T | None: return items[0] if items else None # Bounded TypeVar from typing import SupportsFloat N = TypeVar("N", bound=SupportsFloat) def average(values: list[N]) -> float: return sum(float(v) for v in values) / len(values) ``` ## Protocol (Structural Typing) ```python from typing import Protocol class Readable(Protocol): def read(self, n: int = -1) -> bytes: ... def load(source: Readable) -> dict: """Accepts any object with read() method.""" data = source.read() return json.loads(data) # Works with file, BytesIO, custom classes load(open("data.json", "rb")) load(io.BytesIO(b"{}")) ``` ## Type Guards ```python from typing import TypeGuard def is_string_list(val: list[object]) -> TypeGuard[list[str]]: return all(isinstance(x, str) for x in val) def process(items: list[object]) -> None: if is_string_list(items): # items is now list[str] print(", ".join(items)) ``` ## Literal and Final ```python from typing import Literal, Final Mode = Literal["read", "write", "append"] def open_file(path: str, mode: Mode) -> None: pass # Constants MAX_SIZE: Final = 1024 API_VERSION: Final[str] = "v2" ``` ## Quick Reference | Type | Use Case | |------|----------| | `X \| None` | Optional value | | `list[T]` | Homogeneous list | | `dict[K, V]` | Dictionary | | `Callable[[Args], Ret]` | Function type | | `TypeVar("T")` | Generic parameter | | `Protocol` | Structural typing | | `TypedDict` | Dict with fixed keys | | `Literal["a", "b"]` | Specific values only | | `Final` | Cannot be reassigned | ## Type Checker Commands ```bash # mypy (run inside the project env) uv run mypy src/ --strict # pyright uv run pyright src/ # In pyproject.toml [tool.mypy] strict = true python_version = "3.11" ``` **Emerging: `ty`** — Astral's Rust-based type checker (same toolchain as uv + ruff), dramatically faster than mypy. Still in preview (pre-1.0), so mypy or pyright remain the production default — but worth watching, and easy to try: `uvx ty check`. Adopt for new projects once it stabilizes. ## Additional Resources - `./references/generics-advanced.md` - TypeVar, ParamSpec, TypeVarTuple - `./references/protocols-patterns.md` - Structural typing, runtime protocols - `./references/type-narrowing.md` - Guards, isinstance, assert - `./references/mypy-config.md` - mypy/pyright configuration - `./references/runtime-validation.md` - Pydantic v2, typeguard, beartype - `./references/overloads.md` - @overload decorator patterns ## Scripts - `./scripts/check-types.sh` - Run type checkers with common options ## Assets - `./assets/pyproject-typing.toml` - Recommended mypy/pyright config --- ## See Also This is a **foundation skill** with no prerequisites. **Related Skills:** - `python-pytest-ops` - Type-safe fixtures and mocking **Build on this skill:** - `python-async-ops` - Async type annotations - `python-fastapi-ops` - Pydantic models and validation - `python-database-ops` - SQLAlchemy type annotations
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.