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

[elitejake]

Any updates on this?

[abn]

@funkyfuture thank you for taking the time to provide feedback. However, this conversation has already been had across the linked related issues. As you have mentioned, poetry is not setuptools. While setuptools uses the entry_points argument to configure all three use cases, this can, in the end, be one of the more confusing aspects of the setup.py file. And this is not something that we should repeat just because it is what is already done. PyPA’s interoperability specification exists “to allow build tools other than setuptools to publish pkg_resources compatible entry point metadata, and runtime libraries other than pkg_resources to portably read published entry point metadata (potentially with different caching and conflict resolution strategies)” [1]. It does not dictate or recommend how build tools expose these features to end users in their respective configurations. Any build artifacts produced by Poetry will be interoperable as per the recommended specification.

The scope of this issue is limited to improve script file support, by allowing poetry users to specify a file to be used. To that effect, we do not wish to replace the “plugin” section or duplicate its functionality in another section. The current proposal has been made with future extensibility in mind. I have updated the title to reflect this clearly.

An extension to this could include support for extras and also for distinguishing between console and gui quite easily. For example;

[tool.poetry.scripts]
my-script = {path = "bin/my-script.sh", extras=["foo"]}
my-python-script = {entrypoint = "package.module:function", type="console", extras=["cli"]}
my-python-script = {entrypoint = "package.module.gui:function", type="gui"}