# Justfile Reference

`just` is a command runner for project-specific recipes. Replaces Makefile for non-build tasks.

**Manual**: https://just.systems/man/en/ | **GitHub**: https://github.com/casey/just

## Installation

```bash
brew install just       # macOS
cargo install just      # Via Rust
```

## Core Syntax

```just
# This comment shows in `just --list`
recipe-name:
    command1
    command2
```

Each line runs in a **separate shell** by default. Use `&&` to chain commands in one shell.

Suppress command echoing with `@`:

```just
@hello:
    echo "Hello"
# Output: Hello (not: echo "Hello" \n Hello)
```

## Variables

```just
# Simple assignment
version := "1.0.0"

# Backtick (evaluated at parse time)
git_hash := `git rev-parse --short HEAD`

# Environment variable with default
port := env("PORT", "8000")

# Use in recipes
build:
    @echo "Building {{version}} ({{git_hash}})"
```

## Parameters

```just
# Required
build target:
    @echo "Building {{target}}"

# With default
test suite="unit":
    @echo "Running {{suite}} tests"

# Variadic (one or more)
backup +FILES:
    scp {{FILES}} server:

# Variadic (zero or more)
commit MESSAGE *FLAGS:
    git commit {{FLAGS}} -m "{{MESSAGE}}"

# Exported as env var
serve $PORT="8000":
    python -m http.server $PORT
```

## Dependencies

```just
# Run before (prior dependency)
build:
    @echo "Building..."

test: build
    @echo "Testing..."

# Run after (subsequent dependency)
deploy: build && notify cleanup
    @echo "Deploying..."

# With arguments
default: (test "unit")

test suite:
    @echo "Running {{suite}} tests"
```

## Settings

```just
# Load .env file
set dotenv-load

# Export all variables as env vars
set export

# Suppress command echoing globally
set quiet

# Use bash
set shell := ["bash", "-uc"]
```

## Recipe Attributes

```just
# Group in `just --list`
[group('testing')]
test:
    uv run pytest

[group('quality')]
check:
    uv run ty check

# Require confirmation
[confirm("Reset database?")]
db-reset:
    dropdb myapp && createdb myapp

# Platform-specific
[linux]
install:
    sudo apt install libfoo-dev

[macos]
install:
    brew install libfoo

# Private (hidden from list)
[private]
_helper:
    echo "internal"

# Documentation override
[doc("Run type checking and linting")]
check:
    uv run ty check
    uv run ruff check
    uv run ruff format --check
```

## Shebang Recipes

For multi-line scripts in any language:

```just
analyze:
    #!/usr/bin/env python3
    import json
    with open("data.json") as f:
        data = json.load(f)
    print(f"Found {len(data)} records")

# With uv inline script deps
check-api:
    #!/usr/bin/env -S uv run --script
    # /// script
    # dependencies = ["httpx"]
    # ///
    import httpx
    r = httpx.get("https://api.example.com/health")
    print(f"Status: {r.status_code}")

# Bash with strict mode
deploy:
    #!/usr/bin/env -S bash -euo pipefail
    echo "Deploying..."
    git push origin main
```

Use `#!/usr/bin/env -S` with `-S` flag when passing arguments to the interpreter.

## Conditional Logic

```just
# Conditional assignment
os := if os() == "macos" { "darwin" } else { "linux" }

# Conditional in recipe
test:
    uv run pytest {{ if env("CI", "") != "" { "--no-header -q" } else { "-v" } }}
```

## Built-in Functions

| Function | Returns |
|----------|---------|
| `os()` | "linux", "macos", "windows" |
| `arch()` | "x86_64", "aarch64" |
| `env("VAR", "default")` | Environment variable |
| `justfile()` | Path to current Justfile |
| `justfile_directory()` | Directory of Justfile |
| `invocation_directory()` | Where `just` was called from |
| `uuid()` | Random UUID |

## Python Project Justfile Template

```just
set dotenv-load
set quiet

# Run type checking and linting
[group('quality')]
check:
    uv run ty check
    uv run ruff check
    uv run ruff format --check

# Run tests
[group('testing')]
test *ARGS:
    uv run pytest {{ARGS}}

# Run tests with coverage
[group('testing')]
test-cov:
    uv run pytest --cov=src --cov-report=term-missing

# Auto-fix and format
[group('quality')]
fix:
    uv run ruff check --fix
    uv run ruff format

# Install all dependencies and git hooks
[group('dev')]
install:
    uv sync --all-groups
    uv run lefthook install

# Update all dependencies
[group('dev')]
update:
    uv lock --upgrade
    uv sync --all-groups

# Build the package
[group('build')]
build:
    uv build

# Clean build artifacts
[group('dev')]
clean:
    rm -rf dist/ build/ .pytest_cache/ .ruff_cache/ htmlcov/
    find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

# Open Python REPL
[group('dev')]
repl:
    uv run python
```

