diff --git a/tutorials/pyproject-toml.md b/tutorials/pyproject-toml.md index 0434e4134..621443c44 100644 --- a/tutorials/pyproject-toml.md +++ b/tutorials/pyproject-toml.md @@ -170,13 +170,30 @@ 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 @@ -184,13 +201,19 @@ If you have two authors you can add them like this: 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. @@ -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"] @@ -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? @@ -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"] @@ -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"] @@ -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" @@ -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"] @@ -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" @@ -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"] @@ -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" @@ -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. @@ -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"] @@ -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" @@ -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"