Repository navigation
Clarify entry point's object reference specification #1993
Description
Issue Description
In the entry point specification, section data model,
The object reference points to a Python object. It is either in the form
importable.module, orimportable.module:object.attr. Each of the parts delimited by dots and the colon is a valid Python identifier. It is intended to be looked up like this:import importlib modname, qualname_separator, qualname = object_ref.partition(':') obj = importlib.import_module(modname) if qualname_separator: for attr in qualname.split('.'): obj = getattr(obj, attr)
First, I propose to disallow the former form importable.module as its invocation is never mentioned.
Second and more importantly, I want to explicitly enforces object on the right of the colon (:) to be an attribute of importable.module on the left. To add the confusion , later in the section use for scripts:
the entry point
mycmd = mymod:mainwould create a commandmycmdlaunching a script like this:import sys from mymod import main sys.exit(main())
Because of the way the import-from statement works:
The
fromform uses a slightly more complex process:
- find the module specified in the from clause, loading and initializing it if necessary;
- for each of the identifiers specified in the import clauses:
- check if the imported module has an attribute by that name
- if not, attempt to import a submodule with that name and then check the imported module again for that attribute
[...]
package authors may wrongly assume the first identifier object on the right of the colon to possibly be a module as well (exhibit A). While both pkg_resources's and the builtin importlib.metadata's EntryPoint.load would fail on such incorrect entry point, they aren't run on common build processes and the most popular installer pip generates working scripts in a format the same as in the mycmd = mymod:main example.
It would be nice if the specification is more explicit over what is and is not allowed instead of a reference implementation ([an object reference] is intended to be looked up like this). In Guix we got entry point script generation (hopefully) right on the third try and it shouldn't be like this for other projects.
Code of Conduct
- I am aware that participants in this repository must follow the PSF Code of Conduct.
Activity
merwok commentedon Feb 5, 2026
See also https://discuss.python.org/t/why-do-script-entrypoints-require-a-function-be-specified/14090/ and pypa/distlib#257
ncoghlan commentedon Feb 23, 2026
Detailed entry point requirements on the object being referenced are defined by the entry point consumer. For example,
build-backendinpyproject.tomlis an entry point specifier, and frequently given in the bare module form (but it doesn't have to be - it could instead refer to an implicitly created object instance or a class defining the API hooks as class and/or static methods): https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#declaring-the-build-backendThe details of what that entry point target is expected to support are then given in https://peps.python.org/pep-0517/#build-backend-interface (since that spec hasn't been revised since we started migrating the PyPA specs from the PEPs themselves to packaging.python.org)
For console scripts and GUI scripts specifically, the "Use for scripts" section already explicitly states the following:
There's no way to make a module callable, which is why console and GUI script entry points have to use the "module:object" form of entry point, and the object lookup can't be of a submodule.
For other entry point use cases (such as build backends), a submodule lookup may be entirely fine.
If we were going to change anything, it would probably make the most sense to call out this callable restriction more explicitly in https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#creating-executable-scripts rather than expecting it to be implied by the
import sys; from spam import main_cli; sys.exit(main_cli())invocation example.merwok commentedon Feb 25, 2026
I am surprised that you use the entry point term for build-backend, as it’s not something handled by the entrypoints spec or entrypoints tooling.
Herrtian commentedon May 22, 2026
Summarizing the actionable bit here: the spec text already covers console/gui script targets, so the remaining docs change seems to be in the writing-pyproject-toml guide. A small note under "Creating executable scripts" could say script entry points need a module:object target and cannot point at a module directly; other entry point consumers can define different target rules.