# AGENTS.md

This file is for future coding agents working on this repository.

## Project Overview

- Package: `xml_to_xlsx`
- Purpose: Convert XML workbook definitions into styled Excel `.xlsx` files using `openpyxl`.
- Public API must remain stable:
  - `generate_workbook_from_xml(xml_source)`
  - `write_workbook_from_xml(xml_source, save_to=...)`
  - `XmlSource` type alias
- Primary docs: `README.md`

## Current Architecture

- `xml_to_xlsx/api.py`
  - Public API orchestration and workbook lifecycle.
- `xml_to_xlsx/_parser.py`
  - XML loading, parsing helpers, spans, bool parsing, value coercion.
- `xml_to_xlsx/_renderer.py`
  - Sheet/row/cell rendering and merge/layout behavior.
- `xml_to_xlsx/_styling.py`
  - CSS-like style parsing and mapping to `openpyxl` style objects.
- `xml_to_xlsx/__init__.py`
  - Re-exports public API and package `__version__`.

## Tooling and Workflow

- Python/package manager workflow uses `uv`.
- Run tests with coverage gate:
  - `uv run --extra test pytest`
- Coverage configuration is in `pyproject.toml` under `tool.pytest.ini_options`.
- Coverage minimum is enforced at **90%** (`--cov-fail-under=90`).

## Testing and Quality Expectations

- Test suite location: `tests/`
- Existing tests cover:
  - Public API behavior
  - Parser helpers
  - Styling conversion logic
  - Renderer behavior and selected internal branches
- If you add features, update tests and README in the same change.

## Compatibility and Packaging

- Build backend: `hatchling`
- Python requirement: `>=3.10`
- Runtime dependencies:
  - `defusedxml>=0.7.1`
  - `openpyxl>=3.1.0`
- Typing marker exists: `xml_to_xlsx/py.typed` (PEP 561)

## Important Implementation Notes

- XML root must be `<workbook>`; invalid root raises `ValueError`.
- `xml_source` supports raw XML, file-like objects, and path-like strings.
- Style precedence is sheet -> row -> cell.
- Merged range style propagation is applied when merges are defined via cell span/merge metadata.
- `__version__` is loaded from installed package metadata and falls back to `"0.0.0"` in local/non-installed contexts.

## Known Quirks

- `openpyxl` font merging can produce surprising values in some cases (for example, font name composition behavior). Validate behavior via tests instead of assuming direct replacement semantics.
- Some branches in `__init__.py` (metadata fallback path) are environment-dependent and may show as uncovered locally.

## Agent Memory (Keep Updated)

Update this section whenever you make structural or policy decisions.

- The package was refactored from a monolithic `__init__.py` into internal modules (`_parser`, `_renderer`, `_styling`) with public API preserved.
- README was rewritten to a GitHub-style format and should stay aligned with actual API and XML/styling behavior.
- Test and coverage setup is intentionally strict; keep coverage >= 90%.
- Use `uv run --extra test pytest` as the canonical local verification command.
- Do not introduce breaking changes to top-level imports without clearly documenting and versioning appropriately.
