Code Style¶

The IFPA SDK enforces strict code style using automated tools.

Code Formatters and Linters¶

Black¶

Code formatting with 100 character line length:

# Format all code
poetry run black src tests

# Check without modifying
poetry run black --check src tests

Configuration in pyproject.toml:

[tool.black]
line-length = 100
target-version = ["py311"]

Ruff¶

Fast Python linting:

# Check linting
poetry run ruff check src tests

# Auto-fix issues
poetry run ruff check --fix src tests

mypy¶

Static type checking with strict mode:

# Type check source code
poetry run mypy src

Pre-commit Hooks¶

Install pre-commit hooks to automatically check code before commits:

poetry run pre-commit install

Hooks run automatically on git commit. Run manually:

poetry run pre-commit run --all-files

Code Style Guidelines¶

Type Hints¶

All public functions must have complete type hints:

# Good
def get_player(player_id: int | str) -> Player:
    ...

# Bad - missing types
def get_player(player_id):
    ...

Docstrings¶

All public APIs must have docstrings in Google style:

def search_players(name: str, count: int | None = None) -> PlayerSearchResponse:
    """Search for players by name.

    Args:
        name: Player name to search for
        count: Maximum number of results

    Returns:
        Search results with player list

    Raises:
        IfpaApiError: If the API request fails

    Example:
        ```python
        results = client.player.query("John").limit(25).get()
        ```
    """

Function Length¶

Keep functions focused and under 20 lines:

# Good - single responsibility
def get_player_name(player: Player) -> str:
    return f"{player.first_name} {player.last_name}"

# Bad - too long, multiple responsibilities
def process_player(player_id: int):
    # 50 lines of code doing multiple things
    ...

Import Organization¶

Use Ruff's isort integration for consistent imports:

# Standard library
import os
from typing import Any

# Third-party
import requests
from pydantic import BaseModel

# Local
from ifpa_api.core.config import Config
from ifpa_api.core.exceptions import IfpaError

Editor Configuration¶

VS Code¶

.vscode/settings.json:

{
  "python.formatting.provider": "black",
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.linting.mypyEnabled": true,
  "editor.formatOnSave": true
}

PyCharm¶

Install Black plugin
Enable Ruff
Configure mypy as external tool

For complete guidelines, see CONTRIBUTING.md.