python-configs/README.md

# lilith-python-configs

Shared Python tooling configurations for all Lilith projects. Provides standardized, opinionated configurations for:

- **ruff** - Linting and formatting (replaces black, isort, flake8)
- **mypy** - Type checking
- **pytest** - Testing

## Installation

```bash
pip install lilith-python-configs
```

Or with uv:

```bash
uv add lilith-python-configs --dev
```

## Usage

### Ruff Configuration

Ruff supports extending external configurations. Add to your `pyproject.toml`:

```toml
[tool.ruff]
extend = ".venv/lib/python3.11/site-packages/lilith_python_configs/ruff.toml"
```

Or use the helper to get the path programmatically:

```python
from lilith_python_configs import get_ruff_config_path

print(get_ruff_config_path())
# /path/to/.venv/lib/python3.11/site-packages/lilith_python_configs/ruff.toml
```

**Override specific settings** while inheriting the base:

```toml
[tool.ruff]
extend = ".venv/lib/python3.11/site-packages/lilith_python_configs/ruff.toml"
line-length = 120  # Override: use 120 instead of 100

[tool.ruff.lint]
extend-select = ["ANN"]  # Add: type annotation checks
```

### MyPy Configuration

MyPy doesn't support extending external configs. Copy the settings to your `pyproject.toml`:

```toml
[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_configs = true
warn_unreachable = true
show_error_codes = true
show_column_numbers = true
incremental = true

[tool.mypy.overrides]
module = "tests.*"
disallow_untyped_defs = false
```

Or copy `mypy.ini` to your project root:

```python
from lilith_python_configs import get_mypy_config_path
import shutil

shutil.copy(get_mypy_config_path(), "mypy.ini")
```

### Pytest Configuration

Copy the pytest settings to your `pyproject.toml`:

```toml
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
asyncio_mode = "auto"
addopts = "-v --tb=short --strict-markers --strict-config"
filterwarnings = [
    "error",
    "ignore::DeprecationWarning",
]
markers = [
    "slow: marks tests as slow",
    "integration: marks tests as integration tests",
]
```

## What's Included

### Ruff Rules

The ruff configuration enables:

| Category | Rules | Purpose |
|----------|-------|---------|
| Core | E, F, W | pycodestyle errors/warnings, pyflakes |
| Imports | I | isort-style import sorting |
| Quality | N, UP, B, C4, SIM | naming, upgrades, bugs, comprehensions |
| Hygiene | RUF, PTH, ERA | ruff-specific, pathlib, dead code |

### Formatting

- Line length: 100 characters
- Double quotes
- Space indentation
- Docstring code formatting enabled

### Type Checking (MyPy)

- Strict mode enabled
- All strict flags explicitly listed for transparency
- Test files have relaxed typing requirements

### Testing (Pytest)

- Auto async mode (pytest-asyncio)
- Verbose output with short tracebacks
- Strict markers and config
- Common markers pre-registered (slow, integration, unit)

## API Reference

```python
from lilith_python_configs import (
    __version__,
    get_config_dir,
    get_ruff_config_path,
    get_mypy_config_path,
    get_pytest_config_path,
)

# Get package version
print(__version__)  # "1.0.0"

# Get config directory
print(get_config_dir())  # Path to package directory

# Get individual config paths
print(get_ruff_config_path())   # Path to ruff.toml
print(get_mypy_config_path())   # Path to mypy.ini
print(get_pytest_config_path()) # Path to pytest.ini
```

## License

MIT
# Test persist 1767649114