Skip to main content

xpd

Run uvx xpd check . to find the lines of your Python code that are slow or give a wrong result, and add --fix to let xpd rewrite the ones it can. xpd checks code that uses pandas, NumPy, SciPy, scikit-learn, scikit-lego, MAPIE, Category Encoders, linearmodels, arch, pymoo, plotly or Apache Hamilton. It reads the files and starts no Python, so you or a coding agent can run it after every edit.

The documentation is at https://bjoernaagaard.github.io/xpd/, with a page for every rule.

Install

Install the xpd command with uv.

uv tool install xpd

You can also run xpd once without installing it, with uvx xpd in place of xpd.

Check a file and fix it

Save the following code as bad.py in an empty folder. xpd reads the code and doesn't run it, so you don't need pandas.

import pandas as pd

df = pd.DataFrame({"a": [1, 2], "k": [1, 2]})
other = df.copy()
for i, row in df.iterrows():
    df["a"][i] = row["a"] * 2
df.dropna(inplace=True)
m = pd.merge(df, other, on="k")
out = pd.DataFrame()
for f in ["x.csv"]:
    out = pd.concat([out, pd.read_csv(f)])

Run xpd on the file. On a terminal --format text is the default, and elsewhere xpd prints JSON. It prints one line for each issue, with the place, the severity, the rule and what to write instead, and it exits with 1 because one issue is an error.

$ xpd check bad.py --format text
bad.py:5:15: warning [pandas/row-loop] iterrows() builds a Series for every row. Compute on whole columns instead, such as df["a"] * df["w"]. When each row has to become a Python object, loop over itertuples() or to_dict("records").
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.
bad.py:7:1: info [pandas/no-inplace] inplace=True gives no speedup and blocks chaining. Reassign instead.
bad.py:8:5: warning [pandas/merge-without-validate] merge without validate= can silently duplicate rows.
bad.py:11:5: warning [pandas/concat-in-loop] out grows by one concat per pass, and each concat copies every earlier row. Collect the frames in a list and concat once after the loop.
xpd: 5 issues, 2 more with --fix --unsafe-fixes

Fix every error, and fix a warning unless you can say why the code is right in that place.

Severity Meaning
error The code gives a wrong result or raises an exception
warning The code is slow or easy to get wrong
info A shorter or newer form exists

xpd check bad.py --fix writes the safe fixes, which keep what the code does. None of the five issues has one, so the file stays as it was. --unsafe-fixes adds the fixes that may change what the code does, so read the diff after you use it.

$ xpd check bad.py --fix --unsafe-fixes --format text
bad.py:5:15: warning [pandas/row-loop] iterrows() builds a Series for every row. Compute on whole columns instead, such as df["a"] * df["w"]. When each row has to become a Python object, loop over itertuples() or to_dict("records").
bad.py:8:5: warning [pandas/merge-without-validate] merge without validate= can silently duplicate rows.
bad.py:11:5: warning [pandas/concat-in-loop] out grows by one concat per pass, and each concat copies every earlier row. Collect the frames in a list and concat once after the loop.
xpd: fixed 2, 3 issues

xpd rewrote lines 6 and 7 and exited with 0, because no error is left.

 for i, row in df.iterrows():
-    df["a"][i] = row["a"] * 2
-df.dropna(inplace=True)
+    df.loc[i, "a"] = row["a"] * 2
+df = df.dropna()

Under pandas copy-on-write, the old line 6 left df unchanged, and the new line writes the doubled values into df. xpd check exits with 0 when it finds no error, with 1 when it finds one, and with 2 when it can't run. The Get started page explains each part of an issue.

Rules

Each library has a pack of rules, and a pack runs only on a file that imports its library. The Python pack runs on every file. Each rule has a page that says what goes wrong, what to write instead and whether xpd can fix it, such as pandas/chained-assignment.

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 scored 0.997 AUC on data with no signal
MAPIE calibrate-on-training-rows conformalize on the training rows covered 0.468 of the test rows where 0.9 was asked
plotly marker-size-diameter A marker's size is its diameter, so markers of size 10 and 20 had areas of 78.5 and 314.2 square pixels
Python dict-str-any dict[str, Any] in a signature hides the keys the function uses

xpd rules lists every rule, and the rules overview lists the packs with their counts.

