Metadata-Version: 2.4
Name: xpd
Version: 0.18.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: fastmcp[anthropic,apps,azure,code-mode,gemini,jev,openai,tasks]~=4.2.0
Requires-Dist: prefab-ui==0.21.1
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
License-File: licenses/arch-LICENSE.md
License-File: licenses/category_encoders-LICENSE.md
License-File: licenses/hamilton-DISCLAIMER
License-File: licenses/hamilton-LICENSE
License-File: licenses/hamilton-NOTICE
License-File: licenses/linearmodels-LICENSE.md
License-File: licenses/mapie-LICENSE
License-File: licenses/mapie-THIRD_PARTY_NOTICES.md
License-File: licenses/numpy-LICENSE.txt
License-File: licenses/pandas-LICENSE
License-File: licenses/plotly-LICENSE.txt
License-File: licenses/pymoo-LICENSE
License-File: licenses/scipy-LICENSE.txt
License-File: licenses/sklearn-COPYING
License-File: licenses/sklego-LICENSE
Summary: Fast, opinionated linter for Python library habits, starting with pandas, NumPy, SciPy and scikit-learn, for humans and coding agents
Keywords: pandas,python,linter,ast-grep,agents
Home-Page: https://bjoernaagaard.github.io/xpd/
License-Expression: MIT AND Apache-2.0 AND BSD-3-Clause AND NCSA
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://bjoernaagaard.github.io/xpd/
Project-URL: Repository, https://github.com/bjoernaagaard/xpd

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

```diff
 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.

```text
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 |
| 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](https://bjoernaagaard.github.io/xpd/rules/)
shows each one with code before and after.

## Install

```sh
uv tool install xpd
```

`uvx xpd check .` runs it once without an install.

## Commands

```text
xpd
├── check [paths]          lint files and folders, and rewrite with --fix
├── 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
└── skill                  print the agent skill for this version
```

`find` and `api` search indexes shipped in the binary, including libraries you have not
installed. Search is offline and uses keywords. For example, run `xpd find "time series bootstrap
for cross validation"`, then `xpd api mapie.subsample.BlockBootstrap`.
`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](https://bjoernaagaard.github.io/xpd/commands/#index) 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](https://bjoernaagaard.github.io/xpd/commands/) explains the output and the exit
codes.

## 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](https://bjoernaagaard.github.io/xpd/lsp/) 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](https://github.com/agentplugins/agent-plugins-spec)
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](https://docs.astral.sh/uv/). Version 1.0.0 has no hooks, so the hook below stays a setting
of its own.

```text
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.

```sh
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.

```text
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.

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

### MCP server

`xpd mcp` starts an [MCP](https://modelcontextprotocol.io) 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.

```sh
claude mcp add xpd -- uvx xpd mcp
```

```text
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
│   ├── 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](https://bjoernaagaard.github.io/xpd/mcp/) covers other clients, the
settings and HTTP. The [code mode page](https://bjoernaagaard.github.io/xpd/code-mode/) 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](https://agentskills.io) 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. |

```sh
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.
Package metadata lists the combined licenses of the bundled work.

