# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`rna` is a Python utility library providing foundational building blocks: logging, path handling, argument parsing, config files, design patterns, and multi-backend plotting. Python 3.8+ supported.

## Commands

This project uses [Pixi](https://pixi.sh) for task management.

```bash
pixi run test              # Run pytest (preferred)
pixi run lint              # ruff check
pixi run format            # ruff format
pixi run coverage-build    # Generate HTML + XML coverage reports
pixi run docs-build        # Build Sphinx docs
pixi run check             # Run all pre-commit checks + build validation
```

Run a single test file or test:
```bash
pixi run pytest tests/test_log.py
pixi run pytest tests/test_log.py::test_function_name
pixi run pytest -k "test_name_pattern"
```

Pytest flags:
- `--plot` — enable visual plot tests (disabled by default, `plt.show` is mocked)
- `--slow` — include slow tests

## Architecture

### Package layout

```
rna/
├── __init__.py         # Exports: log, path, process, parsing, pattern, polymorphism
├── log.py              # Color-formatted logging, optional tqdm progressbar
├── path.py             # pathlib extensions
├── parsing.py          # ArgumentParser extensions with logging integration
├── process.py          # System command execution
├── config.py           # Multi-dialect config files (cfg/ini/toml/json)
├── polymorphism.py     # Storable mixin (save/load dispatch by file extension)
├── pattern/            # Design pattern implementations
│   ├── backend.py      # Backend abstraction
│   ├── composite.py    # Composite
│   ├── decorator.py    # Flexible decorator (functions, methods, staticmethods)
│   ├── link.py         # Chain of responsibility
│   ├── singleton.py    # Singleton
│   ├── strategy.py     # Strategy (Context + Strategy classes)
│   └── switch.py       # Switch
└── plotting/           # Multi-backend plotting
    ├── core.py         # Unified API + strategy selection
    ├── base.py         # Base classes
    ├── colors.py       # Color utilities
    ├── paths.py        # Path plotting
    └── backends/
        ├── matplotlib.py
        └── pyqtgraph.py
```

### Key design patterns

- **Plotting backend**: Strategy pattern — switch with `rna.plotting.use('matplotlib')` or `rna.plotting.use('pyqtgraph')`. Both backends implement the same `ApiBackend` interface in `plotting/core.py`.
- **Config dialects**: Strategy pattern — `config.py` dispatches to the appropriate parser based on file extension.
- **Storable**: Mixin in `polymorphism.py` — subclasses implement `_save_{ext}` / `_load_{ext}` methods; `save(path)` / `load(path)` dispatch by extension.
- **Doctest**: Tests live both in `tests/` and inline in docstrings. `conftest.py` injects `numpy as np` into the doctest namespace.

### Commit conventions

Commits must follow [Conventional Commits](https://www.conventionalcommits.org/). Allowed types: `feat`, `fix`, `refactor`, `test`, `docs`, `style`, `ci`, `build`, `chore`, `perf`, `revert`, `release`.