Some info rules state a preference of the house style, such as one method chain where the code builds a frame in separate steps. Set style to make xpd report them as warnings, in [tool.xpd] of the project's pyproject.toml or at the top of ~/.config/xpd/config.toml. xpd check describes the setting.

[tool.xpd]
style = "strict"

Commands

xpd <command> -h lists the options of a command, and the command reference has a page for each one.

xpd
├── lint
│   ├── check [paths]          lint files and folders, and rewrite with --fix
│   ├── rules                  list every rule with its documentation
│   └── hook                   answer an agent's session: lint each edit, and hold a turn that leaves errors or warnings
├── look up a library
│   ├── find "<task>"          find library symbols, rules and worked examples for a task
│   ├── api <name>             read one symbol, method or worked example in full
│   └── index <source>         build a search index from library source
├── read and rewrite code
│   ├── run [paths]            find a code pattern, and preview or apply a rewrite
│   ├── outline [paths]        show imports, definitions and members with line numbers
│   └── graph <files>          print the dataflow of step code or Hamilton modules
├── run the project's Python
│   ├── 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
│   └── refit <contract>       refit a saved Pipeline on raw training rows and compare
├── write your own rules
│   ├── new                    create a rule project, a rule, a test case or a utility
│   └── test                   check rule examples and compare snapshots
└── connect a tool
    ├── mcp                    start the MCP server for agents
    ├── lsp                    start the language server for editors
    ├── skill                  print the agent skill for the installed version
    ├── doctor                 suggest Ruff, ty and pytest settings for the project
    └── completions <shell>    print shell completion

profile, equiv and refit run the project's Python, so they need pandas in the project's environment. index runs Python with Griffe, and the first find downloads a 333 MB search model once. Every other command only reads files.

Use xpd with an agent or an editor

You want Do Guide
An agent to see the issues of each file it edits, and to keep working while one has an error or a warning Install the plugin, or add xpd hook to the agent's hooks Claude Code and other agents
An agent to call xpd's tools claude mcp add xpd -- uvx xpd mcp Connect an agent with MCP
The hook, the MCP server and the skills in one step Install this repository as a plugin in Claude Code or Codex Agent plugin
An agent to know when to run each command npx skills add bjoernaagaard/xpd Agent skill
An agent to train a scikit-learn model with checks xpd mcp --code-mode Train a model in code mode
Issues, fixes and rule help in your editor Start xpd lsp from the editor Use xpd in an editor
A rule for your own project xpd new rule Write a rule

Install the plugin in Claude Code with the following commands. The guide has the commands for Codex.

claude plugin marketplace add bjoernaagaard/xpd
claude plugin install xpd@xpd

The plugin runs xpd hook at four points of a session.

session starts        xpd prints which rule packs apply, the style setting,
                      and the pipelines and Hamilton nodes of the project
user sends a prompt   xpd prints the playbook that answers the prompt, such as
                      xpd/recipe/plotly-chart for "improve my charts",
                      or the open issues when the prompt asks what to improve
agent edits a file    xpd reports the issues of that file
agent wants to stop   xpd lints every Python file the session changed,
                      and holds the turn while one has an error or a warning

With style = "strict", a rule of the house style counts as a warning, so the agent also keeps working until the code is in the style.

A playbook is one of xpd's own recipes. It holds the house style for a kind of task as a complete module, with the commands to run in order and the rules that the code satisfies. xpd find "<task>" returns a playbook when the task fits it, and xpd api <name> prints it.

Playbook What its code is
xpd/recipe/pandas-pipeline Step functions that each return frame.assign(...), joined with pipe
xpd/recipe/feature-module One typed function for each feature, named for the column it returns
xpd/recipe/linear-script A script that changed a frame line by line, as one chain that xpd equiv proves equal
xpd/recipe/plotly-chart A line chart that reports no issue of the plotly pack

License

You may use xpd's own code under the MIT license or the Apache-2.0 license, and the other parts that ship with xpd keep the licenses in the table.

