Python Tutorial / Package a Python Program and Verify Installation

A Python project can declare build metadata in pyproject.toml and produce distributable files such as wheels. Install the built wheel into a clean environment and test outside the source directory to reveal accidental source-only imports.

Separate distribution and import names

The local distribution name here is expensekit-demo; the import package is expensekit. A hyphenated distribution name need not match the Python module name. A src layout helps avoid importing directly from the project root when the installation is incomplete.

These names are for a local exercise. Public repository availability and ownership are not established by creating the files. This workflow builds and installs locally without uploading a release.

For the relevant APIs and platform requirements, see Package a Python Program and Verify Installation documentation.

Package execution and installation isolation build on the rules demonstrated in Create Virtual Environments and Manage Packages with pip.

Create every project file

Create src/expensekit/__init__.py with:

def total(amounts):
    if any(type(x) is not int or x < 0 for x in amounts):
        raise ValueError("invalid amount")
    return sum(amounts)

Create src/expensekit/cli.py with:

import argparse
from . import total

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("amounts", type=int, nargs="+")
    args = parser.parse_args()
    print(total(args.amounts))

if __name__ == "__main__":
    main()

Create pyproject.toml at the project root with:

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

[project]
name = "expensekit-demo"
version = "0.1.0"
description = "Local expense sum example"
requires-python = ">=3.12"

[project.scripts]
expense-total = "expensekit.cli:main"

[tool.setuptools.packages.find]
where = ["src"]

Build and install into a clean environment

From the folder containing pyproject.toml, install the build tool and build the project:

python -m pip install build
python -m build

dist should contain a wheel and a source distribution. Create a separate verification environment:

python -m venv .venv-check

On Windows PowerShell, install the wheel with the new interpreter:

.\.venv-check\Scripts\python.exe -m pip install dist/expensekit_demo-0.1.0-py3-none-any.whl

On macOS or Ubuntu, use:

.venv-check/bin/python -m pip install dist/expensekit_demo-0.1.0-py3-none-any.whl

Activate .venv-check or substitute its full interpreter path in the checks below. After installation, move to a new folder outside the source project and run:

python -c "from expensekit import total; print(total([3500,8000,2500]))"
python -m expensekit.cli 3500 8000 2500

Both commands should print 14000. project.scripts also declares the expense-total alias. With the verification environment activated it can call the same main entry point; module execution remains an explicit alternative if an alias has a path or launcher problem.

Inspect missing files and plan a separate release

If import succeeds only in the source directory, inspect the chosen interpreter, installed distribution, package discovery and wheel contents. Declare runtime dependencies in project.dependencies and verify compatibility with the stated Python range. Development tools do not automatically belong among runtime dependencies.

A public release additionally needs a repository-name check, license and author details, README, included-file and secret review, repository authentication and a release policy. Passing a local install check is not authorization to upload publicly.

The package entry-point lesson explains why importing the CLI module should not start argument parsing or other application work.

Completion here means building local distribution files, installing into a fresh environment and checking imports and command execution. Publishing to PyPI is a separate task. dist should contain expensekit_demo-0.1.0-py3-none-any.whl and expensekit_demo-0.1.0.tar.gz. Use the .venv-check interpreter explicitly or activate that environment for verification, so an existing development installation cannot conceal a packaging error.

project/
  pyproject.toml
  src/
    expensekit/
      __init__.py
      cli.py
  dist/
    expensekit_demo-0.1.0-py3-none-any.whl
    expensekit_demo-0.1.0.tar.gz