Python typing

Skill bitwise-media-group/skills/plugins/python/skills/python-typing

Coding agent marketplace for skills used by the BitWise Media Group.

Install

npx -y skills add bitwise-media-group/skills --skill python-typing

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Python static typing and type annotations, checked with a static type checker — ty (Astral) or pyright (Microsoft/Pylance). Use when adding, writing, or reviewing type hints or annotations on Python functions, methods, parameters, or return values; adding return type annotations across a module; fixing or resolving Python type errors; making a function or class generic with a type parameter; modernizing hints to X | None instead of Optional, A | B instead of Union, and built-in list[]/dict[] generics; choosing between Protocol and ABC for an interface or using typing.Self and PEP 695 syntax; or setting up, configuring, or running ty or pyright under [tool.ty] or [tool.pyright] in pyproject.toml, migrating from mypy, and wiring a type-check step into the dev gate or CI. For Python code only — not TypeScript, Go, or other languages, not runtime isinstance checks, formatting, or test-writing.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.8 KB, as published. Nobody here has run it

Python typing conventions

A static type checker is the type gate for the project: either ty (Astral's fast checker and language server) or pyright (Microsoft's checker, the engine behind Pylance) — pick whichever the project already uses. Type the public surface, keep the type check clean, and write modern annotation syntax. ty is pre-1.0, so expect its diagnostics and config to move. For deeper edge cases see reference.md.

1. Annotate the public surface

Every public function, method, and module-level constant gets parameter and return annotations — that is the contract the checker enforces and editors surface. Annotate internal locals only where the type is not obvious from the right-hand side. Avoid Any (it disables checking — prefer object, a Protocol, or a type variable) and use # type: ignore[rule-code] with a specific code, sparingly, never a bare blanket ignore.

2. Configure and run a type checker

Both checkers configure in pyproject.toml and run through uv. Use one — wire its check into make typecheck and CI.

ty reads [tool.ty]. The minimal config sets the version floor and the src root; tune individual diagnostics under [tool.ty.rules]:

[tool.ty.environment]
python-version = "3.13"
root = ["./src"]

[tool.ty.rules]
possibly-unresolved-reference = "warn"   # severities: "ignore" | "warn" | "error"

uv run ty check            # type-check the project (wire into `make typecheck` + CI)
uv run ty server           # the LSP language server, for editor integration

pyright reads [tool.pyright] (or a standalone pyrightconfig.json, which takes precedence if present). Set the checked paths and the interpreter version; typeCheckingMode selects strictness ("basic" | "standard" | "strict", default "standard"):

[tool.pyright]
include = ["src"]
pythonVersion = "3.13"
typeCheckingMode = "standard"

uv add --dev pyright       # pin it in the dev dependency group
uv run pyright             # type-check the project (or `uvx pyright` for a one-off run)

3. Write modern annotation syntax

X | None, not Optional[X]; A | B, not Union. Built-in generics (list[int], dict[str, int]) — never the deprecated typing.List/Dict. The ruff UP rules (see python-style) rewrite the old forms.

PEP 695 type parameters and aliases (3.12+) instead of TypeVar/TypeAlias:

def first[T](items: list[T]) -> T: ...

class Box[T]:
    def __init__(self, value: T) -> None:
        self.value = value

type Vector = list[float]

typing.Self for fluent/factory methods that return their own type; @override (3.12+) on methods that override a base, so the checker catches signature drift.

4. Prefer Protocol over ABC for interfaces

Structural typing keeps the interface at the consumer (the analogue of Go's consumer-defined interfaces) — no base class to inherit, and any object with the right shape satisfies it:

from typing import Protocol

class Reader(Protocol):
    def read(self, size: int) -> bytes: ...

Reserve abc.ABC for when you need shared implementation or runtime isinstance enforcement.

5. Deferred annotations

Default to from __future__ import annotations at the top of each module: annotations become strings, so forward references need no quotes, import cycles used only for typing disappear, and there is no runtime cost. Guard typing-only imports behind if TYPE_CHECKING:. The exception is code that introspects annotations at runtime (some serializers/validators) — see reference.md.

For runtime data validation reach for a model library; plain annotations are not checked at runtime. For style and the ruff UP rules see the python-style skill; for typing test doubles see python-testing; for the make typecheck target and CI wiring see python-project and python-release.