## Running

```bash
just              # Default recipe (first one, or [default])
just test         # Named recipe
just test -x -v   # Pass args through
just --list       # List all recipes (grouped)
just -l           # Short form
just --choose     # Interactive (needs fzf)
just --summary    # One-line summary
just -n test      # Dry run (show what would run)
```

# pytest Reference

Modern Python testing with pytest and key plugins.

**Docs**: https://docs.pytest.org/en/stable/ | **GitHub**: https://github.com/pytest-dev/pytest | **Tracked line**: pytest 9.x

> **Heads up (8 -> 9)**: pytest 9.0 adds native `[tool.pytest]` TOML configuration (alongside the still-supported `[tool.pytest.ini_options]`), built-in subtests, and stricter mode. It drops Python 3.9 and turns previously-deprecated behaviours into errors. pytest 8.4 already failed (instead of warn-skipping) async tests without an asyncio plugin and made `yield` in tests an error. pytest 9.0.3 fixes CVE-2025-71176 in temp-directory creation - upgrade if you are on 9.0.0/9.0.1/9.0.2.

## Installation

```bash
uv add --dev pytest pytest-asyncio pytest-cov pytest-mock
```

## Running Tests

```bash
uv run pytest                          # Run all tests
uv run pytest tests/test_models.py     # Specific file
uv run pytest tests/test_models.py::test_create  # Specific test
uv run pytest -x                       # Stop on first failure
uv run pytest -x --pdb                 # Drop into debugger on failure
uv run pytest -k "test_user"           # Match test names
uv run pytest -m "not slow"            # Skip marked tests
uv run pytest -v                       # Verbose output
uv run pytest --tb=short               # Short tracebacks
uv run pytest -n auto                  # Parallel (needs pytest-xdist)
```

## pyproject.toml Configuration

```toml
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
asyncio_mode = "auto"                  # pytest-asyncio: auto-detect async tests
# pytest 9.0 silently ignored --strict-markers/--strict-config given via addopts.
# The ini keys work on 9.0 and 9.1 alike; `strict` is the shorthand for all four
# strictness axes (config, markers, xfail, parametrization ids).
strict = true
addopts = ["-ra"]                      # Show summary for all non-passing tests

markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "integration: integration tests",
]

filterwarnings = [
    "error",                           # Treat warnings as errors
    "ignore::DeprecationWarning:some_lib",  # Selectively ignore
]
```

### Coverage Config

```toml
[tool.coverage.run]
source = ["src"]
branch = true
omit = ["*/tests/*", "*/__pycache__/*"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
]
fail_under = 80
```

## Key Plugins

### pytest-asyncio (1.0+)

With `asyncio_mode = "auto"` in config, no decorators needed:

```python
# Async tests - just write async def
async def test_fetch_data():
    result = await my_async_function()
    assert result == expected

# Async fixtures
@pytest.fixture
async def async_client():
    async with SomeAsyncClient() as client:
        yield client

# For a custom event loop (e.g. uvloop), pytest-asyncio 1.4+
# conftest.py - maps factory names to loop factories
import uvloop


def pytest_asyncio_loop_factories(config, item):
    return {
        "uvloop": uvloop.new_event_loop,
    }
```

Select one per test with `@pytest.mark.asyncio(loop_factories=["uvloop"])`.

Breaking changes in 1.0: the `event_loop` fixture was removed - use `asyncio.get_running_loop()`
inside tests. 1.3 dropped Python 3.9 and added pytest 9 compatibility. **1.4.0 deprecated
overriding the `event_loop_policy` fixture** in favour of the hook above, and raised the minimum
pytest to 8.4.0. The deprecation is downstream of CPython: `asyncio.AbstractEventLoopPolicy` is
deprecated as of Python 3.14 (removal planned for 3.16), and `uvloop.EventLoopPolicy` goes with
it - so the old fixture form is on a clock, not merely out of fashion.

### pytest-cov

```bash
uv run pytest --cov=src --cov-report=term-missing
uv run pytest --cov=src --cov-report=html     # HTML report in htmlcov/
```

### pytest-mock

```python
def test_with_mock(mocker):
    mock_api = mocker.patch("myapp.services.external_api")
    mock_api.get_data.return_value = {"status": "ok"}
    result = my_function()
    mock_api.get_data.assert_called_once()
```

### pytest-xdist (Parallel)

```bash
uv add --dev pytest-xdist
uv run pytest -n auto          # Use all CPU cores
uv run pytest -n 4             # Use 4 workers
```

## Fixtures

### Scope Hierarchy

1. **function** (default) - per test
2. **class** - per test class
3. **module** - per .py file
4. **package** - per directory
5. **session** - once for entire run

### Common Patterns

