Improve script section: support use of script files

Improve script support

Rationale & Background

Python packaging supports the distribution and installation of executable scripts by specifying one or more of the following.

1. Entry points console_scripts
2. Entry points gui_scripts
3. Script files

The PyPA Entry points specification details the implementation requirement for handling (1) and (2). As for (3), refer to PEP 427.

Poetry, today, allows for the handling of console_scripts as documented here. Non-script entry points (plugins) are also already supported by Poetry as documented here and is considered a separate feature within the context of Poetry.

As part of the requested enhancement, we want to expand the current support distributing scripts with Poetry managed projects to include both entry point scripts as well as file sourced scripts.

Configuration Specification

In order to achieve this, we need to expand the capabilities offered by the scripts section of the poetry configuration. Today, we expect console_scripts to be configured as follows.

[tool.poetry.scripts]
poetry = 'poetry.console:run'

This should be extended to support various configurations as shown here.

[tool.poetry.scripts]
console-script = {reference = "package.module:function", type = "console"}
gui-script = {reference = "package.module:function", type = "gui"}
file-script = {source = "bin/script.sh", type= "file"}

Entry point script configuration

Name	Description
reference	Required value corresponding to object reference for the the entry point. Eg: importable.module, importable.module:object.attr
type	Optional value indicating the type of script. Defaults to console. Allowed values for reference sourced scripts are console and gui.

File sourced script configuration

Name	Description
source	Required value corresponding to the source file for the script to be included.
type	Optional value indicating the type of script. Defaults to file for file sourced scripts.

While it is possible to detect if a given value is a method or script, the team feels that using an in-line table here will allow for future enhancements to this feature. And furthermore, it allows us to be explicit rather than implicit with respect to the intention.

An implementation of this feature should ensure the following.

1. Project distribution must correctly populate console_scripts and gui_scripts sections of the entry_point.txt file as described by PyPA specifications.
2. Configuration is backwards compatible with existing pyproject.toml files.

Support for extras

Use of extras for an entry point will not be supported by poetry. As per PyPA specifications, these are discouraged for new publishers is discouraged and will not be supported by poetry at this time.

Using extras for an entry point is no longer recommended. Consumers should support parsing them from existing distributions, but may then ignore them. New publishing tools need not support specifying extras. The functionality of handling extras was tied to setuptools’ model of managing ‘egg’ packages, but newer tools such as pip and virtualenv use a different model.

If in the future, this recommendation changes, adding support for this would be as trivial as adding an additional property extras in the script configuration.

Backwards compatibility

To ensure older configuration will still work, string values must also be accepted as a script value. This will default to treating it as an entry point console script. The following will be equivalent.

[tool.poetry.scripts]
poetry = 'poetry.console:run'

[tool.poetry.scripts]
poetry = {reference = "poetry.console:run", type = "console"}

Comparison with setuptools

While these concepts are familiar for users that have used setuptools, the intention here is not copy the configuration interface one-to-one, but rather provide an intuitive and objective driven configuration interface within the context of a Poetry managed project.

To understand better the differences based on the above specification, here are setuptools configurations compared with Poetry configuration achieving the same objective.

Entry point script (console)

setup.py:

setup(
    ...
    entry_points = {
        'console_scripts': ['funniest-joke=funniest.command_line:main'],
    }
    ...
)

pyproject.toml:

[tool.poetry.scripts]
funniest-joke = {reference = "funniest.command_line:main", type = "console"}

Entry point script (gui)

setup.py:

setup(
    ...
    entry_points = {
        'gui_scripts': ['funniest-joke=funniest.gui:main'],
    }
    ...
)

pyproject.toml:

[tool.poetry.scripts]
funniest-joke = {reference = "funniest.gui:main", type = "gui"}

File sourced script

setup.py:

setup(
    ...
    scripts=['bin/funniest-joke'],
    ...
)

pyproject.toml:

[tool.poetry.scripts]
funniest-joke = {source = "bin/funniest-joke", type = "file"}

Related Issues

• #241
• #1023
• #1504

Start with the existing [tool.poetry.scripts] configuration in pyproject.toml and review the linked PyPA entry-points specification and PEP 427. The work is complete when file-sourced scripts and console/gui entry points are distributed as specified while existing string-valued configurations remain compatible.