Skip to main content

xpd

xpd checks Python code for slow operations and wrong results. It checks code that uses pandas, NumPy, SciPy, scikit-learn, scikit-lego, MAPIE, Category Encoders, linearmodels, arch, pymoo, plotly or Apache Hamilton. xpd can rewrite many of the lines it reports, and a coding agent can run it after every edit.

What xpd reports

samples/bad.py holds slow loops and pandas assignments that write to a copy. The diff below shows what xpd check samples/bad.py --fix --unsafe-fixes changes. Each comment names the rule that reports the line.

 import pandas as pd

 df = pd.DataFrame({"a": [1, 2], "k": [1, 2]})
 other = df.copy()
 for i, row in df.iterrows():           # warning  pandas/row-loop
-    df["a"][i] = row["a"] * 2          # error    pandas/chained-assignment
+    df.loc[i, "a"] = row["a"] * 2
-df.dropna(inplace=True)                # info     pandas/no-inplace
+df = df.dropna()
 m = pd.merge(df, other, on="k")        # warning  pandas/merge-without-validate
 out = pd.DataFrame()
 for f in ["x.csv"]:
     out = pd.concat([out, pd.read_csv(f)])  # warning  pandas/concat-in-loop

Each message says what goes wrong and what to write instead.

samples/bad.py:6:5: error [pandas/chained-assignment] Chained assignment writes to a copy under copy-on-write, so the frame keeps its old values. Assign to df.loc[i, "a"] instead.

An issue has one of three severities, and a fix is either safe or unsafe.

Word Meaning
error The code gives a wrong result or raises. Fix it.
warning The code is slow or easy to get wrong. Fix it unless you can say why it is right here.
info A shorter or newer form exists.
safe fix Keeps what the code does. --fix writes it.
unsafe fix May change what the code does. --fix --unsafe-fixes writes it, so read the diff afterwards.

Rules

Each library has one pack of rules, written for the library's current version. A library's pack runs only on files that import the library. The plotly pack also runs on files that make plotly the plotting backend of pandas. The Python pack runs on every file.

Pack One of its rules What the rule reports
pandas chained-assignment df["a"][i] = v writes to a copy, so the frame keeps its old values
NumPy append-flattens np.append without axis flattens both arrays
SciPy removed-keyword tol= on the sparse iterative solvers was removed and raises TypeError
scikit-learn fit-on-test A fit on the test rows makes the score on those rows useless
scikit-lego thresholder-score Thresholder.score ignores threshold, so a search scores every threshold the same
MAPIE calibrate-on-training-rows conformalize on the training rows gives intervals that covered 0.48 of new rows where 0.90 was asked
Category Encoders ordinal-mapping-pairs An OrdinalEncoder mapping given as a list of pairs codes every row as -1.0
linearmodels clustered-without-clusters cov_type="clustered" without clusters gives the robust standard errors under another name
arch unscaled-returns Returns as decimals made the optimizer stop with code 4 and give a mean of 4.02 where 0.056 was right
pymoo objectives-stacked-by-row out["F"] = np.array([f1, f2]) in a Problem gives each solution the wrong values, and a least f2 of 0.003 came back where the true least is 10
plotly marker-size-diameter A marker's size is its diameter, so markers for 10 and 20 were drawn with areas of 78.5 and 314.2 square pixels
Hamilton node-mutates-input A node writes to one of its parameters, and Hamilton hands the same object to other nodes
Python dict-str-any dict[str, Any] in a signature hides the keys the function uses

xpd rules lists every rule, and the rules page shows each one with code before and after.

Install

uv tool install xpd

uvx xpd check . runs it once without an install.

Commands

