Entry points, console_scripts and __main__.py

if __name__ == "__main__":
    args = parse_args(sys.argv[1:])
    config = load(args.config)
    for row in read(config):
        process(row)
    print("done")

Everything this program does lives in a block that only executes when the file is run directly. So: no test can call it, no other module can reuse it, and there is nothing for a [project.scripts] entry to point at. The refactor is one line — move the body into def main(argv: Sequence[str]) -> int: — and it unlocks all three.

The entry-point model

An entry point is a (group, name, object reference) triple, recorded in your distribution’s metadata at build time and readable by anything at runtime.

[project.scripts]
pricing = "pricing.cli:main"

[project.gui-scripts]
pricing-ui = "pricing.ui:launch"

[project.entry-points."pricing.backends"]
sqlite = "pricing.adapters.sqlite:SqliteBackend"

The object reference is importable.module:object.attr — a module path, an optional colon, then a dotted attribute path within it. pricing.cli:main is the function main in module pricing.cli; pkg.mod:Class.method reaches a method; a bare pkg.mod refers to the module itself.

[project.scripts] becomes the console_scripts group. The installer generates a small wrapper executable in the environment’s bin/ (or Scripts/) which imports your module, calls the object, and exits with its return value. There is no shebang in your source, no chmod +x, and no python -m for the user to remember.

[project.gui-scripts] exists for one platform difference: on Windows, a console_scripts wrapper is built against python.exe and opens a console window; a gui_scripts wrapper is built against pythonw.exe and does not. On Linux and macOS the two are effectively the same.

Custom groups are the plugin mechanism. Your application reads them back at runtime:

from importlib.metadata import entry_points

for ep in entry_points(group="pricing.backends"):
    backend_class = ep.load()

Use importlib.metadata. pkg_resources — the old way — is removed, and it was also slow, because it scanned and parsed metadata for every installed distribution at import.

plugins = {ep.name: ep for ep in entry_points(group="myapp.plugins")}
backend = plugins[config.backend].load()      # exactly one import

What main() must return

def main(argv: Sequence[str] | None = None) -> int:
    ...
    return 0

The generated wrapper does the equivalent of sys.exit(main()), and sys.exit has a specific contract:

• None or 0 → exit status 0, success.
• any other int → that exit status.
• any other object, including a str → the object is printed to stderr and the exit status is 1.

So return "done" prints done to stderr and exits 1. Every CI system, every shell &&, every Kubernetes readiness check reads that as failure. The bug is invisible locally, because the message looks like success.

Annotate main as returning int (or int | None) and let mypy hold you to it. This is a genuine case where the annotation prevents a production defect rather than documenting one.

__main__.py

A package with __main__.py can be run as python -m yourpkg:

# yourpkg/__main__.py
import sys

from yourpkg.cli import main

sys.exit(main(sys.argv[1:]))

Note what is not there: an if __name__ == "__main__": guard. __main__.py exists precisely to be run as __main__, and it is not meaningfully importable under any other name — so the guard is noise that suggests a second mode of use that does not exist.

Ship both a [project.scripts] entry and a __main__.py, both delegating to the same main(). The console script is what users type; python -m is what works when bin/ is not on PATH, which is more often than you would think.