```python
# Yield fixture (setup + teardown)
@pytest.fixture
def db_session(database):
    database.execute("BEGIN")
    yield database
    database.execute("ROLLBACK")

# Factory fixture
@pytest.fixture
def make_user():
    created = []
    def _make(name="test", email="[email protected]"):
        user = User(name=name, email=email)
        created.append(user)
        return user
    yield _make
    for u in created:
        u.delete()

# Parametrized fixture
@pytest.fixture(params=["sqlite", "postgres"])
def database(request):
    if request.param == "sqlite":
        return create_sqlite_db()
    return create_postgres_db()

# Session-scoped resource
@pytest.fixture(scope="session")
def app():
    app = create_app(testing=True)
    yield app
```

### Built-in Fixtures

| Fixture | Purpose |
|---------|---------|
| `tmp_path` | `pathlib.Path` to unique temp directory |
| `monkeypatch` | Modify objects/env vars (auto-reverted) |
| `capsys` | Capture stdout/stderr |
| `request` | Test metadata (params, markers, etc.) |

### monkeypatch Examples

```python
def test_env_var(monkeypatch):
    monkeypatch.setenv("APP_NAME", "test-app")
    result = get_config()
    assert result.app_name == "test-app"

def test_patched_function(monkeypatch):
    monkeypatch.setattr("myapp.services.fetch_data", lambda: {"mock": True})
    result = process()
    assert result["mock"] is True
```

## conftest.py

Fixtures in `conftest.py` are auto-discovered for all tests in the same directory and below. Never import from conftest files.

```python
# tests/conftest.py
import pytest

@pytest.fixture(scope="session")
def project_root():
    from pathlib import Path
    return Path(__file__).parent.parent

@pytest.fixture
def mock_api(monkeypatch):
    monkeypatch.setattr("myapp.api.client.fetch", lambda url: {"data": []})

# Custom CLI option
def pytest_addoption(parser):
    parser.addoption("--run-integration", action="store_true", default=False)

def pytest_collection_modifyitems(config, items):
    if not config.getoption("--run-integration"):
        skip = pytest.mark.skip(reason="need --run-integration")
        for item in items:
            if "integration" in item.keywords:
                item.add_marker(skip)
```

## Parametrize

```python
@pytest.mark.parametrize("input,expected", [
    ("hello", 5),
    ("", 0),
    ("world", 5),
])
def test_length(input, expected):
    assert len(input) == expected

# Multiple parametrize = cartesian product
@pytest.mark.parametrize("x", [1, 2])
@pytest.mark.parametrize("y", [10, 20])
def test_multiply(x, y):
    assert x * y > 0
```

## Project Structure

```
tests/
  conftest.py               # Shared fixtures
  test_models.py            # Unit tests
  test_services.py
  integration/
    conftest.py             # Integration-specific fixtures
    test_api.py
```

## Justfile Recipes

```just
test *ARGS:
    uv run pytest {{ARGS}}

test-cov:
    uv run pytest --cov=src --cov-report=term-missing

test-watch:
    uv run pytest -x --watch   # Needs pytest-watch plugin
```

# ruff Reference

Extremely fast Python linter and formatter, written in Rust. Replaces flake8, black, isort, pyupgrade.

**Docs**: https://docs.astral.sh/ruff/ | **GitHub**: https://github.com/astral-sh/ruff | **Tracked line**: ruff 0.16.x

> **Heads up**: ruff **0.16 is the big one** - the default rule set went from 59 to 413 rules, 18 opinionated `E`/`F` rules were dropped from that default set, and `ruff format` now formats Python blocks inside Markdown by default. A `select` list replaces the defaults, so prefer `extend-select`/`ignore`. 0.16 also adds line-level `ruff: ignore` comments and `--add-ignore`, and `format --check` gained the linter's `--output-format github`. Earlier: 0.14 moved the default target Python to 3.14; 0.15 shipped the 2026 formatter style guide and block-level suppressions. Pinning `target-version` in `pyproject.toml` keeps formatter output reproducible across upgrades.

## Usage

```bash
# Lint
uv run ruff check .              # Check for errors
uv run ruff check --fix .        # Auto-fix
uv run ruff check --diff .       # Show what would change

# Format
uv run ruff format .             # Format code
uv run ruff format --check .     # Check without changing

# Combined (lint + format in one go)
uv run ruff check --fix && uv run ruff format

# Info
ruff rule E501                   # Explain a rule
ruff rule --all                  # List all rules
```

## pyproject.toml Configuration

### Core Settings

```toml
[tool.ruff]
target-version = "py313"
line-length = 100
indent-width = 4

exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
    "*.egg-info",
]
```

### Lint Rules