xpd
├── check [paths]          lint files and folders, and rewrite with --fix
├── scan [paths]           the same lint command as check
├── run [paths]            find a code pattern or syntax kind, and preview or apply a rewrite
├── outline [paths]        show symbols, imports, members and source ranges
├── test                   check rule examples and compare diagnostic and fix snapshots
├── new                    create a project, rule, empty case template or shared utility
├── find "<task>"          find library symbols, rules and worked recipes
├── api <dotted.name>       read a full API or recipe with source and attribution
├── index <source>         refresh symbols and documentation recipes without running Python
├── rules                  list every rule with its documentation
├── graph <files>          print the dataflow of step code or Hamilton modules
├── profile <data file>    print dtypes, nulls, unique counts and memory per column
├── equiv old.py new.py    run two scripts and compare the `result` each one leaves
├── hook                   lint the file that a Claude Code edit touched
├── mcp                    start the MCP server
├── lsp                    start the language server for editors
├── completions <shell>    generate completion from the installed command schema
└── skill                  print the agent skill for this version

find and api search indexes shipped in the binary, including libraries you have not installed. For example, run xpd find "time series bootstrap for cross validation", then xpd api mapie.subsample.BlockBootstrap. find ranks by keywords and by meaning, so a task in your own words also finds an entry whose documentation uses other words. The meaning comes from the EmbeddingGemma model. The first find downloads it once, 333 MB, with the Python that xpd finds, to ~/.cache/xpd/models. On macOS the folder is ~/Library/Caches/xpd/models, on Windows %LOCALAPPDATA%\xpd\models, and with XDG_CACHE_HOME set it is $XDG_CACHE_HOME/xpd/models. After that, search runs offline. When the model cannot be downloaded or loaded, find says so on stderr and searches by keywords only. find ranks symbols, rules and recipes separately, returning up to five, three and three. JSON is {"symbols": [...], "rules": [...], "recipes": [...]}. --limit sets the maximum per kind and --kind selects one kind. Use xpd find "rounded bars" --kind recipe for worked Python examples. Pass a returned recipe name to xpd api to read its code, used symbols, pinned source and license. Recipes are harvested from library documentation and galleries. The harvester applies safe and unsafe fixes and keeps only examples with zero remaining issues from xpd's packs. It never runs the examples. The index command refreshes symbols and recipes together.

check, rules and graph read the files and start no Python. profile and equiv run the project's Python and need pandas there. xpd <command> -h lists the flags of a command. The commands page explains the output and the exit codes.

xpd run --lang python --pattern '$X.iterrows()' . finds structural matches without running Python. Add --rewrite '<replacement>' to preview a replacement, then --interactive to review edits or --update-all to apply every match. --format json returns matches and their source ranges. xpd outline src --format json reads the project's symbols, imports and members without executing it.

check also accepts --format sarif and --format github. Use --fix --review to accept or decline each fix. Unsafe fixes still require --unsafe-fixes.

xpd new project --pack team --yes creates a portable local rule project. Create a rule with xpd new rule team/no-iterrows --pattern '$DF.iterrows()' --message 'Use column operations.' --with-test --yes. The rule's documentation and optional empty case template are created with it. xpd new rule --help lists version bounds, value proofs and fix safety options. xpd new util creates a shared matcher that rules reference with matches.

xpd test checks valid and invalid examples using xpd's own scanner. It uses the project's testConfigs directories from sgconfig.yml. --filter selects rule IDs, --skip-snapshot-tests checks only whether examples match, --interactive reviews snapshot changes and --update-all accepts them all. --engine structural uses the upstream ast-grep runner for structural rule suites and their existing snapshots.

xpd completions bash prints Bash completion. The other shells are zsh, fish, powershell and elvish.

Use in an editor

xpd lsp starts a language server, so an editor shows the issues while you type, with a quick fix for each fixable one and the rule's documentation on hover. The language server page has the setup for Neovim, Helix, Zed and VS Code.

Use with a coding agent

An agent can use xpd as a plugin, or through a hook, an MCP server and skills that you set up one at a time.

Way What the agent gets Setup
Plugin The MCP server and the skills together Load this repository in a client that supports Agent Plugins, such as Codex
Hook The issues of each file, right after the edit xpd hook in the Claude Code settings
MCP server Typed tools, the rules, the skills and prompts xpd mcp
Skills When to run each command, and Python style that a linter cannot check npx skills add bjoernaagaard/xpd

Plugin

This repository is a plugin in the Agent Plugins format, version 1.0.0. A client that supports the format loads the folder and gets the MCP server and the skills. The plugin starts xpd with uvx, so the machine needs uv. Version 1.0.0 has no hooks, so the hook below stays a setting of its own.

