Packaging in Python

Write a minimal pyproject.toml with a console entry point and install your utility with pip install -e . for local development.

The concepts are clear. Now write the actual files.

The project layout

A packageable utility needs a minimal directory structure. For the CSV extractor from the lab, it looks like this:

my-extractor/
├── pyproject.toml
└── extract.py

That is it for a single-file tool. pyproject.toml sits next to your source file. For larger tools with multiple files you would put the source in a subdirectory (a proper package), but one file plus one config is enough to start.

A complete pyproject.toml

Here is a working pyproject.toml for the CSV extractor:

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.backends.legacy:build"

[project]
name = "csv-extract"
version = "0.1.0"
description = "Extract a named column from CSV input."
requires-python = ">=3.9"

[project.scripts]
csv-extract = "extract:main"

Key points:

name = "csv-extract" is the package name that pip knows. It does not have to match the filename.
csv-extract = "extract:main" creates a command called csv-extract that calls main() in extract.py. The left side is the terminal command; the right side is filename_without_extension:function_name.
requires-python = ">=3.9" is optional but good practice — it stops pip from installing on an incompatible Python.

Editable installs

During development, you want changes to extract.py to take effect immediately without reinstalling. That is what editable mode (-e) does:

pip install -e .

Run this once from the my-extractor/ directory. Pip installs a pointer back to your source directory rather than copying files. Every edit to extract.py is live the next time you run csv-extract — no reinstall required.

To uninstall: pip uninstall csv-extract.

Use a virtual environment (python -m venv .venv && source .venv/bin/activate) before running pip install -e .. That way your tool is isolated from system Python and from other projects. pip install -e . in the activated environment installs only into that environment.

Verify the install

After pip install -e ., confirm it worked:

which csv-extract        # should show a path inside your venv
csv-extract --help       # should print the argparse help text
echo "name,score\nada,91" | csv-extract score   # should print: score\n91

If which returns nothing, the virtual environment is not activated or the bin/ directory is not on your PATH.

A demonstration

The browser runner cannot run shell commands or install packages, but you can see the pyproject.toml contents and the full extract.py side by side to understand how they connect. Here is the complete script as it would exist on disk:

Python — editable, runs in your browser

# This is extract.py — the file that pyproject.toml points to.
# The entry point "extract:main" calls main() below.

import sys
import argparse

def column_index(header, name):
  try:
      return header.index(name)
  except ValueError:
      return -1

def extract_column(csv_text, column_name):
  lines = csv_text.strip().splitlines()
  if not lines:
      return []
  header = lines[0].split(",")
  idx = column_index(header, column_name)
  if idx == -1:
      return []
  result = [header[idx]]
  for line in lines[1:]:
      row = line.split(",")
      result.append(row[idx])
  return result

def main():
  parser = argparse.ArgumentParser(description="Extract a CSV column.")
  parser.add_argument("column", help="Column name to extract")
  args = parser.parse_args(["score"])   # simulate the command line

csv_text = "name,score
alice,91
bob,74
"
  values = extract_column(csv_text, args.column)
  if not values:
      sys.stderr.write("error: column not found: " + args.column + "
")
      sys.exit(1)
  print("
".join(values))
  sys.exit(0)

main()

Where to go next

Next: the lab — package the CSV extractor you built, write its pyproject.toml, and verify it installs correctly.

Finished reading? Mark it complete to track your progress.