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. 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
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
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 records the commit that the session began at
user sends a prompt xpd prints nothing in this version
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.
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 | 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.40.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xpd-0.40.0.tar.gz | 5.9 MB | Without provenance | Details for xpd-0.40.0.tar.gz |
Built distributions (wheels)
Total release size: 126.6 MB
Release files / xpd-0.40.0.tar.gz
| Download URL | xpd-0.40.0.tar.gz |
|---|---|
| Size | 5.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a754dc7649ffda193e40167d0b57f161cc6034da36c212eea0108fde9926801c
|
|
BLAKE2b-256 checksum How to use checksums |
8357f4c967976e36cf5eeb6c189fb6ce1c6bbcd4f9df3e8af02db9ea041422ac
|
| 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.40.0-py3-none-win_amd64.whl
| Download URL | xpd-0.40.0-py3-none-win_amd64.whl |
|---|---|
| Size | 17.4 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
519306e1babd0f76497a8c55f0c5e93877c74a7421882c5a835c76a3c51c828e
|
|
BLAKE2b-256 checksum How to use checksums |
0de2aa44c20ebe5ee8788551cb2b61120a5712e7cdadb0337a477c2deea67f57
|
| 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.40.0-py3-none-musllinux_1_2_x86_64.whl
| Download URL | xpd-0.40.0-py3-none-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 17.3 MB |
| Tags | Linux musl 1.2+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
8e47650a0276e953259262138ad96a6e20e4d67ed97b24505423d1d5d0f0db5d
|
|
BLAKE2b-256 checksum How to use checksums |
734233f43b96836f8703f5e95c666bd010b38095c188f2ce049c4fe200b4117a
|
| 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.40.0-py3-none-musllinux_1_2_aarch64.whl
| Download URL | xpd-0.40.0-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 |
2bd09f6b4a577f96dee173e7697724758fed80db7d4338d365eeecc734a4ae94
|
|
BLAKE2b-256 checksum How to use checksums |
dd6b54ec38c13acec036e297b6d32a57c45100016751eeae2944e9d11dbadf8e
|
| 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.40.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | xpd-0.40.0-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 |
00541c2d41ca8eafb9e09786ed53e06b03940638eb94c51f728713c33d5e9eb8
|
|
BLAKE2b-256 checksum How to use checksums |
9473f1dea36d2c5ae5dd4c8d74dce71a582f891dd54d1da6c843b83f5c63c3eb
|
| 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.40.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | xpd-0.40.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 17.0 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
15b40e5aaca669c89a39f9f8eec37dde16b4041643800efeb85a36029a163b85
|
|
BLAKE2b-256 checksum How to use checksums |
909834ac0d224f650f313071e0a129e25e03f6882f8b9a0512ad4e6557f6e3d7
|
| 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.40.0-py3-none-macosx_11_0_arm64.whl
| Download URL | xpd-0.40.0-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 |
7a7f3db6a5427cee2decc28b8e1140c76243133ec0ab5d858ae3b3efb4d1526e
|
|
BLAKE2b-256 checksum How to use checksums |
96f2894c078e8636d0d6b7b40f82014287fa8c8283f2bd2a0774fb30d71bb2ce
|
| 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.40.0-py3-none-macosx_10_15_x86_64.whl
| Download URL | xpd-0.40.0-py3-none-macosx_10_15_x86_64.whl |
|---|---|
| Size | 17.3 MB |
| Tags | Python 3 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
523896295a0199069836d92090d7af49f146fc8baedee1b7bcbafa5c90a56628
|
|
BLAKE2b-256 checksum How to use checksums |
ddfb16001d8c52ad854a0a1e0330a040ad48ca5a1a48aa8e51b9b5ef887123e8
|
| 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.40.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.