home / skills / pluginagentmarketplace / custom-plugin-python / type-hints

type-hints skill

safe

This skill helps you master Python type hints and mypy checks to improve code quality, IDE support, and static analysis.

npx playbooks add skill pluginagentmarketplace/custom-plugin-python --skill type-hints

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

1.3 KB

---
name: Type Hints
description: Python type hints, type checking, and static analysis with mypy
version: "2.1.0"
sasmp_version: "1.3.0"
bonded_agent: 07-best-practices
bond_type: PRIMARY_BOND

# Skill Configuration
retry_strategy: exponential_backoff
observability:
  logging: true
  metrics: type_coverage_percent
---

# Python Type Hints Skill

## Overview
Master Python type hints for better code quality, IDE support, and static type checking with mypy.

## Topics Covered

### Basic Type Hints
- Variable annotations
- Function signatures
- Return types
- Optional types
- Union types

### Advanced Typing
- Generic types
- TypeVar and ParamSpec
- Protocol and structural typing
- Literal types
- TypedDict

### Type Checking
- mypy configuration
- Strict mode settings
- Type ignore comments
- Stub files (.pyi)
- Type coverage

### Runtime Types
- typing_extensions
- Pydantic validation
- Runtime type checking
- Dataclasses with types
- attrs integration

### Best Practices
- Gradual typing strategy
- Third-party type stubs
- CI type checking
- Documentation with types
- Type-driven development

## Prerequisites
- Python fundamentals
- OOP concepts

## Learning Outcomes
- Write type-annotated code
- Configure mypy properly
- Use generic types
- Implement protocols

Overview

This skill teaches practical Python type hints, static analysis, and mypy configuration to improve code reliability and developer experience. It covers basic and advanced typing constructs, runtime typing tools, and workflows for gradual adoption. You will learn how to write annotations that enable better IDE support, clearer APIs, and fewer runtime errors.

How this skill works

The skill inspects code patterns and explains appropriate type annotations for variables, functions, and classes. It demonstrates configuring and running mypy, interpreting its output, and using type stubs and ignore directives when needed. It also shows how to combine static typing with runtime validators and dataclass/attrs patterns for robust validation.

When to use it

When you want stronger guarantees and earlier detection of bugs in Python code.
When onboarding teams that need consistent API contracts and clearer interfaces.
When integrating third-party libraries and you need or provide type stubs (.pyi).
When improving IDE completions and refactor safety across a codebase.
When adopting gradual typing to incrementally improve legacy code.

Best practices

Start with function signatures and public APIs before annotating every local variable.
Use mypy strict settings gradually; add per-module overrides while improving coverage.
Prefer typing.Protocol for structural interfaces over ad-hoc duck typing when possible.
Adopt TypeVar and generics for reusable container and algorithm code.
Keep runtime validation (Pydantic or custom checks) for security-critical inputs.

Example use cases

Annotating a web service layer so request/response shapes are explicit and validated.
Adding generics to a utilities library to make functions type-safe across types.
Configuring CI to run mypy and enforce a minimum type coverage threshold.
Creating .pyi stubs for a C-extension or untyped third-party package.
Combining dataclasses with types and Pydantic models for validation plus static checks.

FAQ

Do type hints affect runtime performance?

Type hints are ignored at runtime by default and incur no performance cost; runtime validators or libraries that enforce types can add overhead.

When should I use typing_extensions?

Use typing_extensions to access newer typing features on older Python versions until they become part of the standard typing module.