Skip to content

Description/Author formatting in tutorials/pyproject-toml.md #193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Mar 6, 2024
Merged

Description/Author formatting in tutorials/pyproject-toml.md #193

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
8afe183
Add: last files for bug bash
lwasser Feb 13, 2024
24ebbc9
Fix: Edits from @ucodery
lwasser Feb 27, 2024
c2e399f
Fix: edits from review
lwasser Feb 27, 2024
4434620
Fix: comments from review
lwasser Feb 27, 2024
cdfd0c6
Fix: update links throughout lessons
lwasser Feb 27, 2024
8493f03
Merge branch 'license-pyproject' of https://github.com/lwasser/python…
sneakers-the-rat Mar 1, 2024
e9b2aaf
Merge remote-tracking branch 'lwasser/license-pyproject' into license…
sneakers-the-rat Mar 1, 2024
665fd2d
Expanding author, maintainer, and description so they fit on the page!
sneakers-the-rat Mar 1, 2024
a03b484
Merge branch 'main' into author-formatting
sneakers-the-rat Mar 4, 2024
5e0b27a
precommit will be the death of me
sneakers-the-rat Mar 4, 2024
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
157 changes: 122 additions & 35 deletions tutorials/pyproject-toml.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,27 +170,50 @@ Add the following to your table:
- package **authors**
- package **maintainers**

When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:
The `description` is just a string like the other values you've set:

```toml
# you can use """ for multiline strings like in python!

`authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]`
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
```

If you have two authors you can add them like this:
When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:

```toml
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]

`authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]`
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
```

:::{admonition} Author names & emails
:class: note

There is a quirk with PyPI for authors that have names but not emails in the pyproject.toml. If you are missing the email for one or more authors or maintainers, like this:

```toml
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname" }]
maintainers = [
{ name = "Firstname lastname", email = "email@pyopensci.org" },
{ name = "Firstname lastname" }
]
```

Then we suggest that you only provide names in your list of names to ensure that everything renders properly on your PyPI page - like this:

```toml
maintainers = [{ name = "Firstname lastname"}, { name = "Firstname lastname" }]
maintainers = [
{ name = "Firstname lastname"},
{ name = "Firstname lastname" }
]
```

don't have emails for everyone, we suggest that you only add names.
Expand All @@ -199,7 +222,7 @@ don't have emails for everyone, we suggest that you only add names.

Your `pyproject.toml` file now should look like the example below. It is OK if you only have 1 author and the same author is also maintainer of your package:

{emphasize-lines="8-10"}
{emphasize-lines="8-19"}
```toml
[build-system]
requires = ["hatchling"]
Expand All @@ -208,9 +231,18 @@ build-backend = "hatchling.build"
[project]
name = "pyospackage"
version = "0.1.0"
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
```

:::{dropdown} Learn More: What's the difference between author and maintainer in open source?
Expand Down Expand Up @@ -238,7 +270,7 @@ In the previous lessons, you added both a [README.md](add-readme) file and a [LI
Once you have those files, you can add them to your pyproject.toml file as
links following the example below.

{emphasize-lines="11-12"}
{emphasize-lines="20-21"}
```toml
[build-system]
requires = ["hatchling"]
Expand All @@ -247,18 +279,27 @@ build-backend = "hatchling.build"
[project]
name = "pyospackage"
version = "0.1.0"
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
license = {file = "LICENSE"}
```
### Step 3: Add requires-python to your [project] table

Finally, add the `requires-python` field to your `pyproject.toml` `[project]` table. The `requires-python` field, helps pip understand the lowest version of Python that you package supports when it's installed. It is thus a single value.


{emphasize-lines="13"}
{emphasize-lines="22"}
```toml
[build-system]
requires = ["hatchling"]
Expand All @@ -267,9 +308,18 @@ build-backend = "hatchling.build"
[project]
name = "pyospackage"
version = "0.1.0"
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"
Expand All @@ -287,7 +337,7 @@ requires = ["hatchling"] # this is an array (or list) of requirements
dependencies are added in an array (similar to a Python list) structure.


{emphasize-lines="15"}
{emphasize-lines="24"}
```toml
[build-system]
requires = ["hatchling"]
Expand All @@ -296,9 +346,18 @@ build-backend = "hatchling.build"
[project]
name = "pyospackage"
version = "0.1.0"
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"
Expand Down Expand Up @@ -354,7 +413,7 @@ The classifier key should look something like the example below. A few notes:
- Your classifier values might be different depending upon the license you have selected for your package, your intended audience, development status of your package and the Python versions that you support
- You can add as many classifiers as you wish as long as you use the [designated PyPI classifier values](https://PyPI.org/classifiers/).

{emphasize-lines="17-24"}
{emphasize-lines="26-34"}
```toml
[build-system]
requires = ["hatchling"]
Expand All @@ -363,9 +422,18 @@ build-backend = "hatchling.build"
[project]
name = "pyospackage"
version = "0.1.0"
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"
Expand All @@ -379,7 +447,8 @@ classifiers = [
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3 :: Only",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",]
"Programming Language :: Python :: 3.11",
]
```

Note that while classifiers are not required in your `pyproject.toml` file, they will help users find your package. As such we strongly recommend that you add them.
Expand All @@ -394,7 +463,7 @@ Finally, add the project.urls table to your pyproject.toml file.
- **Bug reports:** a link to your issues / discussions or wherever you want users to report bugs.
- **Source:** the GitHub / GitLab link for your project.

{emphasize-lines="27-30"}
{emphasize-lines="36-39"}
```toml
[build-system]
requires = ["hatchling"]
Expand All @@ -403,9 +472,18 @@ build-backend = "hatchling.build"
[project]
name = "pyospackage"
version = "0.1.0"
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"
Expand Down Expand Up @@ -445,9 +523,18 @@ build-backend = "hatchling.build"
[project]
name = "pyospackage"
version = "0.1.0"
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
{ name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"
Expand Down