Skip to content

AGENTS.md

Latest commit

 

History

History
95 lines (80 loc) · 2.63 KB

AGENTS.md

File metadata and controls

95 lines (80 loc) · 2.63 KB
Raw

Development Guidelines

This document contains critical information about working with this codebase. Follow these guidelines precisely.

Core Development Rules

  1. Package Management

    • ONLY use uv, NEVER pip
    • Installation: uv add package
    • Running tools: uv run tool
    • Upgrading: uv add --dev package --upgrade-package package
    • FORBIDDEN: uv pip install, @latest syntax

  2. Code Quality

    • Type hints required for all code
    • Public APIs must have docstrings
    • Functions must be focused and small
    • Follow existing patterns exactly
    • Line length: 120 chars maximum

  3. Testing Requirements

    • Framework: uv run --frozen pytest
    • Async testing: use anyio, not asyncio
    • Coverage: test edge cases and errors
    • New features require tests
    • Bug fixes require regression tests

Python Tools

Code Formatting

  1. Ruff

    • Format: uv run --frozen ruff format .
    • Check: uv run --frozen ruff check .
    • Fix: uv run --frozen ruff check . --fix
    • Critical issues:
      • Line length (88 chars)
      • Import sorting (I001)
      • Unused imports
    • Line wrapping:
      • Strings: use parentheses
      • Function calls: multi-line with proper indent
      • Imports: split into multiple lines

  2. Type Checking

    • Tool: uv run --frozen pyright
    • Requirements:
      • Explicit None checks for Optional
      • Type narrowing for strings
      • Version warnings can be ignored if checks pass

Error Resolution

  1. CI Failures

    • Fix order:
      1. Formatting
      2. Type errors
      3. Linting
    • Type errors:
      • Get full line context
      • Check Optional types
      • Add type narrowing
      • Verify function signatures

  2. Common Issues

    • Line length:
      • Break strings with parentheses
      • Multi-line function calls
      • Split imports
    • Types:
      • Add None checks
      • Narrow string types
      • Match existing patterns
    • Pytest:
      • If the tests aren't finding the anyio pytest mark, try adding PYTEST_DISABLE_PLUGIN_AUTOLOAD="" to the start of the pytest run command eg: PYTEST_DISABLE_PLUGIN_AUTOLOAD="" uv run --frozen pytest

  3. Best Practices

    • Check git status before commits
    • Run formatters before type checks
    • Keep changes minimal
    • Follow existing patterns
    • Document public APIs
    • Test thoroughly

Exception Handling

  • Catch specific exceptions where possible:
    • File ops: except (OSError, PermissionError):
    • JSON: except json.JSONDecodeError:
    • Network: except (ConnectionError, TimeoutError):
  • Only catch Exception for:
    • Top-level handlers that must not crash
    • Cleanup blocks (log at debug level)