Basedpyright Type Checking

Basedpyright Type Checking

Basedpyright is a fork of Pyright with additional features and stricter defaults, designed for maximum type safety and performance.

When to Use This Skill

Installation

Via uv (Recommended)

# Install globally
uv tool install basedpyright

# Install as dev dependency
uv add --dev basedpyright

# Run with uv
uv run basedpyright

Via pipx

pipx install basedpyright

Basic Usage

# Check entire project
basedpyright

# Check specific files/directories
basedpyright src/ tests/

# Watch mode for development
basedpyright --watch

# Output JSON for tooling integration
basedpyright --outputjson

# Verbose diagnostics
basedpyright --verbose

Configuration

Minimal Strict Configuration (pyproject.toml)

[tool.basedpyright]
typeCheckingMode = "strict"
pythonVersion = "3.12"
include = ["src"]
exclude = ["**/__pycache__", "**/.venv"]

# Basedpyright-specific strict rules
reportUnusedCallResult = "error"
reportImplicitStringConcatenation = "error"
reportMissingSuperCall = "error"
reportUninitializedInstanceVariable = "error"

Type Checking Modes

Progressive Type Checking

# Start with basic mode
[tool.basedpyright]
typeCheckingMode = "basic"
include = ["src/new_module"]  # Type check new code only

# Gradually expand
include = ["src/new_module", "src/api"]

# Eventually enable strict mode
typeCheckingMode = "strict"
include = ["src"]

Choosing a Type Checker

Choose Basedpyright for maximum type safety with stricter defaults and fastest speed. Choose Pyright for Microsoft's official support and VS Code Pylance compatibility. Choose mypy for extensive plugin ecosystem (django-stubs, pydantic-mypy).

Inline Error Suppression

# Inline type ignore
result = unsafe_operation()  # type: ignore[reportUnknownVariableType]

# Function-level ignore
def legacy_function():  # basedpyright: ignore
    pass

Agentic Optimizations

Quick Reference

For detailed configuration options, LSP integration, migration guides, CI setup, and best practices, see REFERENCE.md.

Basedpyright Type Checking - Reference

Detailed reference material for basedpyright type checking configuration and patterns.

Full pyproject.toml Configuration

[tool.basedpyright]
# Type checking mode (off, basic, standard, strict, all)
typeCheckingMode = "strict"

# Python version and platform
pythonVersion = "3.12"
pythonPlatform = "All"

# Execution environments for multi-environment projects
executionEnvironments = [
  { root = "src", pythonVersion = "3.12" },
  { root = "tests", extraPaths = ["src"] }
]

# Strict type checking rules (enabled in strict mode)
strictListInference = true
strictDictionaryInference = true
strictSetInference = true
strictParameterNoneValue = true

# Additional strict rules (beyond standard Pyright)
reportUnusedCallResult = "error"
reportImplicitStringConcatenation = "error"
reportMissingSuperCall = "error"
reportUninitializedInstanceVariable = "error"

# Standard type checking rules
reportMissingImports = "error"
reportMissingTypeStubs = "warning"
reportUnusedImport = "error"
reportUnusedClass = "warning"
reportUnusedFunction = "warning"
reportUnusedVariable = "error"
reportDuplicateImport = "error"
reportOptionalSubscript = "error"
reportOptionalMemberAccess = "error"
reportOptionalCall = "error"
reportOptionalIterable = "error"
reportOptionalContextManager = "error"
reportOptionalOperand = "error"
reportTypedDictNotRequiredAccess = "warning"
reportPrivateImportUsage = "error"
reportConstantRedefinition = "error"
reportIncompatibleMethodOverride = "error"
reportIncompatibleVariableOverride = "error"
reportInconsistentConstructor = "error"
reportOverlappingOverload = "error"
reportMissingSuperCall = "warning"
reportUninitializedInstanceVariable = "warning"
reportInvalidStringEscapeSequence = "error"
reportUnknownParameterType = "warning"
reportUnknownArgumentType = "warning"
reportUnknownLambdaType = "warning"
reportUnknownVariableType = "warning"
reportUnknownMemberType = "warning"
reportMissingParameterType = "error"
reportMissingTypeArgument = "error"
reportInvalidTypeVarUse = "error"
reportCallInDefaultInitializer = "warning"
reportUnnecessaryIsInstance = "warning"
reportUnnecessaryCast = "warning"
reportUnnecessaryComparison = "warning"
reportAssertAlwaysTrue = "error"
reportSelfClsParameterName = "error"
reportImplicitStringConcatenation = "warning"
reportUndefinedVariable = "error"
reportUnboundVariable = "error"
reportInvalidStubStatement = "error"
reportIncompleteStub = "warning"
reportUnsupportedDunderAll = "error"
reportUnusedCoroutine = "error"

