beeware / beeware/briefcase

Adopt the use of PEP 621 entry points

Open
#2,868 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
3.3k
Forks
549
Avg merge
1d 4h
Merged PRs (30d)
40

Description

### What is the problem or limitation you are having?

Briefcase uses an assumption that an app will always be started using the app name as a module (i.e., the analog of `python -m `).

However, PEP 621 provides for entry point definitions - the ability to define what public entry points should be defined when a package is installed. This also allows for both GUI scripts and console scripts.

Briefcase should

### Describe the solution you'd like

It should be possible to use a PEP 621 entry point definition for an app. The current Briefcase default behavior should be the equivalent of an explicit:
```
[project.gui-scripts]
my-app = "my_app"
```

(or an even more explicit)
```
[project.gui-scripts]
my-app = "my_app/__main__:main"
```

"Invoke the app name as a module" should be retained as a default behavior. However, if the user defines a PEP 621 entry point matching the app name, that would override the default behavior.

This would also supersede the `console_app` definition. If the app name is defined in `[project.scripts]`, it would be assumed to be a console script. Defining the same app in both `gui-scripts` and `scripts` would be considered a configuration error. Defining `console_app` at all if an entry point is explicitly provided would also be a configuration error.

An app should also be able to define a `scripts` or `gui-scripts` key, defining the list of entry points that this app will expose. The default behaviour would effectively be the equivalent of:

```
[project.gui-scripts]
my-app = "my_app"

[tool.briefcase.app.my-app]
gui-scripts = ["my-app"]
```

As a first pass, this list should be limited to a single entry (and may always be limited to a single entry on some platforms - macOS, iOS and Android only allow a single GUI entry point in an app), with longer lists raising an error. However, in time, we may be able to accommodate multiple entry points in a single "app".

### Describe alternatives you've considered

Status quo.

Contributor guide

Open the contributing guide

Research direction

Start by tracing Briefcase's app configuration handling and how it currently invokes an app as a module. Map the PEP 621 [project.scripts] and [project.gui-scripts] definitions to the app's configured entry-point list, including validation for conflicting scripts, console_app, and lists longer than one. Done means explicit entry points override the default while invalid combinations raise configuration errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.