xpd, loaded as a plugin
├── plugin.json                         the name and version of the plugin
├── skills/                             xpd, python-best-practices and python-review
├── mcp.json                            starts the MCP server of this version with uvx
└── .agents/plugins/marketplace.json    lists the plugin for Codex

Codex installs it with two commands.

codex plugin marketplace add bjoernaagaard/xpd
codex plugin add xpd@xpd

Hook

After each edit to a .py file, Claude Code sends the edit to xpd hook. When xpd finds issues, Claude Code shows them to the agent in the same turn.

Claude Code edits features.py
└── the PostToolUse hook runs xpd hook
    ├── no issues: exit code 0
    └── issues: exit code 2
        └── Claude Code shows the issues to the agent

Add the hook to .claude/settings.json in your project.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "xpd hook" }]
      }
    ]
  }
}

MCP server

xpd mcp starts an MCP server, so an agent calls xpd through typed tools and needs no shell. The server comes with xpd, and the command below adds it to Claude Code.

claude mcp add xpd -- uvx xpd mcp
xpd mcp
├── tools
│   ├── check, fix                 lint, and write fixes after the user confirms unsafe ones
│   ├── graph, profile, equiv      the commands of the same names
│   ├── find, api                   discover a library for a task and read its API
│   ├── query, rewrite              search code, preview replacements and confirm edits
│   ├── outline                     browse live project symbols and imports
│   ├── new, test                    create rules and check their examples and snapshots
│   ├── rules, rule                list the rules, and read one with its examples
│   ├── contract, gates            judge a run from a data file to a saved model
│   └── show_issues, show_dataflow, show_columns    tables and a chart, in hosts that draw them
├── resources
│   ├── xpd://rules/{package}/{rule}    one rule's documentation
│   └── skill://<name>/SKILL.md         each skill that ships with xpd
└── prompts
    └── lint_and_fix, review, refactor_data_logic, add_to_dataflow, build_pipeline

The server takes every rule and every result from the xpd binary, so it matches the installed version. The MCP page covers other clients, the settings and HTTP. The code mode page is a first draft of a run from a data file to a saved scikit-learn model in one call.

Skills

The repository includes Agent Skills in skills/. The Python skills work without xpd. They also run xpd when it is installed.

Skill What it does
xpd Says when to run each xpd command. xpd skill prints it for the installed version.
python-best-practices Holds the rules an agent follows when it writes or changes Python.
python-review Reviews a file, package or diff, and cites the rule for every finding.
npx skills add bjoernaagaard/xpd

Documentation

The full guide is at https://bjoernaagaard.github.io/xpd/. It also explains how to write a rule.

License

You may use xpd's own code under the MIT license or the Apache-2.0 license. Harvested recipes keep their source licenses, including MIT, BSD-3-Clause, Apache-2.0 and NCSA. Run xpd api <recipe-name> to read the license text, copyright notices, source link and modification status with the code. The licenses/ directory contains the upstream license and notice files shipped in the crate, sdist and wheel. The unmodified option-ext dependency is under MPL-2.0. Its complete source is included as licenses/option-ext-0.2.0-source.tar.gz, with its license in licenses/option-ext-LICENSE.txt. The same source is available from https://crates.io/api/v1/crates/option-ext/0.2.0/download. Package metadata lists the combined licenses of the bundled work. The embedding model that find downloads is not shipped with xpd. It is Gemma, provided under and subject to the Gemma Terms of Use at https://ai.google.dev/gemma/terms.

Metadata

