Packaging Entry Points

It’s recommended to write command line utilities as installable packages with entry points instead telling users to run python hello.py.

A distribution package is a .whl file you install with pip or another Python installer. You use a pyproject.toml file to describe the project and how it is built into a package. You might upload this package to PyPI, or distribute it to your users in another way.

Python installers create executable scripts that will run a specified Python function. These are known as “entry points”. The installer knows how to create an executable regardless of the operating system, so it will work on Linux, Windows, MacOS, etc.

Project Files

To install your app with an entry point, all you need is the script and a pyproject.toml file. Here’s an example project directory:

hello-project/
    src/
        hello/
            __init__.py
    pyproject.toml

Contents of hello.py:

import click

@click.command()
def cli():
    """Prints a greeting."""
    click.echo("Hello, World!")

Contents of pyproject.toml:

[project]
name = "hello"
version = "1.0.0"
description = "Hello CLI"
requires-python = ">=3.11"
dependencies = [
    "click>=8.1",
]

[project.scripts]
hello = "hello:cli"

[build-system]
requires = ["flit_core<4"]
build-backend = "flit_core.buildapi"

The magic is in the project.scripts section. Each line identifies one executable script. The first part before the equals sign (=) is the name of the script that should be generated, the second part is the import path followed by a colon (:) with the function to call (the Click command).

Installation

When your package is installed, the installer will create an executable script based on the configuration. During development, you can install in editable mode using the -e option. Remember to use a virtual environment!

$ python -m venv .venv
$ . .venv/bin/activate
$ pip install -e .

Afterwards, your command should be available:

$ hello
Hello, World!