Skip to content

agents.md

Latest commit

 

History

History
113 lines (75 loc) · 3.1 KB

agents.md

File metadata and controls

113 lines (75 loc) · 3.1 KB

Python Repo Instructions

Adding Dependencies

  • Add a runtime dependency: uv add <package-name>
  • Add a development dependency: uv add --dev <package-name>
  • Lock dependencies: uv lock
  • Sync after manual edits to pyproject.toml: uv sync

Code Quality & Formatting

Ruff - Linting and Formatting

To use ruff for code quality, first add it as a dev dependency: uv add --dev ruff

  • Format code: uv run ruff format .
  • Check formatting without changes: uv run ruff format --check .
  • Run linter: uv run ruff check .
  • Run linter with auto-fix: uv run ruff check --fix .
  • Run all checks: uv run ruff check . && uv run ruff format --check .

Type Checking

To use mypy for type checking, first add it as a dev dependency: uv add --dev mypy

  • Run mypy for type checking: uv run mypy src/
  • Run mypy on specific file: uv run mypy path/to/file.py

Testing

Running Tests

To use pytest for testing, first add it as a dev dependency: uv add --dev pytest

  • Run all tests: uv run pytest
  • Run specific test file: uv run pytest tests/test_module.py
  • Run tests matching pattern: uv run pytest -k "test_pattern"
  • Run with coverage: uv run pytest --cov=src --cov-report=term-missing (requires uv add --dev pytest-cov)
  • Run with verbose output: uv run pytest -v

Test Organization

  • All tests go in the tests/ directory
  • Test files must start with test_ and end with .py
  • Test functions must start with test_
  • Use descriptive test names that explain what is being tested

Code Style Guidelines

General Python Style

  • Follow PEP 8 conventions
  • Use type hints for function signatures
  • Prefer explicit over implicit

Import Organization

The expected order is:

  1. Standard library imports
  2. Third-party imports
  3. Local application imports

Blank lines separate each group.

Docstrings

Use Google-style docstrings for public modules, classes, methods, and functions.

Example function docstring:

def process_data(items: list[str], timeout: int = 30) -> dict[str, str]:
    """Process a list of items and return results.

    Args:
        items: List of items to process.
        timeout: Maximum time in seconds. Defaults to 30.

    Returns:
        Dictionary containing processed results.

    Raises:
        ValueError: If items list is empty.
    """

Type Hints

  • Public functions and methods should have type hints
  • Use modern Python type syntax (e.g., list[int] instead of List[int])
  • Use T | None for nullable types

Naming Conventions

  • Classes: PascalCase
  • Functions/methods: snake_case
  • Constants: UPPER_SNAKE_CASE
  • Private methods/attributes: prefix with single underscore _private_method

Development Workflow

Project Structure

  • Source code lives in src/agent_tools/
  • The package has a CLI entrypoint defined as agent-tools in pyproject.toml

Running the CLI

  • Run the CLI: uv run agent-tools
  • Or use: uv run python -m agent_tools

Configuration

Project settings are in pyproject.toml. Add tool-specific configuration sections as needed (e.g., [tool.ruff], [tool.mypy], [tool.pytest]).