xpd index
Parse library source into a versioned index. Never imports or runs library code
Use xpd index when xpd find and xpd api should search a library or a
version that xpd does not ship. It builds a search index from the Python source and stub files
of a library, and never imports or runs library code. It parses the source with Griffe 2.4.1 in
the project's Python, so start it with uv run --with griffe==2.4.1. No other command needs
Griffe.
xpd index [OPTIONS] --package <PACKAGE> <SOURCE>Arguments
Section titled “Arguments”<SOURCE>
Section titled “<SOURCE>”<SOURCE>
The library's source folder or installed package folder, such as a site-packages folder.
Required.
Options
Section titled “Options”--package
Section titled “--package”--package <PACKAGE>
The Python import name of the library, such as sklego.
Required.
--version
Section titled “--version”--version <VERSION>
The library version. Default: the version in the wheel metadata, so give it for a source checkout.
--output
Section titled “--output”--output <OUTPUT>
The file to write. Default: indexes/<package>.json, in a folder that exists.
--examples
Section titled “--examples”--examples <EXAMPLES>
Documentation and gallery root to harvest with the symbol index.
--source-url
Section titled “--source-url”--source-url <SOURCE_URL>
Repository URL ending in /blob/<pinned revision> for example attribution.
--license
Section titled “--license”--license <LICENSE>
The source's license file, which names the license of each recipe.
Examples
Section titled “Examples”uv run --with griffe==2.4.1 xpd index /path/to/site-packages --package sklegouv run --with griffe==2.4.1 xpd index /path/to/source/sklego --package sklego --version 0.9.10 --output local.jsonxpd find "grouped regression" --index local.jsonxpd api sklego.meta.GroupedPredictor --index local.jsonWithout Griffe, xpd index stops and prints the command to run.
$ xpd index samples/sklego --package sklego --version 0.9.10xpd: Index building needs griffe==2.4.1. Run uv run --with griffe==2.4.1 xpd index samples/sklego --package sklego --version 0.9.10.A local index replaces the shipped index of its package, and it also works for a library without
an xpd rule pack. Without --examples, the command keeps the recipes that the output file
already holds for the same package and version.
Index file
Section titled “Index file”Each index file has schema_version, package, version and entries. schema_version is 2,
and find and api refuse a local index of schema 1.
| Key | What it holds |
|---|---|
| Every entry | kind, package, name, callable, parameters, summary, members and rules, and keywords taken from the source when there are any |
| An entry or a member with parameters | parameters_written, the parameter list as the source writes it |
| A member | name, parameters and summary, and property, which is true for a property |
| A recipe entry | recipe, with title, symbols, source, code, license and modified, and attribution when the source file has copyright lines |
recipes |
The counts from collecting recipes, with candidates, clean, fixed, dropped, capped and retained |
Recipes
Section titled “Recipes”--examples collects recipes from the documentation of a library checkout pinned to a version.
It reads the Examples sections of docstrings, Python files under examples or gallery folders,
Python code blocks in Markdown, doctests in reStructuredText and notebook code cells, and it
never runs them. It keeps a snippet only when the rule engine finds no issue in it after fixes,
and it keeps up to 24 recipes and 96,000 code bytes per pack. --license names the license of
each recipe, and a license that xpd does not recognize gives a pointer to the source without
the code.
uv run --with griffe==2.4.1 xpd index /var/tmp/xpd-source/scikit-lego-0.9.10 --package sklego --version 0.9.10 \ --examples /var/tmp/xpd-source/scikit-lego-0.9.10 \ --source-url https://github.com/koaning/scikit-lego/blob/v0.9.10 \ --license /var/tmp/xpd-source/scikit-lego-0.9.10/LICENSEExit status
Section titled “Exit status”| Exit code | Meaning |
|---|---|
| 0 | The index was written |
| 2 | Griffe is missing, the source cannot be read, or the output folder does not exist |