Get Started
Open source that pays

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.

70 minIntermediateFreeStep 1 free

What you'll do

Package it with one config file

Write a pyproject.toml, build the wheel, and install it locally to prove the command works.

Rehearse on TestPyPI

Publish to the practice index first, because a version on the real PyPI can never be reused.

Publish by pushing a tag

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
Before you start
  • The repo from a repo people trust in ten seconds with v0.1.0 tagged. You'll re-release as 0.1.1 here
  • uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh, or irm https://astral.sh/uv/install.ps1 | iex on 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
01/06The project layout and pyproject.toml0 done
STEP 01 of 06~12 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

  1. Arrange your project like this:

    Layout
    jdx/
      pyproject.toml
      README.md
      LICENSE
      CHANGELOG.md
      src/jdx/
        __init__.py
        cli.py
      tests/
        test_cli.py

    If you're starting from nothing, uv init --package jdx creates this shape. If you have an existing repo, create the folders by hand and write the config.

The config file

  1. Write pyproject.toml in 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 the jdx command on the user's PATH after install.
    • readme makes your README the PyPI page.
    • requires-python stops people installing on a version you don't test.
    • license-files ships the LICENSE inside the wheel, which some corporate scanners require.
    • version lives here and only here; the CLI reads it with importlib.metadata so 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.

  1. 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)
  2. Create the test at tests/test_cli.py:

    tests/test_cli.py
    import 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().out

    src/jdx/__init__.py can be empty. Add .venv/, dist/ and __pycache__/ to .gitignore if they aren't already.

Checkpoint
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
The package isn't installed into the venv. 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.
Still stuck? Ask the community
Next mission · Open source that paysLaunch it: Show HN, the right subreddits, Product Hunt and a 48 hour reply plan
→