Claude Skill

python-typing-ops

Python type hints and type safety patterns. Triggers on: type hints, typing, TypeVar, Generic, Protocol, mypy, pyright, type annotation, overload, TypedDict.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download 0xdarkmatter-claude-mods-skills_python-typing-ops-3dfaf0b.zip · 17 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/python-typing-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git 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 annotations
  • python-fastapi-ops - Pydantic models and validation
  • python-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.

No comments yet.

Reviews (0)

No reviews yet.