mypy.ini

# =============================================================================
# Mypy Configuration
# https://mypy.readthedocs.io/
# =============================================================================
#
# This file is portable - copy to other repos without modification.
#
# Mypy is a static type checker for Python. It analyzes your code without
# running it to find type errors, missing return statements, and other bugs.
#
# Usage:
#   poetry run mypy src/           # Check src/ directory
#   poetry run mypy src/ --strict  # Strict mode (override config)
#   poetry run mypy src/ --show-error-codes  # Show error codes
#   poetry run mypy src/ --ignore-missing-imports  # Ignore untyped libs
#
# Common error codes:
#   [arg-type]      Wrong argument type
#   [return-value]  Wrong return type
#   [attr-defined]  Attribute not defined
#   [name-defined]  Name not defined
#   [import]        Import error
#   [override]      Incompatible override
#
# =============================================================================


# =============================================================================
# Global Settings
# =============================================================================

[mypy]

# Target Python version for type checking
# Use minimum supported version (3.12) for broadest compatibility
python_version = 3.12

# Paths to search for imports (src layout)
mypy_path = src

# Support PEP 420 namespace packages
namespace_packages = True

# Treat each directory as a package root
explicit_package_bases = True

# Files/directories to check
files = src/


# =============================================================================
# Dynamic Typing Rules
# =============================================================================
#
# These settings control how strict mypy is about dynamic typing (Any).
# Relaxed for Django compatibility - Django uses dynamic patterns.
#
# =============================================================================

# Don't require type annotations for unimported types
disallow_any_unimported = False

# Allow Any in expressions (Django querysets, etc.)
disallow_any_expr = False

# Allow decorated functions to have Any types
disallow_any_decorated = False

# Allow explicit Any type annotations
disallow_any_explicit = False

# Allow generic types without parameters (list vs list[str])
disallow_any_generics = False

# Allow subclassing Any
disallow_subclassing_any = False


# =============================================================================
# Untyped Definitions
# =============================================================================
#
# Controls strictness for functions without type annotations.
# Relaxed to allow gradual typing adoption.
#
# =============================================================================

# Allow calling untyped functions
disallow_untyped_calls = False

# Allow defining functions without type annotations
disallow_untyped_defs = False

# Allow partial type annotations (some args typed, some not)
disallow_incomplete_defs = False

# Still check bodies of untyped functions
check_untyped_defs = True

# Allow untyped decorators
disallow_untyped_decorators = False


# =============================================================================
# None and Optional Handling
# =============================================================================

# Don't allow implicit Optional (def f(x: int = None) → must be Optional[int])
no_implicit_optional = True

# Enable strict None checking
strict_optional = True


# =============================================================================
# Warnings
# =============================================================================

# Warn about redundant casts
warn_redundant_casts = True

# Warn about unused # type: ignore comments
warn_unused_ignores = True

# Warn about missing return statements
warn_no_return = True

# Warn when returning Any from typed function (noisy with Django)
warn_return_any = False

# Warn about unreachable code
warn_unreachable = True


# =============================================================================
# Strictness Flags
# =============================================================================

# Don't allow untyped global variables
allow_untyped_globals = False

# Don't allow redefining variables with different types
allow_redefinition = False

# Require complete type info for local variables
local_partial_types = False

# Allow implicit re-exports from __init__.py
implicit_reexport = True

# Strict equality checks (no comparing incompatible types)
strict_equality = True

# Strict concatenate checking for ParamSpec
strict_concatenate = True


# =============================================================================
# Error Output
# =============================================================================

# Show context around errors
show_error_context = True

# Show column numbers in errors
show_column_numbers = True

# Show error codes like [arg-type] in messages
show_error_codes = True

# Pretty-print error messages
pretty = True

# Colorize output
color_output = True

# Show error summary at end
error_summary = True


# =============================================================================
# Performance
# =============================================================================

# Enable incremental checking (faster subsequent runs)
incremental = True

# Cache directory for incremental checking
cache_dir = .mypy_cache


# =============================================================================
# Import Handling
# =============================================================================

# How to handle imports: normal, silent, skip, error
follow_imports = normal

# Ignore missing type stubs for external libraries (global default)
ignore_missing_imports = True

# Warn about unused config sections
warn_unused_configs = True


# =============================================================================
# Exclusions
# =============================================================================
#
# Patterns to exclude from type checking.
# Uses Python regex with (?x) verbose mode.
#
# =============================================================================

exclude = (?x)(
    migrations/
    | __pycache__/
    | \.venv/
    | build/
    | dist/
    | \.tox/
    | node_modules/
    | bup/
    | wip/
  )


# =============================================================================
# Django Plugin
# =============================================================================
#
# django-stubs provides type stubs for Django.
# Install: poetry add django-stubs --group dev
#
# =============================================================================

plugins = mypy_django_plugin.main

[mypy.plugins.django-stubs]
django_settings_module = tst.settings


# =============================================================================
# Per-Module Overrides: Project Code
# =============================================================================
#
# Stricter settings for our own code vs third-party libraries.
#
# =============================================================================

# Our package - require proper imports
[mypy-swing.*]
ignore_missing_imports = False

# Test files - relaxed (test code is often less strictly typed)
[mypy-tst.*]
ignore_errors = True
disable_error_code = attr-defined

[mypy-tests.*]
ignore_errors = True

# Development/backup directories - ignore completely
[mypy-bup.*]
ignore_errors = True

[mypy-wip.*]
ignore_errors = True

# Django migrations - auto-generated, ignore
[mypy-migrations.*]
ignore_errors = True

# Setup files
[mypy-setup]
ignore_errors = True


# =============================================================================
# Per-Module Overrides: Third-Party Libraries
# =============================================================================
#
# Libraries without type stubs or with incomplete stubs.
# Add libraries here as needed when mypy complains about missing stubs.
#
# =============================================================================

# Django and extensions
[mypy-django.*]
ignore_missing_imports = True

[mypy-rest_framework.*]
ignore_missing_imports = True

# Async/task queues
[mypy-celery.*]
ignore_missing_imports = True

[mypy-channels.*]
ignore_missing_imports = True

# Data stores
[mypy-redis.*]
ignore_missing_imports = True

# Image processing
[mypy-PIL.*]
ignore_missing_imports = True

# GraphQL
[mypy-graphene.*]
ignore_missing_imports = True

[mypy-strawberry.*]
ignore_missing_imports = True