```toml
[tool.ruff.lint]
# Ruff 0.16 enables 413 rules by default (up from 59), and dropped 18 opinionated
# E/F rules from that set. Writing a `select` list REPLACES the default set, so
# `select = ["E","F","I","UP"]` now yields a weaker linter than no config at all.
# Start from the defaults and narrow with `ignore`, or widen with `extend-select`.
ignore = [
    "E501",   # line too long - formatter handles it
    "UP007",  # X | Y unions - Optional[X] is more readable
    "UP006",  # type vs Type - both valid
]

# Allow auto-fix for all enabled rules
fixable = ["ALL"]
unfixable = []
```

### Extended Rule Sets (add when needed)

Use `extend-select`, not `select` - it adds to ruff 0.16's default set instead of replacing it.
Some of these are already on by default (a mutable-default arg raises `B006` with no config at
all), while `S`, `T20` and `ERA` are not.

```toml
[tool.ruff.lint]
extend-select = [
    "B",   # flake8-bugbear - common bugs and design problems (partly default in 0.16)
    "SIM", # flake8-simplify - simplification suggestions
    "RUF", # ruff-specific rules
    "S",   # flake8-bandit - security issues
    "PTH", # flake8-use-pathlib - prefer pathlib over os.path
    "T20", # flake8-print - no print() in production code
    "ERA", # eradicate - commented-out code detection
]
```

### Per-File Ignores

```toml
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]          # Allow unused imports
"tests/*" = ["S101"]              # Allow assert statements
"scripts/*" = ["T20"]             # Allow print() in scripts
"conftest.py" = ["F401", "F811"]  # Allow unused imports and redefined names
```

### Import Sorting

```toml
[tool.ruff.lint.isort]
known-first-party = ["my_project"]
known-third-party = ["fastapi", "pydantic"]
force-single-line = false
lines-after-imports = 2
```

### Formatter Settings

```toml
[tool.ruff.format]
quote-style = "double"        # double (default) or single
indent-style = "space"        # space (default) or tab
line-ending = "lf"            # lf, cr-lf, cr, auto, native
skip-magic-trailing-comma = false
docstring-code-format = true  # Format code in docstrings
```

## Rule Categories Reference

| Code | Name | What It Catches |
|------|------|-----------------|
| E | pycodestyle | Syntax errors, whitespace issues |
| W | pycodestyle warnings | Whitespace warnings |
| F | Pyflakes | Undefined names, unused imports, redefined names |
| I | isort | Import order and grouping |
| UP | pyupgrade | Outdated Python syntax (dict() vs {}, old-style formatting) |
| B | flake8-bugbear | Common bugs (mutable default args, except Exception) |
| SIM | flake8-simplify | Code simplification (if/else to ternary, dict.get) |
| S | flake8-bandit | Security issues (hardcoded passwords, SQL injection) |
| RUF | Ruff-specific | Ruff's own rules (unused noqa, mutable class default) |
| T20 | flake8-print | print() statements (remove for production) |
| PTH | flake8-use-pathlib | os.path vs pathlib suggestions |
| ERA | eradicate | Commented-out code |
| N | pep8-naming | Naming conventions |
| D | pydocstyle | Docstring conventions |
| ANN | flake8-annotations | Type annotation enforcement |
| C4 | flake8-comprehensions | Unnecessary list/dict/set comprehension patterns |
| PIE | flake8-pie | Miscellaneous lints |
| RET | flake8-return | Return statement issues |

## Git Hook Integration

```yaml
# lefthook.yml
pre-commit:
  piped: true
  jobs:
    - name: ruff-check
      glob: "*.{py,pyi,ipynb}"
      run: uv run ruff check --force-exclude --fix {staged_files}
      stage_fixed: true
    - name: ruff-format
      glob: "*.{py,pyi,ipynb}"
      run: uv run ruff format --force-exclude {staged_files}
      stage_fixed: true
```

`--force-exclude` is required whenever paths are passed explicitly, or `[tool.ruff] exclude`
is ignored for them. Lint before format: `--fix` output may need reformatting.

On pre-commit instead, the current hook ids are `ruff-check` and `ruff-format` - bare `ruff`
is a legacy alias - and `rev` must be kept in step with the ruff pin in `pyproject.toml`:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.16.6
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format
```

## CI/CD

```yaml
# GitHub Actions
- name: Lint
  run: uv run ruff check --output-format github .

- name: Format check
  run: uv run ruff format --check .
```

The `--output-format github` flag produces annotations that show inline in PRs.

## Editor Integration

Ruff has first-party VS Code extension and LSP. With uv projects, the extension discovers ruff from the project's virtual environment automatically.

## Suppression Comments

```python
x = 1  # noqa: E741       # Suppress specific rule
x = 1  # noqa              # Suppress all rules on this line