# Include/exclude patterns
include = ["src", "tests"]
exclude = [
  "**/__pycache__",
  "**/.venv",
  "**/.git",
  "**/node_modules",
  "**/.mypy_cache",
  "**/.pytest_cache"
]

# Stub search paths
stubPath = "typings"

# Virtual environment detection
venvPath = "."
venv = ".venv"

LSP Integration

Neovim with nvim-lspconfig

-- Using mason.nvim
require("mason").setup()
require("mason-lspconfig").setup({
  ensure_installed = { "basedpyright" }
})

-- Direct configuration
require("lspconfig").basedpyright.setup({
  settings = {
    basedpyright = {
      analysis = {
        typeCheckingMode = "strict",
        diagnosticMode = "workspace",
        autoSearchPaths = true,
        useLibraryCodeForTypes = true,
        diagnosticSeverityOverrides = {
          reportUnusedCallResult = "error",
          reportImplicitStringConcatenation = "error",
        }
      }
    }
  }
})

VS Code Settings

{
  "basedpyright.analysis.typeCheckingMode": "strict",
  "basedpyright.analysis.diagnosticMode": "workspace",
  "basedpyright.analysis.autoSearchPaths": true,
  "basedpyright.analysis.useLibraryCodeForTypes": true,
  "basedpyright.analysis.diagnosticSeverityOverrides": {
    "reportUnusedCallResult": "error",
    "reportImplicitStringConcatenation": "error"
  }
}

Language Server Protocol

# Start LSP server
basedpyright-langserver --stdio

# Used by editors for:
# - Real-time type checking
# - Auto-completion with type hints
# - Go to definition
# - Find references
# - Rename symbols
# - Quick fixes

Basedpyright vs Pyright vs mypy

Feature Comparison

When to Choose Basedpyright

Choose Basedpyright when:

• You want maximum type safety with stricter defaults
• You need the fastest type checker available
• You're starting a new project with strict typing requirements
• You want additional strictness rules beyond standard Pyright
• You prefer opinionated defaults over extensive configuration
• You need LSP integration with enhanced diagnostics

Choose Pyright when:

• You need Microsoft's official support and stability
• You want standard type checking without extra strictness
• Your team prefers industry-standard tooling
• You need compatibility with VS Code Pylance

Choose mypy when:

• You need extensive plugin ecosystem
• You have legacy code with mypy configuration
• You require specific mypy plugins (e.g., django-stubs, pydantic-mypy)
• You need fine-grained control over type checking behavior
• Your team has mypy expertise

Migration from Pyright

# Existing pyproject.toml with [tool.pyright]
[tool.pyright]
typeCheckingMode = "strict"
include = ["src"]

# Change to [tool.basedpyright] - same configuration
[tool.basedpyright]
typeCheckingMode = "strict"
include = ["src"]

# Add basedpyright-specific rules
reportUnusedCallResult = "error"
reportImplicitStringConcatenation = "error"

Migration from mypy

# From mypy.ini or [tool.mypy]
[tool.mypy]
strict = true
warn_unused_ignores = true
warn_redundant_casts = true

# To basedpyright
[tool.basedpyright]
typeCheckingMode = "strict"
reportUnnecessaryCast = "warning"
# Note: Some mypy-specific options don't have direct equivalents

Advanced Patterns

Multiple Execution Environments

[tool.basedpyright]
executionEnvironments = [
  # Main source code
  { root = "src", pythonVersion = "3.12", extraPaths = [] },

  # Tests with access to src
  { root = "tests", pythonVersion = "3.12", extraPaths = ["src"] },

  # Scripts with different requirements
  { root = "scripts", pythonVersion = "3.11", extraPaths = ["src"] }
]

