xpd
xpd checks Python code for slow operations and wrong results. It checks code that uses pandas, NumPy, SciPy, scikit-learn 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 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 |
| 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
├── 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
└── skill print the agent skill for this version
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.
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
│ ├── rules, rule list the rules, and read one with its examples
│ └── 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
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.
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 under the MIT license or the Apache-2.0 license.
Metadata
Release files for xpd 0.14.1
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.14.1.tar.gz | 355.6 kB | Without provenance | Details for xpd-0.14.1.tar.gz |
Built distributions (wheels)
Total release size: 18.7 MB
Release files / xpd-0.14.1.tar.gz
| Download URL | xpd-0.14.1.tar.gz |
|---|---|
| Size | 355.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
43eb94079e93ee03adc2edabeb163040ca33f1d0511f0286654d398d7cb8d2ea
|
|
BLAKE2b-256 checksum How to use checksums |
ec72c3fe2b80fc3b1902e4b8fb678441e47b95295815773ede5f07079612ea35
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / xpd-0.14.1-py3-none-win_amd64.whl
| Download URL | xpd-0.14.1-py3-none-win_amd64.whl |
|---|---|
| Size | 2.7 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7cb9326ecae07f2256b75147fb6e04189ab1a5aaed1d153cb6b59e0bda5f3320
|
|
BLAKE2b-256 checksum How to use checksums |
7148ec29d1d5af2552fe022f196d696459964b09d38c432f0622adfa07ef2076
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / xpd-0.14.1-py3-none-musllinux_1_2_x86_64.whl
| Download URL | xpd-0.14.1-py3-none-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | Linux musl 1.2+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
bd9151b02967504649c67d41d2d91464ce97318fdcb0a95ec41d38a3ae98cabc
|
|
BLAKE2b-256 checksum How to use checksums |
a52d9c3897fdc42cfbbc302511de14c94b24415eeb08262778b9979b3c4783eb
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / xpd-0.14.1-py3-none-musllinux_1_2_aarch64.whl
| Download URL | xpd-0.14.1-py3-none-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 2.5 MB |
| Tags | Linux musl 1.2+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
9af6217cff2808136808ea0b694fad82273c1ff51276545c125ef64d96b27142
|
|
BLAKE2b-256 checksum How to use checksums |
e9d5d36bdb8306097d1dc57c9a1201fa9765f0313ec3ce033bdb5bf8cd6c3fc7
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / xpd-0.14.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | xpd-0.14.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 2.7 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
5cdc6bbb5a468ae2963ab27e7252c2ab67a169d9eb31ef4dc1f2e7157d343f65
|
|
BLAKE2b-256 checksum How to use checksums |
a1f92575018b583b19b5ad4fa4d8c2da39e415d11e19e78bd6b461944a1ef074
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / xpd-0.14.1-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | xpd-0.14.1-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 2.5 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
bbecf720f226cc79839bb794ffbacaa7b92a1ff484226d30ff1f3cfb43de9470
|
|
BLAKE2b-256 checksum How to use checksums |
216cbc434c6764a81a52153cd18243c1a89fd3282008d0b3a1866b7709e5f1b5
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / xpd-0.14.1-py3-none-macosx_11_0_arm64.whl
| Download URL | xpd-0.14.1-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.5 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d4eca752955d13e369dc70a3766a9d281c639d86e344b0d99c51d35e1dc010e6
|
|
BLAKE2b-256 checksum How to use checksums |
1612e43fc8e045eaf03a7685d3800d5cac69f800fb2b49fa6588bae066121c55
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / xpd-0.14.1-py3-none-macosx_10_12_x86_64.whl
| Download URL | xpd-0.14.1-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 2.6 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
8853285d08b4bc118df62f9dce3499536dedc6dbf59bd58dadfc4f9367653786
|
|
BLAKE2b-256 checksum How to use checksums |
72928f71564bf3c6aa5e2613c20cad242a620a361fb01a61e6c240aec430c38d
|
| 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for xpd 0.14.1
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.