Packaging and Shipping 📦

The shape of a package

crew-manager/
├── pyproject.toml          the one config file that matters
├── README.md               what it is, shown on PyPI
├── LICENSE                 without one, nobody may legally use it
├── .gitignore
├── src/
│   └── crew_manager/
│       ├── __init__.py     makes it a package; holds the version
│       ├── core.py
│       └── cli.py
└── tests/
    ├── test_core.py
    └── test_cli.py

pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "crew-manager"
version = "0.1.0"
description = "Manage a pirate crew from the command line."
readme = "README.md"
requires-python = ">=3.11"
license = "MIT"
authors = [{ name = "Your Name" }]
keywords = ["cli", "pirates"]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
dependencies = [
    "rich>=13.0",
]

[project.optional-dependencies]
dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.10"]

[project.scripts]
crew = "crew_manager.cli:main"

[project.urls]
Homepage = "https://github.com/you/crew-manager"
Issues = "https://github.com/you/crew-manager/issues"

That [project.scripts] line is the good bit: after installing, the user gets a crew command on their PATH that calls your main function. It is how pytest, ruff and pip itself are installed.

Installing your own package while you work on it

$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -e ".[dev]"

Successfully installed crew-manager-0.1.0 (editable)

$ crew --help
usage: crew [-h] {add,list,remove} ...

-e means editable: the package is installed as a link to your source, so your edits take effect immediately with no reinstall. .[dev] also pulls in the optional development dependencies. This is the first command to run in any Python project you clone.

Building and publishing

$ pip install build twine
$ python -m build

Successfully built crew_manager-0.1.0.tar.gz and
                   crew_manager-0.1.0-py3-none-any.whl

# ALWAYS publish to the test index first
$ twine upload --repository testpypi dist/*
$ pip install --index-url https://test.pypi.org/simple/ crew-manager

# then, when you are sure
$ twine upload dist/*

Version numbers mean something

This is semantic versioning, and it is a promise to the people installing your package. Breaking it, by changing behaviour in a patch release, is the fastest way to lose users' trust, because their code broke while they were doing nothing wrong.

Automating the checks

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install
        run: pip install -e ".[dev]"

      - name: Lint
        run: ruff check .

      - name: Format check
        run: ruff format --check .

      - name: Type check
        run: mypy src

      - name: Test
        run: pytest -v

Every push now runs your tests on three Python versions, on a clean machine, before you can merge. That last part is the real value: it catches "works on my machine" the moment it happens, and it proves your package installs from scratch.

Before you publish anything

• A README that shows installation and one working example in the first screen
• A LICENSE file. Without one, the legal default is that nobody may use it
• Tests that pass on a clean machine, not just yours
• A name nobody has taken, checked on PyPI
• requires-python set honestly
• Version 0.1.0, not 1.0.0, unless you mean it
• No secrets, no API keys, no personal paths in the source
• Uploaded to TestPyPI and installed from there successfully

# src/wordtools/__init__.py
"""Small text statistics helpers."""

__version__ = "0.1.0"

from .core import word_count, most_common

__all__ = ["word_count", "most_common"]

# src/wordtools/cli.py
"""Command-line entry point."""

import argparse
import sys
from pathlib import Path

from .core import most_common, word_count


def main(argv=None) -> int:
    parser = argparse.ArgumentParser(prog="wordtools")
    parser.add_argument("file", type=Path)
    parser.add_argument("-n", "--top", type=int, default=3)
    args = parser.parse_args(argv)

    try:
        text = args.file.read_text(encoding="utf-8")
    except FileNotFoundError:
        print(f"wordtools: no such file: {args.file}", file=sys.stderr)
        return 1

    print(f"{word_count(text)} words")
    for word, count in most_common(text, args.top):
        print(f"  {count:4}  {word}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

pip install -e ".[dev]"
wordtools README.md --top 5