# Migration to Python 3.12, Pydantic v2, and uv tooling

This document describes the migration steps performed on the `pymultirole_plugins` project.

## 1. Build system: flit → hatchling/uv

The build system was migrated from **flit** to **hatchling** with **uv** as the package manager.

- `pyproject.toml`: changed `build-system` to use `hatchling`
- Replaced `flit` commands with `uv build` and `uv publish`
- Jenkinsfile updated to use `uv pip install` and `uv build`/`uv publish`

## 2. Python version: 3.8+ → 3.12

- `requires-python` set to `>=3.12` in `pyproject.toml`
- `Dockerfile` updated to use Python 3.12 base image
- Classifiers updated accordingly

## 3. Pydantic v1 → v2

- Updated `pydantic` dependency to `>=2.0,<3.0`
- Replaced deprecated Pydantic v1 APIs:
  - `validator` → `field_validator`
  - `schema_extra` → `json_schema_extra`
  - `Config` inner class → `model_config = ConfigDict(...)`
  - `.dict()` → `.model_dump()`
  - `Optional[X] = None` patterns updated
- Schema classes in `pymultirole_plugins/v1/schema.py` refactored for v2 compatibility

## 4. Linter: black + flake8 → ruff

- Removed `black` and `flake8` dependencies
- Added `ruff` to test dependencies
- Configured `[tool.ruff]` in `pyproject.toml`:
  - `line-length = 120`
  - `target-version = "py312"`
  - Lint rules: `E`, `W`, `F`, `I`, `B`, `C4`, `UP`, `ARG`, `SIM`
  - Format: double quotes, space indent

### Running the linter

```
uv run ruff check .
uv run ruff format --check .
```

To auto-fix formatting:

```
uv run ruff format .
```

## 5. Test runner: tox → uv

**tox** was removed entirely. The project now uses `uv run` to execute tests, linting, and doc generation directly.

### What changed

- Deleted `tox.ini`
- Removed `tox` from `[project.optional-dependencies].test`
- Moved pytest configuration from `tox.ini` to `pyproject.toml`:

```toml
[tool.pytest.ini_options]
addopts = "--durations=5"
norecursedirs = ["docs"]
```

### Running tests

```
uv run pytest
```

### Why tox was unnecessary

- The project targets a single Python version (3.12)
- The Jenkinsfile CI pipeline was already using `uv`, `ruff`, and `pytest` directly, not tox
- `uv run` provides virtual environment isolation without the extra layer

## 6. Documentation generation

Sphinx is used for documentation with the `docs` optional dependency group.

### Fix: added `lxml_html_clean` dependency

The `jupyter_sphinx` extension requires `lxml_html_clean` (split from `lxml` in recent versions). This was added to `[project.optional-dependencies].docs`.

### Generating docs

```
uv run --extra docs sphinx-build docs docs/_build
```

## 7. Jenkinsfile updates

- `__init__.py` generation now includes a blank line between the docstring and `__version__` to comply with `ruff format`
- Build/publish pipeline uses `uv build` and `uv publish`

## 8. .gitignore updates

Added the following entries:
- `uv.lock` — generated lock file, not committed
- `docs/_build/` — generated documentation output