Part License Where the text is
xpd's own code and its playbooks MIT or Apache-2.0, as you choose LICENSE-MIT and LICENSE-APACHE
Recipes, which are examples taken from library documentation The license of the library, which is MIT, BSD-3-Clause, Apache-2.0 or NCSA licenses/, one file per library. xpd api <recipe> prints the license name and the source link with the code
option-ext, a dependency shipped unmodified MPL-2.0 licenses/option-ext-LICENSE.txt, with the complete source in licenses/option-ext-0.2.0-source.tar.gz and at https://crates.io/api/v1/crates/option-ext/0.2.0/download
libcst, the parser that checks a fixed file MIT, with parts of CPython under PSF-2.0 licenses/libcst-LICENSE
EmbeddingGemma, the model that find downloads The Gemma Terms of Use at https://ai.google.dev/gemma/terms Not shipped with xpd

The licenses/ folder ships in the crate, the sdist and the wheel, and the package metadata lists the combined licenses.

Metadata

Release files for xpd 0.41.5

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.41.5
File Size Uploaded Provenance Actions
xpd-0.41.5.tar.gz 6.0 MB Without provenance Details for xpd-0.41.5.tar.gz

Built distributions (wheels)

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

Total release size: 127.0 MB

Release files / xpd-0.41.5.tar.gz

Download URL xpd-0.41.5.tar.gz
Size 6.0 MB
Tags Source
SHA-256 checksum
How to use checksums
f6801107864f3d1d9a4f7782e5979e72be2f744fd415c168c933706e68528fc9
BLAKE2b-256 checksum
How to use checksums
03ba0c9e68eb6c6b00392d59f023b7b0e5e93d1745ad6217f180f30d0e8d5e4a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5-py3-none-win_amd64.whl

Download URL xpd-0.41.5-py3-none-win_amd64.whl
Size 17.5 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
7c705296b6426341c4e17388151eecfddb7d5f7e32637d94a584d4da39e88bd1
BLAKE2b-256 checksum
How to use checksums
f314023b4a7f5e8d3573766a2c4c9e46c0cc8486baa9c58333028b8944ae4f1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5-py3-none-musllinux_1_2_x86_64.whl

Download URL xpd-0.41.5-py3-none-musllinux_1_2_x86_64.whl
Size 17.4 MB
Tags Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
b54a3d2306ebacaac618f209770cf9e050a95ea9d2aa1117974e70a70bd1d771
BLAKE2b-256 checksum
How to use checksums
7c9737400fd3eb8ccd36a6568fed1f8df61aeb883f9fc63cbd915d7be4049a65
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5-py3-none-musllinux_1_2_aarch64.whl

Download URL xpd-0.41.5-py3-none-musllinux_1_2_aarch64.whl
Size 16.9 MB
Tags Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
37ef62c6a53cd3e44a1be5dc80402ccd5eb4ea07ea70cddab1adc00a1208b81a
BLAKE2b-256 checksum
How to use checksums
88c06e2371a69a3e3fc82007c5c7b8759614cb4268a2c23a9cca16c54b4746ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL xpd-0.41.5-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 17.5 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
ab79e1a154c9a9b79f638318976c4b016464d235e6630184f0c53640a70b8fac
BLAKE2b-256 checksum
How to use checksums
350bb7b31ea5834defb64bbbb563e86c36c1900fe5bbfd7ef2c9934aa6f0165d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL xpd-0.41.5-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 17.1 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
b849f8f6c4ec1e0a40f0e9d28efb0d294b6cd3bfd86f6c93596418f2cc75ca27
BLAKE2b-256 checksum
How to use checksums
abb143376ee397ad9d272ec56ac0c5c3c0c5bf4a67fbc8c2ee9795b5c4fce4e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5-py3-none-macosx_11_0_arm64.whl

Download URL xpd-0.41.5-py3-none-macosx_11_0_arm64.whl
Size 17.3 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
db1829cbe6d4cf1fc3e74457c374840562d60021543a50b5252e419d67b37198
BLAKE2b-256 checksum
How to use checksums
05fe63db0f6d1074d093e6e0925d9e81e2ed75f07764b6c377e200cf0e9d88d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5-py3-none-macosx_10_15_x86_64.whl

Download URL xpd-0.41.5-py3-none-macosx_10_15_x86_64.whl
Size 17.4 MB
Tags Python 3 macOS 10.15+ x86-64
SHA-256 checksum
How to use checksums
45cdb37895c0505ffd855b89cba2822ab561873ea86dae6c849c657a70445d12
BLAKE2b-256 checksum
How to use checksums
adbe498442de8e07a618cf7dd1e9371f7b6937a7ce6611a948a0028495cf97d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.41.5

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.41.5 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