Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changes/1235.feature.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Briefcase now supports the PEP 621 `authors` setting as a list of author details.
1 change: 1 addition & 0 deletions changes/1235.removal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The `author` and `author_email` settings are deprecated in favour of `authors` matching PEP 621 representation. Using them gives a warning.
14 changes: 8 additions & 6 deletions docs/en/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,13 +97,15 @@ Examples of valid version strings:

### Optional values

#### `author`
#### `authors`

The person or organization responsible for the project.
A list containing the names and/or contact email addresses of people who originally created the project, in [PEP 621 format](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#authors-maintainers) for authors.

#### `author_email`

The contact email address for the person or organization responsible for the project.
```toml
authors = [
{name = "Jane Developer", email = "jane@example.com"},
]
```

#### `env_manager`

Expand Down Expand Up @@ -521,7 +523,7 @@ The following `[project]` metadata keys will be used by Briefcase if they are av
- `name` is normalized and maps to the Briefcase [`project_name`][] setting.
- `version` maps to the same key in Briefcase.
- `license` and `license-files` map to the same key in Briefcase. Legacy formats for these keys will be [coerced into PEP 639 format][license-definitions].
- `authors` The `email` and `name` keys of the first value in the `authors` setting map to [`author`][] and [`author_email`][].
- `authors` maps to the same key in Briefcase.
- `dependencies` maps to the Briefcase [`requires`][] setting. This is a cumulative setting; any packages defined in the [`requires`][] setting at the `[tool.briefcase]` level will be appended to the packages defined with `dependencies` at the `[project]` level.
- `description` maps to the same key in Briefcase.
- `test` in an `[project.optional-dependencies]` section maps to [`test_requires`][]., As with `dependencies`/[`requires`][], this is a cumulative setting.
Expand Down
6 changes: 6 additions & 0 deletions docs/en/reference/platforms/linux/system.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,3 +233,9 @@ Docker builds are not able to reference local paths in the [`requires`][] and [`
### Environment managers and Docker builds

If an application defines the use of an environment manager (using the [`env_manager`][] setting), and Docker is used to build the application, the environment manager will be ignored, and raw `pip` installs will be used.

### Interpreting authors as package maintainers

An app can have more than one author, but Linux packages only have room for one maintainer. Debian's `control` file has a single `Maintainer:` field, and Arch's `PKGBUILD` has a single `PACKAGER` value; both of these are set from the *first* author listed in the app's [`authors`][] setting.

The `PKGBUILD` does credit the other authors. As well as `PACKAGER`, it has `# Maintainer:` comment lines, and Briefcase writes one of those for every author.
4 changes: 4 additions & 0 deletions docs/en/reference/platforms/windows/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -344,3 +344,7 @@ The MSI installer format can be thought of as managing a database - the MSI file
If you write files into the application folder, or you use a post-install or pre-uninstall script that modifies files in the application folder, you must ensure that everything that is installed by the MSI can be removed by the MSI on uninstallation. If the uninstallation process cannot remove files or directories that were originally added by the installer - either because the files have been removed, or because a folder isn't empty - then registry entries tied to that installer will remain in the registry after completion of the installation.

For example, consider an installer that creates a `data` folder in the app, containing 2 files `a.dat` and `b.dat`. The MSI installer has a post-installation script that deletes `b.dat`, and adds `c.dat`. When the uninstallation process is executed, registry entries for `data/b.dat` and `data` will remain in the registry. A well-behaved app should *not* delete content that the MSI app installed; and it should not leave content in locations that would prevent the MSI from removing content that the MSI installed.

### Interpreting authors as product owners

An app can have more than one author. However, when [`use_full_install_path`][] is enabled (as it is by default), a Windows app is installed in folder matching the company that produced the app. Briefcase will use the name of the first author listed in the app's [`authors`][] setting as the company name.
4 changes: 2 additions & 2 deletions docs/en/topics/access-packaging-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ It will also have the following keys, derived from your application's `pyproject
The metadata may also contain the following keys, if they have been defined in your app's `pyproject.toml` configuration:

- **Home-page** - [`url`][]
- **Author** - [`author`][]
- **Author-email** - [`author_email`][]
- **Author** - the `name` values from [`authors`][]
- **Author-email** - the `email` values from [`authors`][]

For example, the metadata for the app constructed by the [BeeWare Tutorial](https://tutorial.beeware.org/tutorial/tutorial-1/) would contain:

Expand Down
4 changes: 2 additions & 2 deletions src/briefcase/bootstraps/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ class AppContext(TypedDict):
test_source_dir: str
project_name: str
description: str
author: str
author_email: str
pep621: dict[str, list[dict[str, str]]]
declare_authors: bool
bundle: str
url: str
license: str
Expand Down
112 changes: 45 additions & 67 deletions src/briefcase/commands/convert.py
Original file line number Diff line number Diff line change
Expand Up @@ -378,8 +378,7 @@ def input_bundle(self, url, app_name, override_value: str | None) -> str:
)

def input_author(self, override_value: str | None) -> str:
"""Ask about the author name, using hints from the pyproject.toml file if there
are any.
"""Ask about the author name.

:returns: author name
"""
Expand All @@ -388,67 +387,25 @@ def input_author(self, override_value: str | None) -> str:
"This could be your own name, or the name of your company you work for."
)

options = [
author["name"]
for author in self.pep621_data.get("authors", [])
if "name" in author
]

default_author = "Jane Developer"
if not options or override_value is not None:
git_username = self.get_git_config_value("user", "name")
if git_username is not None:
default_author = git_username
intro = (
f"{intro}\n\n"
f"Based on your git configuration,"
f" we believe it could be '{git_username}'."
)

return self.console.text_question(
intro=intro,
description="Author",
default=default_author,
override_value=override_value,
git_username = self.get_git_config_value("user", "name")
if git_username is not None:
default_author = git_username
intro = (
f"{intro}\n\n"
f"Based on your git configuration,"
f" we believe it could be '{git_username}'."
)
elif len(options) > 1:
# Add a line with all authors joined: E.g. 'Jane Developer & Joe Developer'
# and a line with Other
options.append(", ".join(options[:-1]) + f" & {options[-1]}")

options.append("Other")

# We want to use text_question if override_value is provided or if the selected
# author is "Other". However, since we don't want the selection_question prompt
# if an override value is provided, we need to initialise the author variable
# here.
author = self.console.selection_question(
intro=(
f"{intro}\n\n"
"We found these author names in the PEP621 formatted "
"'pyproject.toml'. Who do you want to be credited as the author of "
"this application?"
),
return self.console.text_question(
intro=intro,
description="Author",
options=options,
default=options[0],
override_value=None,
default=default_author,
override_value=override_value,
)
if author == "Other":
author = self.console.text_question(
intro=(
"Who do you want to be credited as the author of this application?"
),
description="Author",
default=default_author,
override_value=None,
)

return author

def input_email(self, author: str, bundle: str, override_value: str | None) -> str:
"""Ask about the author email, using hints from the pyproject.toml file if there
are any.
"""Ask about the author email.

:returns: author email
"""
Expand All @@ -460,11 +417,6 @@ def input_email(self, author: str, bundle: str, override_value: str | None) -> s
default = git_email
default_source = "your git configuration"

for author_info in self.pep621_data.get("authors", []):
if author_info.get("name") == author and author_info.get("email"):
default = author_info["email"]
default_source = "the selected author name"

intro = (
"What email address should people use to contact the developers of this "
"application? This might be your own email address, or a generic contact "
Expand All @@ -482,6 +434,35 @@ def input_email(self, author: str, bundle: str, override_value: str | None) -> s

return author_email

def input_authors(
self,
bundle: str,
project_overrides: dict,
) -> tuple[list[dict[str, str]], bool]:
"""Determine the app's authors, using the PEP 621 authors if there are any.

:returns: The app's authors, and whether the Briefcase configuration needs to
declare them. It doesn't need to if the project's own PEP 621 definition can
be used.
"""
author_override = project_overrides.pop("author", None)
email_override = project_overrides.pop("author_email", None)

authors = self.pep621_data.get("authors", [])
if authors and author_override is None and email_override is None:
self.console.divider(title="Authors")
self.console.prompt()
self.console.prompt(
"Using author details from PEP621 formatted pyproject.toml"
)
# The PEP 621 authors are merged into the Briefcase configuration when
# the project is loaded, so there's no need to repeat the definition.
return authors, False

author = self.input_author(override_value=author_override)
author_email = self.input_email(author, bundle, override_value=email_override)
return [{"name": author, "email": author_email}], True

def get_license_hint(self) -> tuple[str | None, str]:
"""Get hint for project license, either by reading pyproject.toml or the license
file.
Expand Down Expand Up @@ -566,10 +547,7 @@ def build_app_context(self, project_overrides):
)
url = self.input_url(app_name, project_overrides.pop("url", None))
bundle = self.input_bundle(url, app_name, project_overrides.pop("bundle", None))
author = self.input_author(override_value=project_overrides.pop("author", None))
author_email = self.input_email(
author, bundle, override_value=project_overrides.pop("author_email", None)
)
authors, declare_authors = self.input_authors(bundle, project_overrides)
project_license = self.input_license(
override_value=project_overrides.pop("license", None)
)
Expand All @@ -586,8 +564,8 @@ def build_app_context(self, project_overrides):
"source_dir": source_dir,
"test_source_dir": test_source_dir,
"description": description,
"author": author,
"author_email": author_email,
"pep621": {"authors": authors},
"declare_authors": declare_authors,
"bundle": bundle,
"url": url,
"license": project_license,
Expand Down
21 changes: 17 additions & 4 deletions src/briefcase/commands/create.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,10 +71,23 @@ def write_dist_info(app: FinalizedAppConfig, dist_info_path: Path):
f.write(f"Download-URL: {app.url}\n")
else:
f.write("Download-URL: \n")
if app.author:
f.write(f"Author: {app.author}\n")
if app.author_email:
f.write(f"Author-email: {app.author_email}\n")

names = []
for entry in app.authors or []:
if entry.get("name"):
names.append(entry["name"])
author = ", ".join(names)

emails = []
for entry in app.authors or []:
if entry.get("email"):
emails.append(entry["email"])
author_email = ", ".join(emails)

if author:
f.write(f"Author: {author}\n")
if author_email:
f.write(f"Author-email: {author_email}\n")
f.write(f"Summary: {app.description}\n")
with (dist_info_path / "top_level.txt").open("w", encoding="utf-8") as f:
f.write(f"{app.module_name}\n")
Expand Down
6 changes: 4 additions & 2 deletions src/briefcase/commands/new.py
Original file line number Diff line number Diff line change
Expand Up @@ -416,6 +416,8 @@ def build_app_context(self, project_overrides: dict[str, str]) -> dict[str, str]
override_value=project_overrides.pop("author_email", None),
)

authors = [{"name": author, "email": author_email}]

url = self.console.text_question(
intro=(
"What is the website URL for this application?\n"
Expand All @@ -440,8 +442,8 @@ def build_app_context(self, project_overrides: dict[str, str]) -> dict[str, str]
"test_source_dir": test_source_dir,
"project_name": project_name,
"description": description,
"author": author,
"author_email": author_email,
"pep621": {"authors": authors},
"declare_authors": True,
"bundle": bundle,
"url": url,
"license": project_license,
Expand Down
Loading
Loading