From ff1f42dae5f4b456be05f03328f7458ea223789c Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 12:00:42 -0700 Subject: [PATCH] document the optional dependencies Explain in the installation section that a base install needs no compiler, and give the install command for each optional feature. The tests section said to run the suite with `uv run pytest`, which contradicted the installation section's statement that uv is not required; use plain pytest and note that tests for the optional features skip when their dependency is absent. Co-Authored-By: Claude Opus 5 (cherry picked from commit 1c4c8dfe31cb8a8eea0dc72b7ca136b44e134c9f) --- README.md | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2a39481..4cd9ab3 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,26 @@ this repository: [uv](https://docs.astral.sh/uv/) works too (`uv sync`) and is convenient for development, but it is not required. -One dependency, `pywikidiff2`, is installed from source and compiles a -C++ extension, so a C++ compiler must be available at install time. +This installs everything needed for the columns most people use, and +requires no compiler. Two features carry heavier dependencies and are +therefore optional. + +`--diff` and `-p wikidiff2` need +[pywikidiff2](https://gitea.communitydata.science/groceryheist/pywikidiff2), +a Python binding for MediaWiki's wikidiff2 diff engine. It is not on +PyPI and compiles a C++ extension, so it needs a C++ compiler and +libthai: + + pip install 'pywikidiff2 @ git+https://gitea.communitydata.science/groceryheist/pywikidiff2.git' + +`-p legacy` needs `mediawiki-utilities`, which is only useful for +reproducing results from older research projects: + + pip install '.[legacy]' + +wikiq tells you which of these to install if you use an option that +needs one. The other persistence methods, including the default +`-p sequence`, need neither. Wikimedia dumps are usually compressed as 7z (most common), gz, or bz2. wikiq reads these by running your system's decompression tools, so it @@ -80,12 +98,16 @@ The most commonly useful options (`wikiq --help` describes them all): From the repository root: - uv run pytest test/ + pip install pytest pandas pytest-asyncio pytest-benchmark + pytest test/ Run the suite from the root—some tests open fixture files by paths relative to it. The full suite processes several real dumps from -`test/dumps/` and takes a couple of minutes; expected outputs live in -`test/baseline_output/`. +`test/dumps/`; expected outputs live in `test/baseline_output/`. + +Tests covering `--diff`, `-p wikidiff2`, and `-p legacy` skip when their +optional dependency is absent, so a base install reports skips rather +than failures. ## Authors