pyright

pyright Best Practices

pyright is the definitive static type-checker for modern Python, essential for "type-first" development. We standardize on basedpyright for its stricter defaults and enhanced diagnostics, ensuring our codebase remains consistently type-clean.

1. Project-Wide Configuration

Always define a pyrightconfig.json (or [tool.pyright] in pyproject.toml) at your project root. Commit this file to version control to guarantee consistent type-checking across all developer environments and CI pipelines. Start with a baseline, fix errors, then progressively tighten rules.

❌ BAD: No config file, relying on default pyright behavior. ✅ GOOD: Explicitly define your type-checking rules.

// pyrightconfig.json
{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__"],
  "reportMissingTypeStubs": "error",
  "reportAny": "error", // basedpyright specific, essential
  "reportExplicitAny": "error", // basedpyright specific, essential
  "reportImplicitRelativeImport": "error", // basedpyright specific
  "reportInvalidCast": "error", // basedpyright specific
  "reportUnsafeMultipleInheritance": "error", // basedpyright specific
  "strict": [ // Apply strict mode to specific directories
    "src/core",
    "src/models"
  ],
  "stubPath": "stubs" // Where custom type stubs live
}

2. Strict Diagnostics & Any Usage

Embrace strict diagnostics to eliminate implicit Any types and enforce explicit type declarations. basedpyright's reportAny and reportExplicitAny are non-negotiable for maintaining a truly type-safe codebase.

Prefer object over Any

Use object when a function truly accepts any Python object, but its type isn't relevant to its operation (e.g., for str(), repr(), or passing to a callback that ignores its argument). Reserve Any only when the type system cannot express the intent.

❌ BAD: Overusing Any, disabling type checks.

from typing import Any

def process_data(data: Any) -> Any: # Type checking effectively disabled
    print(str(data))
    return data