dragoman

Toolkit to produce docstrings for pysits.

Installation

Install from source:

pip install git+https://github.com/m3nin0-labs/dragoman.git

Usage

To use the tool, first it is required to create a pysits.toml, specifying the rules of translation, virtual env used to introspect pysits API and few other details. Once the file is created, we are good to go.

Inspect the target API

Before generating anything, let's confirm dragoman can see the pysits you expect. dragoman api runs the introspection step in isolation and prints the functions and sample datasets it discovered.

uv run dragoman api

Generate docstrings

dragoman generate is the main pass. It renders each Rd page into conversions/base/*.md, asks the LLM to translate the R example into Python, and runs the translation in the pysits interpreter to make sure it works. Examples that fail verification are still emitted, marked so you can spot them during review.

uv run dragoman generate

Use --static-only to skip the LLM and execution stages entirely. This is useful for a first pass, for CI, or when you do not have an API key.

uv run dragoman generate --static-only

Harmonize S3 method families

The R sits package ships various functions as S3 method families (plot.*, sits_get_data.*, summary.*, ...) where every method has its own Rd page. pysits collapses each family into a single Python function, so the docstrings should too.

To solve this, we can use, dragoman harmonize which merges each family into one coherent docstring, drops references to methods that do not exist in Python, and writes the result to conversions/harmonized/.

uv run dragoman harmonize

Retype

The Rd sources talk about "tibbles", "character vectors", and "NULL". Python callers see SITSTimeSeriesModel, list[str], and None. The dragoman retype command, rewrites the R type language into the ergonomic Python types that pysits actually returns and accepts, and logs every substitution in retype.json.

uv run dragoman retype

The pass reads from conversions/harmonized/ when present, otherwise from conversions/base/.

Coverage summary

The dragoman coverage command reprints the summary from the most recent generate run without redoing any work.

uv run dragoman coverage

Each pass writes to its own directory, so every change is reviewed independently. When you are happy with a docstring, move the file into pysits/docs/content and wire it up with the attach_doc decorator by hand.

Development

Clone the repository and set up a development environment with uv:

git clone https://github.com/m3nin0-labs/dragoman.git
cd dragoman

uv sync                            # install runtime + dev deps
uv run pytest -q                   # run the test suite
uv run pytest -m integration -q    # opt-in: hits the real Anthropic API
uv run ruff check dragoman tests   # lint
uv run mypy dragoman tests         # type-check

The integration marker is deselected by default and requires ANTHROPIC_API_KEY in .env. Everything else runs offline.

Contributing

Contributions are welcome. For anything larger than a targeted fix, please open an issue first so we can align on the approach before you invest time in a pull request.

License

dragoman is distributed under the GPL-2.0-only license. See LICENSE for the full text.