Custom Type Stubs

[tool.basedpyright]
stubPath = "typings"  # Directory for custom .pyi files

# Directory structure:
# typings/
#   third_party_lib/
#     __init__.pyi
#     module.pyi

Ignore Specific Errors

# Inline type ignore
result = unsafe_operation()  # type: ignore[reportUnknownVariableType]

# File-level ignore
# basedpyright: ignore[reportMissingImports]

# Function-level ignore
def legacy_function():  # basedpyright: ignore
    # No type checking in this function
    pass

Type Checking Specific Files Only

[tool.basedpyright]
# Strict checking for new code only
include = [
  "src/api/**/*.py",
  "src/models/**/*.py",
  "!src/legacy/**/*.py"  # Exclude legacy code
]

CI Integration

GitHub Actions

name: Type Check

on: [push, pull_request]

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v2
        with:
          enable-cache: true

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --all-extras --dev

      - name: Run basedpyright
        run: uv run basedpyright

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/DetachHead/basedpyright
    rev: v1.18.3
    hooks:
      - id: basedpyright
        additional_dependencies: []  # Add runtime dependencies if needed

Make/Just Task

# Makefile
.PHONY: typecheck
typecheck:
	uv run basedpyright

# With JSON output for CI parsing
.PHONY: typecheck-ci
typecheck-ci:
	uv run basedpyright --outputjson > typecheck-results.json

Best Practices

1. Start Strict Early

# New projects: Start with strict mode
[tool.basedpyright]
typeCheckingMode = "strict"
include = ["src"]

2. Progressive Type Coverage

# Generate baseline of current issues
basedpyright --outputjson > baseline.json

# Fix issues incrementally
# Use reportUnknownMemberType = "warning" initially
# Upgrade to "error" when resolved

3. Type Annotations First

# Always provide type hints for public APIs
def process_data(
    items: list[dict[str, Any]],
    config: Config | None = None
) -> ProcessedResult:
    """Process data with optional configuration."""
    ...

# Use Protocol for structural typing
from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> None: ...

def render(obj: Drawable) -> None:  # Accepts any type with draw()
    obj.draw()

4. Leverage Type Narrowing

from typing import assert_type

def process_optional(value: str | None) -> str:
    if value is None:
        return "default"

    # Type narrowed to str
    assert_type(value, str)  # Compile-time type assertion
    return value.upper()

5. Use TypedDict for Structured Data

from typing import TypedDict, NotRequired

class UserData(TypedDict):
    id: int
    name: str
    email: str
    age: NotRequired[int]  # Optional field

def create_user(data: UserData) -> User:
    # Type-safe dictionary access
    return User(
        id=data["id"],
        name=data["name"],
        email=data["email"],
        age=data.get("age")
    )

6. Monitor Type Coverage

# Check type coverage percentage
basedpyright --verbose | grep "completion"

# Goal: Aim for 95%+ type annotation coverage

Common Issues and Solutions

Issue: Too Many False Positives

# Solution: Adjust diagnostic severity
[tool.basedpyright]
reportUnknownMemberType = "warning"  # Downgrade from error
reportUnknownArgumentType = "warning"

Issue: Third-Party Library Without Stubs

# Solution: Install type stubs
uv add --dev types-requests types-pyyaml

# Or create custom stubs in typings/

Issue: Performance on Large Codebases

# Solution: Limit scope or use include patterns
[tool.basedpyright]
include = ["src/core", "src/api"]  # Check subset
exclude = ["src/legacy", "**/*_test.py"]  # Skip tests initially

Issue: Conflicts with Runtime Behavior

# Solution: Use TYPE_CHECKING for type-only imports
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from expensive_module import LargeType

def process(data: "LargeType") -> None:  # String annotation
    # Runtime code doesn't import expensive_module
    ...

Resources

• Official Repository: https://github.com/DetachHead/basedpyright
• Pyright Documentation: https://microsoft.github.io/pyright/ (most rules apply)
• Type Hints PEPs: PEP 484, 526, 544, 585, 604, 612, 613
• Python Type System: https://typing.readthedocs.io/