# ruff: noqa: E741         # Suppress rule for entire file (top of file)
```

Clean up stale suppressions:
```bash
uv run ruff check --extend-select RUF100  # Flag unused noqa comments
```

## Migration from Other Tools

### From black
Ruff format is compatible with black. Remove black, add ruff format config:
```toml
[tool.ruff.format]
quote-style = "double"    # black default
```

### From flake8
Map flake8 rules to ruff equivalents. Most common: `E`, `W`, `F` codes are identical.

### From isort
Ruff `I` rules replace isort. Config maps:
- `known_first_party` -> `[tool.ruff.lint.isort] known-first-party`
- `known_third_party` -> `[tool.ruff.lint.isort] known-third-party`

## Troubleshooting

```bash
ruff clean                        # Clear cache
ruff check --show-settings        # Show resolved config
ruff check --show-files           # Show files to be checked
ruff check --statistics           # Show rule violation counts
```

# ty Reference (Beta)

Astral's Python type checker - extremely fast, written in Rust.

**GitHub**: https://github.com/astral-sh/ty | **Status**: Beta (0.0.x; current line 0.0.79)

> **Heads up**: ty is still pre-1.0 and each minor bump can change inference. Notable: 0.0.31 introduced `--fix`; 0.0.33 prefers declared annotation over inferred RHS when assignable, removing many `cast(...)` workarounds; **0.0.52 made `error-on-warning` the default**, so warnings now fail your build; 0.0.57 onward added a dedicated Pydantic support track; 0.0.67 removed the deprecated `src.root` in favour of `environment.root`. Pin a concrete version in `[dependency-groups]` rather than tracking `@latest`.

## Installation

```bash
# As dev dependency (recommended)
uv add --dev ty
uv run ty check

# Quick run without installing
uvx ty check

# Global install - pin a version; ty is beta and inference moves between minors
uv tool install ty@0.0.79

# Homebrew
brew install ty
```

## Basic Usage

```bash
ty check                    # Check current project
ty check src/ tests/        # Check specific paths
ty check --watch            # Watch mode (recheck on changes)
ty server                   # Start language server (LSP)
ty version                  # Print version
```

## Configuration in pyproject.toml

All config goes in `[tool.ty.*]` sections. Alternatively, use a standalone `ty.toml` file (omits `[tool.ty]` prefix).

### Environment Settings

```toml
[tool.ty.environment]
# Python version (default: inferred from requires-python minimum, fallback 3.14)
python-version = "3.13"

# Target platform: win32, darwin, linux, android, ios, all
python-platform = "linux"

# Path to Python environment (auto-discovered via VIRTUAL_ENV from uv run)
python = ".venv"

# Additional module resolution paths
extra-paths = ["./shared/stubs"]

# First-party module roots (priority order)
root = ["./src", "./lib"]

# Custom typeshed
typeshed = "/path/to/typeshed"
```

### Source Selection

```toml
[tool.ty.src]
# Files/dirs to include
include = ["src", "tests"]

# Files/dirs to exclude (gitignore patterns)
exclude = [
    "generated",
    "*.proto",
    "tests/fixtures/**",
    "!tests/fixtures/important.py",  # negate to re-include
]

# Respect .gitignore (default: true)
respect-ignore-files = true
```

### Rule Configuration

```toml
[tool.ty.rules]
# Set all rules to a severity
all = "error"               # or "warn" or "ignore"

# Individual rule overrides
possibly-unresolved-reference = "warn"
division-by-zero = "ignore"
unused-ignore-comment = "warn"
possibly-missing-attribute = "error"
possibly-missing-import = "error"
empty-body = "error"
```

### Analysis Settings

```toml
[tool.ty.analysis]
# Suppress unresolved-import for specific modules
allowed-unresolved-imports = ["test.**", "!test.foo"]

# Replace a module's types with `Any` - the targeted fix for a heavy-typing
# dependency that produces false positives, instead of swapping type checker.
# Import diagnostics are unconditionally suppressed for matching modules.
replace-imports-with-any = ["sqlalchemy.**"]

# Whether to respect `type: ignore` comments (default: true)
# Set false to only use `ty: ignore` comments
respect-type-ignore-comments = true
```

### Output Settings

```toml
[tool.ty.terminal]
# Output format: full, concise, github, gitlab, junit
output-format = "full"

# Exit code 1 on warnings. NOTE: the default is `true` since 0.0.52 -
# set this to false only if you deliberately want warnings to pass.
error-on-warning = false
```

### Per-File Overrides

```toml
[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]