Release files for xpd 0.30.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xpd 0.30.0
File Size Uploaded Provenance Actions
xpd-0.30.0.tar.gz 5.4 MB Without provenance Details for xpd-0.30.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for xpd 0.30.0
File Actions
xpd-0.30.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for xpd-0.30.0-py3-none-win_amd64.whl
xpd-0.30.0-py3-none-musllinux_1_2_x86_64.whl Python 3 none Linux musl 1.2+ x86-64 Details for xpd-0.30.0-py3-none-musllinux_1_2_x86_64.whl
xpd-0.30.0-py3-none-musllinux_1_2_aarch64.whl Python 3 none Linux musl 1.2+ ARM64 Details for xpd-0.30.0-py3-none-musllinux_1_2_aarch64.whl
xpd-0.30.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for xpd-0.30.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
xpd-0.30.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for xpd-0.30.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
xpd-0.30.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for xpd-0.30.0-py3-none-macosx_11_0_arm64.whl
xpd-0.30.0-py3-none-macosx_10_15_x86_64.whl Python 3 none macOS 10.15+ x86-64 Details for xpd-0.30.0-py3-none-macosx_10_15_x86_64.whl

Total release size: 120.1 MB

Release files / xpd-0.30.0.tar.gz

Download URL xpd-0.30.0.tar.gz
Size 5.4 MB
Tags Source
SHA-256 checksum
How to use checksums
b41d7137649771734ed05dce81ad63513534fd3cca69df9caebbba7943556e31
BLAKE2b-256 checksum
How to use checksums
b247c8b04a5439b6bba7cdfcf04021475a41327c962f51e78237d1a79a66edd5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.30.0-py3-none-win_amd64.whl

Download URL xpd-0.30.0-py3-none-win_amd64.whl
Size 16.6 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
65003b898bec39be0479b05a55f29692cb144cc9d94936a86777ff8aace2b7a6
BLAKE2b-256 checksum
How to use checksums
df141669193e0ec33f479a7d9bfbd178a0349c55cf09c519d8a8c6e0c19caafb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.30.0-py3-none-musllinux_1_2_x86_64.whl

Download URL xpd-0.30.0-py3-none-musllinux_1_2_x86_64.whl
Size 16.5 MB
Tags Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
c3aa6c5221dfe421c5a143e2942f2e456f34fc662cd30efd9ae85367faccbc9d
BLAKE2b-256 checksum
How to use checksums
da21845d050191bbbda23bdc4aa152851ddec5d3be34be3f246c4db27a1f4654
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.30.0-py3-none-musllinux_1_2_aarch64.whl

Download URL xpd-0.30.0-py3-none-musllinux_1_2_aarch64.whl
Size 16.1 MB
Tags Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
bcde4bb4a3fdb931feedac2a04e88c35b13f257edaa8c1e097e0c78a3e38e542
BLAKE2b-256 checksum
How to use checksums
6af5adb5b63ecaf0ab42cda1ce4f5c0116fb30eef12930588310cc0c2e836be3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.30.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL xpd-0.30.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 16.6 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
d263ce9f2ad29192c155bc030e2dee64c58098418f63f35242137d58f955945d
BLAKE2b-256 checksum
How to use checksums
21be85f521a8ec12f599add48798ce9129adcc98dfc1b8466aafee30a8a620f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.30.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL xpd-0.30.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 16.2 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
3f08ac19e912d0925b6473f135cb216b3209543ff4eddc5b6ac426554474b375
BLAKE2b-256 checksum
How to use checksums
a758c31f4d766eb354b06b883ed26ba2b749939b0e098dc2b548e5e1d81eeead
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.30.0-py3-none-macosx_11_0_arm64.whl

Download URL xpd-0.30.0-py3-none-macosx_11_0_arm64.whl
Size 16.4 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0a20f2ec67b8a04ed5b8f1bd1636767a22b10b1193b6033f54ba565e88086e61
BLAKE2b-256 checksum
How to use checksums
a66d15e2a64ad7a1a36dd5456c8dc19d370c783eefab6c6dd9eceae30462a7ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / xpd-0.30.0-py3-none-macosx_10_15_x86_64.whl

Download URL xpd-0.30.0-py3-none-macosx_10_15_x86_64.whl
Size 16.4 MB
Tags Python 3 macOS 10.15+ x86-64
SHA-256 checksum
How to use checksums
8a55258bb0db061f40445882b1ccc2e38f88f474efb64d78f0f81f1ab8a04a6a
BLAKE2b-256 checksum
How to use checksums
4c370e78b4d7ca6b2f406c84da3f9e40d25b155678be2ef17e89d54e0123e96e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for xpd 0.30.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.30.0 This release

8 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page