
Mission 3 of 6
Ship your first release: pip install in one command.
Most projects stall between 'works on my machine' and 'pip install jdx'. You'll package yours, test it on a machine that has never seen your code, and publish it by pushing a git tag.
What you'll do
Write a pyproject.toml, build the wheel, and install it locally to prove the command works.
Publish to the practice index first, because a version on the real PyPI can never be reused.
Set up trusted publishing and a GitHub Actions workflow that tests, builds and publishes with no token stored.
- A clean-machine test in Docker
- The npm version of every step, for Node projects
- The repo from a repo people trust in ten seconds with
v0.1.0tagged. You'll re-release as0.1.1here uvinstalled (curl -LsSf https://astral.sh/uv/install.sh | sh, orirm https://astral.sh/uv/install.ps1 | iexon Windows). It handles Python versions, venvs, building and publishing- A PyPI account and a TestPyPI account (they're separate), both with two-factor on. Verify the emails before step 4
- Docker for the clean-machine test. Docker without fear if it's new to you. Optional but worth it
Your progress0/6
- 01The project layout and pyproject.toml12 min
- 02Build the wheel and install it locally8 min
- 03Dry run on TestPyPI10 min
- 04Trusted publishing: PyPI trusts your GitHub workflow, no token10 min
- 05The release workflow: push a tag, get a release12 min
- 06Test on a machine that has never seen your code, then the npm variant10 min
The project layout and pyproject.toml
One config file that defines the package, the command and the version, so building and publishing need no other setup.
You start by getting the project into the right shape for packaging: a layout and one config file.
Python packaging had a decade of competing tools. Today the answer for a new project is a pyproject.toml with the hatchling build backend, driven by uv. No setup.py, no setup.cfg, no requirements.txt.
If your project is already laid out differently, don't restructure in a panic; the src/ layout below is the recommended one because it stops tests importing your code from the working directory instead of the installed package, which hides packaging bugs.
The layout
Arrange your project like this:
Layoutjdx/ pyproject.toml README.md LICENSE CHANGELOG.md src/jdx/ __init__.py cli.py tests/ test_cli.pyIf you're starting from nothing,
uv init --package jdxcreates this shape. If you have an existing repo, create the folders by hand and write the config.
The config file
Write
pyproject.tomlin the project root. Here's the whole file for the worked example:pyproject.toml[project] name = "jdx" version = "0.1.0" description = "Diff two JSON files, ignoring key order and noise" readme = "README.md" license = "MIT" license-files = ["LICENSE"] requires-python = ">=3.10" authors = [{ name = "Your Name" }] keywords = ["json", "diff", "cli"] classifiers = [ "Programming Language :: Python :: 3", "Environment :: Console", ] dependencies = [] [project.urls] Homepage = "https://github.com/OWNER/jdx" Changelog = "https://github.com/OWNER/jdx/blob/main/CHANGELOG.md" [project.scripts] jdx = "jdx.cli:main" [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [dependency-groups] dev = ["pytest", "ruff"]The lines that matter:
[project.scripts]turns a function into thejdxcommand on the user's PATH after install.readmemakes your README the PyPI page.requires-pythonstops people installing on a version you don't test.license-filesships the LICENSE inside the wheel, which some corporate scanners require.versionlives here and only here; the CLI reads it withimportlib.metadataso you never have two numbers to keep in sync.
Something to ship
The rest of the mission needs something to ship, so here is a small real CLI and a test. Yours replaces this; keep the main(argv=None) shape, it's what makes the command and the tests share one entry point.
Create the CLI at
src/jdx/cli.py:src/jdx/cli.py"""jdx: diff two JSON files ignoring key order.""" import argparse import json import sys from fnmatch import fnmatch from importlib.metadata import version def _strip(obj, ignore, path=""): if isinstance(obj, dict): return { k: _strip(v, ignore, f"{path}.{k}" if path else k) for k, v in sorted(obj.items()) if not any(fnmatch(f"{path}.{k}" if path else k, pat) for pat in ignore) } if isinstance(obj, list): return [_strip(v, ignore, f"{path}[]") for v in obj] return obj def _diff(a, b, path=""): if isinstance(a, dict) and isinstance(b, dict): for k in sorted(set(a) | set(b)): p = f"{path}.{k}" if path else k if k not in a: print(f"+ {p}: {json.dumps(b[k])}") elif k not in b: print(f"- {p}: {json.dumps(a[k])}") else: yield from _diff(a[k], b[k], p) elif a != b: print(f"~ {path}: {json.dumps(a)} -> {json.dumps(b)}") yield 1 def main(argv=None): ap = argparse.ArgumentParser(prog="jdx", description=__doc__) ap.add_argument("old") ap.add_argument("new") ap.add_argument("--ignore", action="append", default=[], metavar="PATH") ap.add_argument("--exit-code", action="store_true", help="exit 1 if files differ") ap.add_argument("--version", action="version", version=version("jdx")) args = ap.parse_args(argv) with open(args.old) as f: a = _strip(json.load(f), args.ignore) with open(args.new) as f: b = _strip(json.load(f), args.ignore) changed = sum(_diff(a, b)) or (a != b) if args.exit_code and changed: sys.exit(1)Create the test at
tests/test_cli.py:tests/test_cli.pyimport json from jdx.cli import main def test_ignores_key_order(tmp_path, capsys): a = tmp_path / "a.json" b = tmp_path / "b.json" a.write_text(json.dumps({"x": 1, "y": 2})) b.write_text(json.dumps({"y": 2, "x": 1})) main([str(a), str(b)]) assert capsys.readouterr().out == "" def test_reports_change(tmp_path, capsys): a = tmp_path / "a.json" b = tmp_path / "b.json" a.write_text(json.dumps({"x": 1})) b.write_text(json.dumps({"x": 2})) main([str(a), str(b)]) assert "~ x: 1 -> 2" in capsys.readouterr().outsrc/jdx/__init__.pycan be empty. Add.venv/,dist/and__pycache__/to.gitignoreif they aren't already.
uv sync completes, creates .venv, and uv run pytest -q reports 2 passed.If it breaksuv run pytest can't import jdx + 1 more
uv run pytest can't import jdx
uv sync installs your project in editable mode only if pyproject.toml has a [build-system] section; check it's there and the folder is src/jdx/ (the name must match [project] name, with hyphens turned into underscores).I want to add a dependency
uv add requests writes it into dependencies and the lockfile. Commit uv.lock; it makes CI reproducible. Dev-only tools go in [dependency-groups] dev via uv add --dev.