[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"
empty-body = "ignore"

[[tool.ty.overrides]]
include = ["generated/**"]

[tool.ty.overrides.rules]
all = "ignore"
```

## CLI Flags

```bash
ty check [OPTIONS] [PATH]...

# Rule severity (repeatable, use 'all' for all rules)
--error <rule>              # Treat as error
--warn <rule>               # Treat as warning
--ignore <rule>             # Disable rule

# Environment
--python-version <ver>      # 3.7-3.15 accepted; 3.10 is the real support floor
--python-platform <plat>    # win32, darwin, linux, all
--python <path>             # Path to environment/interpreter
--extra-search-path <path>  # Additional module path
--typeshed <path>           # Custom typeshed

# Source
--exclude <pattern>         # Gitignore-style exclude
--force-exclude             # Enforce on direct paths too

# Config
-c <key=value>              # TOML override (e.g. 'environment.python-version="3.12"')
--config-file <path>        # Path to ty.toml
--project <dir>             # Project directory

# Output
--output-format <fmt>       # full, concise, github, gitlab, junit
--error-on-warning          # Exit 1 on warnings
--exit-zero                 # Always exit 0
-q / -v                     # Quiet / verbose

# Special
--watch, -W                 # Watch mode
--fix                       # Apply auto-fixes for diagnostics that support them (ty 0.0.31+)
--add-ignore                # Auto-add ty: ignore comments for all diagnostics
```

## Suppression Comments

```python
# Suppress specific rule
x: int = "hello"  # ty: ignore[invalid-assignment]

# Suppress all ty diagnostics on a line
x: int = "hello"  # ty: ignore

# mypy-compatible (respected by default)
x: int = "hello"  # type: ignore[assignment]
x: int = "hello"  # type: ignore
```

To disable `type: ignore` support:
```toml
[tool.ty.analysis]
respect-type-ignore-comments = false
```

## Integration with uv

Always run ty through uv to ensure proper environment discovery:

```bash
uv run ty check
```

`uv run` sets the `VIRTUAL_ENV` environment variable, which ty uses to find installed packages. Without it, ty may not resolve your project's dependencies.

### Update ty

```bash
uv lock --upgrade-package ty
```

## Key Type System Features

### Intersection Types

After isinstance checks, ty narrows to intersection types:

```python
class Serializable: ...
class Versioned: ...

def process(obj: Serializable):
    if isinstance(obj, Versioned):
        # ty: type is Serializable & Versioned
        reveal_type(obj)
```

### Gradual Types

For untyped code, ty uses `Unknown` instead of `Any` to avoid false positives:

```python
max_retries = None       # ty infers: Unknown | None (not just None)
max_retries = 3          # no error - Unknown allows this
```

### Redeclarations

ty allows reusing a symbol with a different type:

```python
def split_paths(paths: str) -> list[Path]:
    paths: list[str] = paths.split(":")  # ty allows this
    return [Path(p) for p in paths]
```

## Known Limitations

1. **Beta status** - expect bugs and missing features. Version 0.0.x, targeting stable in 2026.
2. **Incomplete typing spec** - long tail of Python typing features still being added.
3. **Third-party libraries** - Django and SQLAlchemy support is not yet complete. Pydantic has had a dedicated support track since 0.0.57 (constructors, `model_config`, `BaseSettings`, `RootModel`, strict vs lax) and is no longer the usual culprit. For a dependency that still misbehaves, silence just that one with `[tool.ty.analysis] replace-imports-with-any = ["sqlalchemy.**"]`.
4. **No plugin system** - unlike mypy, no plugin API for custom type inference.
5. **Some rules off by default** - `possibly-unresolved-reference`, `possibly-missing-import`, `division-by-zero` produce false positives.

## Recommended Setup

```toml
# Minimal, practical config
[tool.ty.environment]
python-version = "3.13"

[tool.ty.src]
include = ["src"]

# Keep default rules - they catch real issues without noise
# Add stricter rules incrementally as ty matures
```

For the Justfile:

```just
check:
    uv run ty check
    uv run ruff check
    uv run ruff format --check
```

# uv Reference (0.12.x)

Complete guide to uv - the Python package manager, version manager, and project runner.

> **Heads up (0.11 -> 0.12)**: `uv init` now **packages by default** - it writes a `[build-system]` using `uv_build`, uses src layout, and adds a `[project.scripts]` entry; `--no-package` restores the old flat layout. The default pre-release mode is now `if-necessary`, and `if-necessary-or-explicit` survives only as a deprecated alias. `uv venv --clear` now refuses to clear a directory that is not a virtualenv (use `--force`). `uv lock --upgrade-group <name>` validates the group and errors if it does not exist.
>
> **Earlier (0.10 -> 0.11)**: `uv venv` requires explicit `--clear` to remove an existing environment. `--native-tls` is deprecated in favor of `--system-certs`. `uv python upgrade`, `--upgrade-group`, and workspace commands `uv workspace dir` / `uv workspace list` are stable. Always run a recent uv (>= 0.11.6) to pick up the wheel-uninstall path-traversal fix (GHSA-pjjw-68hj-v9mw).

**Docs**: https://docs.astral.sh/uv/ | **GitHub**: https://github.com/astral-sh/uv

## Installation

```bash
# macOS/Linux (Homebrew)
brew install uv

# Or via pip
pip install uv

# Verify
uv version
```

## Project Initialization

### `uv init` Templates

As of uv 0.12.0 `uv init` **packages by default**: it writes a `[build-system]` using
`uv_build`, uses src layout, and adds a `[project.scripts]` entry. `--package` is now redundant;
`--no-package` gets the old flat, build-systemless layout.

```bash
# Packaged application (src layout, uv_build, entry point) - the default since 0.12
uv init my-project

# Flat application, no build system (the pre-0.12 default)
uv init --no-package my-app

# Library (src layout, py.typed marker)
uv init --lib my-lib

# Minimal (only pyproject.toml)
uv init --bare my-project

# With specific build backend (overriding the uv_build default)
uv init --build-backend hatchling my-project

# With author from git config
uv init --author-from git my-project
```

### Key `uv init` Flags

| Flag | Effect |
|------|--------|
| `--app` | Application template |
| `--package` | Packaged app with build system and src layout (default since 0.12) |
| `--no-package` | Flat layout with no build system (the pre-0.12 default) |
| `--lib` | Library (implies --package, adds py.typed) |
| `--bare` | Only pyproject.toml, no other files |
| `--build-backend <name>` | hatchling, flit-core, pdm-backend, setuptools, uv_build, maturin |
| `--python <ver>` | Set requires-python |
| `--author-from git` | Pull author from git config |
| `--vcs git` | Init git repo |
| `--python-pin` | Create .python-version file |

### Generated Structure (--package)

```
my-project/
  .python-version
  README.md
  pyproject.toml
  src/
    my_project/
      __init__.py
```

## Dependency Management

### Adding Dependencies

```bash
# Project dependencies
uv add httpx
uv add "httpx>=0.20"
uv add "httpx==0.27.0"

# Dev dependencies (goes to [dependency-groups] dev)
uv add --dev pytest ruff ty

# Named dependency group
uv add --group lint ruff
uv add --group test coverage

# Optional dependencies (extras)
uv add --optional network httpx

# From requirements file
uv add -r requirements.txt

# From git
uv add git+https://github.com/encode/httpx
uv add git+https://github.com/encode/httpx --tag 0.27.0
uv add git+https://github.com/encode/httpx --branch main

# From local path (editable)
uv add --editable ../packages/foo/

# With platform markers
uv add "jax; sys_platform == 'linux'"

# Control version bound style
uv add httpx --bounds exact     # ==x.y.z
uv add httpx --bounds minor     # >=x.y.z, <x.y+1.0
uv add httpx --bounds major     # >=x.y.z, <x+1.0.0
uv add httpx --bounds lower     # >=x.y.z (default)
```

### Removing Dependencies

```bash
uv remove httpx
uv remove --dev pytest
uv remove --group lint ruff
```

### Lockfile

```bash
uv lock                           # Create/update uv.lock
uv lock --check                   # Check if up-to-date (no changes)
uv lock --upgrade                 # Upgrade all to latest allowed
uv lock --upgrade-package httpx   # Upgrade specific package
uv lock --upgrade-group lint      # Upgrade everything in a dependency-group (uv 0.11.4+)
```

### Syncing Environment

```bash
uv sync                       # Exact sync (default - removes extraneous)
uv sync --inexact             # Don't remove extraneous packages
uv sync --no-dev              # Exclude dev group
uv sync --all-groups          # Include all groups
uv sync --group docs          # Include specific group
uv sync --all-extras          # Include all extras
uv sync --locked              # Error if lockfile outdated
uv sync --frozen              # Don't check lockfile
uv sync --no-install-project  # Skip installing the project itself
```

#### What `uv sync` installs

uv ships with `dev` in `default-groups`, so a bare `uv sync` already pulls dev deps. Other named groups only install when requested.

| Command | Installs |
|---|---|
| `uv sync` | main deps + `dev` |
| `uv sync --no-dev` | main deps only |
| `uv sync --group lint` | main deps + `dev` + `lint` |
| `uv sync --all-groups` | everything in `[dependency-groups]` |

To change the default set, declare it explicitly:

```toml
[tool.uv]
default-groups = ["dev", "test"]   # uv sync now includes both
```

### Exporting

```bash
uv export --format requirements.txt -o requirements.txt
uv export --format pylock.toml                    # PEP 751
uv export --format cyclonedx1.5                   # SBOM
```

## Running Code

### `uv run`

```bash
# Run Python files
uv run main.py
uv run python -c "import example"

# Run entry points
uv run my-cli-command

# Run with extra temporary dependencies
uv run --with httpx python -c "import httpx"

# Run with specific Python version
uv run --python 3.12 main.py

# Run without syncing
uv run --no-sync pytest

# Stdin
echo 'print("hello")' | uv run -
```

### Inline Script Metadata (PEP 723)

```python
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint
resp = requests.get("https://peps.python.org/api/peps.json")
pprint(resp.json())
```

Run with: `uv run script.py` - dependencies install automatically.

### `uvx` (Tool Runner)

```bash
uvx ruff check .              # Run tool without installing
uvx ruff@0.6.0 --version      # Specific version
uvx --with mkdocs-material mkdocs build

# Install persistently
uv tool install ruff
uv tool upgrade ruff
uv tool list
uv tool uninstall ruff
```

## Python Version Management

```bash
# Install
uv python install 3.13
uv python install 3.12 3.13    # Multiple
uv python install pypy          # Alternative implementation

# Pin (creates .python-version)
uv python pin 3.13
uv python pin --global 3.13     # Global default

# List
uv python list
uv python list --only-installed

# Upgrade patch versions
uv python upgrade 3.13          # 3.13.x -> latest 3.13.y
uv python upgrade               # All installed

# Find
uv python find '>=3.12'

# Remove
uv python uninstall 3.12
```

## pyproject.toml Configuration

### `[tool.uv]` Settings

```toml
[tool.uv]
managed = true                    # uv manages this project
required-version = ">=0.10.0"     # Enforce minimum uv version
default-groups = ["dev"]          # Groups to sync by default

# Resolution
resolution = "highest"            # highest, lowest, lowest-direct
prerelease = "if-necessary-or-explicit"

# Performance
compile-bytecode = false
link-mode = "clone"               # clone (macOS), hardlink (Linux)
```

### `[tool.uv.sources]` - Custom Dependency Sources

```toml
[tool.uv.sources]
# From specific index
torch = { index = "pytorch" }

# From git
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }

# Local editable
my-lib = { path = "../my-lib", editable = true }

# Workspace member
my-pkg = { workspace = true }
```

### `[[tool.uv.index]]` - Package Indexes

```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true    # Only used when referenced in sources

[[tool.uv.index]]
name = "private"
url = "https://private.example.com/simple/"
default = true     # Replaces PyPI
```

### `[dependency-groups]` (PEP 735)

```toml
[dependency-groups]
dev = [
    "ruff>=0.16.6",
    "ty>=0.0.79",
    "pytest>=9.1.1",
    {include-group = "lint"},
]
lint = ["ruff"]
test = ["pytest", "coverage"]
docs = ["sphinx", "furo"]
```

`[dependency-groups]` is PEP 735 and supported by uv (and modern pip 25+). For libraries published to PyPI that need broader tooling support, `[project.optional-dependencies]` (extras) remains the portable choice.

## CLI Entry Points (`[project.scripts]`)

Declare console scripts in `pyproject.toml`:

```toml
[project.scripts]
my-project = "my_project:main"
my-project-admin = "my_project.cli:admin"
```

Format is `<script-name> = "<module>:<callable>"`. Two requirements:

1. **A build system.** Editable installs (which `uv sync` performs for the current project) need `[build-system]`. Without it, `uv sync` errors with "project requires a build system to install".

   ```toml
   [build-system]
   requires = ["hatchling"]
   build-backend = "hatchling.build"

   [tool.hatch.build.targets.wheel]
   packages = ["src/my_project"]
   ```

2. **A matching callable.** `my_project:main` resolves to the `main` attribute of `src/my_project/__init__.py`. `my_project.cli:admin` resolves to `admin` in `src/my_project/cli.py`.

   ```python
   # src/my_project/__init__.py
   def main() -> None:
       print("hello from my-project")
   ```

After `uv sync`, run with `uv run my-project`. uv installs the project editable, so edits under `src/` take effect on the next invocation - no reinstall.

## Workspaces (Monorepos)

Root `pyproject.toml`:

```toml
[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/experimental"]
```

```bash
uv workspace list       # List all members
uv workspace dir        # Show workspace root
uv run --package foo    # Run in specific member's context
```

Key: single `uv.lock` for entire workspace, single `requires-python` intersection.

## Build and Publish

```bash
# Build
uv build                     # sdist + wheel into dist/
uv build --wheel             # Wheel only
uv build --no-sources        # Ignore tool.uv.sources (before publishing)

# Version management
uv version                   # Read current
uv version 1.0.0             # Set exact
uv version --bump patch      # 1.2.3 -> 1.2.4
uv version --bump minor      # 1.2.3 -> 1.3.0
uv version --bump major      # 1.2.3 -> 2.0.0

# Publish
uv publish                   # To PyPI
uv publish --token <TOKEN>
uv publish --index testpypi

# Prevent accidental PyPI publish
# Add to classifiers: "Private :: Do Not Upload"
```

## CI/CD (GitHub Actions)

```yaml
name: CI
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.0.1   # full version: floating majors stop at v7
      - run: uv sync --all-groups
      - run: uv run ty check
      - run: uv run ruff check --output-format github
      - run: uv run ruff format --check
      - run: uv run pytest
      - run: uv run lefthook validate
```

## Troubleshooting

```bash
uv cache clean               # Clear package cache
uv lock --upgrade             # Regenerate lockfile
rm -rf .venv && uv sync      # Reset environment
uv python list --only-installed  # Check Python installations
```