Skip to content

Commit 717be65

Browse files
lwasserlwasser
authored
Description/Author formatting in tutorials/pyproject-toml.md 
2 parents efad49e + 5e0b27a commit 717be65

File tree

1 file changed

+122
-35
lines changed

1 file changed

+122
-35
lines changed

‎tutorials/pyproject-toml.md

Lines changed: 122 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -170,27 +170,50 @@ Add the following to your table:
170170
- package **authors**
171171
- package **maintainers**
172172

173-
When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:
173+
The `description` is just a string like the other values you've set:
174+
175+
```toml
176+
# you can use """ for multiline strings like in python!
174177

175-
`authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]`
178+
description = """
179+
Tools that update the pyOpenSci contributor and review metadata
180+
that is posted on our website
181+
"""
182+
```
176183

177-
If you have two authors you can add them like this:
184+
When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:
185+
186+
```toml
187+
authors = [
188+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
189+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
190+
]
178191

179-
`authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]`
192+
maintainers = [
193+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
194+
{ name = "New Friend", email = "newbie@pyopensci.org" }
195+
]
196+
```
180197

181198
:::{admonition} Author names & emails
182199
:class: note
183200

184201
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:
185202

186203
```toml
187-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname" }]
204+
maintainers = [
205+
{ name = "Firstname lastname", email = "email@pyopensci.org" },
206+
{ name = "Firstname lastname" }
207+
]
188208
```
189209

190210
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:
191211

192212
```toml
193-
maintainers = [{ name = "Firstname lastname"}, { name = "Firstname lastname" }]
213+
maintainers = [
214+
{ name = "Firstname lastname"},
215+
{ name = "Firstname lastname" }
216+
]
194217
```
195218

196219
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.
199222

200223
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:
201224

202-
{emphasize-lines="8-10"}
225+
{emphasize-lines="8-19"}
203226
```toml
204227
[build-system]
205228
requires = ["hatchling"]
@@ -208,9 +231,18 @@ build-backend = "hatchling.build"
208231
[project]
209232
name = "pyospackage"
210233
version = "0.1.0"
211-
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
212-
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
213-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
234+
description = """
235+
Tools that update the pyOpenSci contributor and review metadata
236+
that is posted on our website
237+
"""
238+
authors = [
239+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
240+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
241+
]
242+
maintainers = [
243+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
244+
{ name = "New Friend", email = "newbie@pyopensci.org" }
245+
]
214246
```
215247

216248
:::{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
238270
Once you have those files, you can add them to your pyproject.toml file as
239271
links following the example below.
240272

241-
{emphasize-lines="11-12"}
273+
{emphasize-lines="20-21"}
242274
```toml
243275
[build-system]
244276
requires = ["hatchling"]
@@ -247,18 +279,27 @@ build-backend = "hatchling.build"
247279
[project]
248280
name = "pyospackage"
249281
version = "0.1.0"
250-
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
251-
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
252-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
282+
description = """
283+
Tools that update the pyOpenSci contributor and review metadata
284+
that is posted on our website
285+
"""
286+
authors = [
287+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
288+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
289+
]
290+
maintainers = [
291+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
292+
{ name = "New Friend", email = "newbie@pyopensci.org" }
293+
]
253294
readme = "README.md"
254-
license = {file = 'LICENSE'}
295+
license = {file = "LICENSE"}
255296
```
256297
### Step 3: Specify Python version with `requires-python`
257298

258299
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.
259300

260301

261-
{emphasize-lines="13"}
302+
{emphasize-lines="22"}
262303
```toml
263304
[build-system]
264305
requires = ["hatchling"]
@@ -267,9 +308,18 @@ build-backend = "hatchling.build"
267308
[project]
268309
name = "pyospackage"
269310
version = "0.1.0"
270-
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
271-
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
272-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
311+
description = """
312+
Tools that update the pyOpenSci contributor and review metadata
313+
that is posted on our website
314+
"""
315+
authors = [
316+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
317+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
318+
]
319+
maintainers = [
320+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
321+
{ name = "New Friend", email = "newbie@pyopensci.org" }
322+
]
273323
readme = "README.md"
274324
license = {file = 'LICENSE'}
275325
requires-python = ">=3.10"
@@ -287,7 +337,7 @@ requires = ["hatchling"] # this is an array (or list) of requirements
287337
dependencies are added in an array (similar to a Python list) structure.
288338

289339

290-
{emphasize-lines="15"}
340+
{emphasize-lines="24"}
291341
```toml
292342
[build-system]
293343
requires = ["hatchling"]
@@ -296,9 +346,18 @@ build-backend = "hatchling.build"
296346
[project]
297347
name = "pyospackage"
298348
version = "0.1.0"
299-
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
300-
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
301-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
349+
description = """
350+
Tools that update the pyOpenSci contributor and review metadata
351+
that is posted on our website
352+
"""
353+
authors = [
354+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
355+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
356+
]
357+
maintainers = [
358+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
359+
{ name = "New Friend", email = "newbie@pyopensci.org" }
360+
]
302361
readme = "README.md"
303362
license = {file = 'LICENSE'}
304363
requires-python = ">=3.10"
@@ -354,7 +413,7 @@ The classifier key should look something like the example below. A few notes:
354413
- 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
355414
- You can add as many classifiers as you wish as long as you use the [designated PyPI classifier values](https://PyPI.org/classifiers/).
356415

357-
{emphasize-lines="17-24"}
416+
{emphasize-lines="26-34"}
358417
```toml
359418
[build-system]
360419
requires = ["hatchling"]
@@ -363,9 +422,18 @@ build-backend = "hatchling.build"
363422
[project]
364423
name = "pyospackage"
365424
version = "0.1.0"
366-
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
367-
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
368-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
425+
description = """
426+
Tools that update the pyOpenSci contributor and review metadata
427+
that is posted on our website
428+
"""
429+
authors = [
430+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
431+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
432+
]
433+
maintainers = [
434+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
435+
{ name = "New Friend", email = "newbie@pyopensci.org" }
436+
]
369437
readme = "README.md"
370438
license = {file = 'LICENSE'}
371439
requires-python = ">=3.10"
@@ -379,7 +447,8 @@ classifiers = [
379447
"License :: OSI Approved :: MIT License",
380448
"Programming Language :: Python :: 3 :: Only",
381449
"Programming Language :: Python :: 3.10",
382-
"Programming Language :: Python :: 3.11",]
450+
"Programming Language :: Python :: 3.11",
451+
]
383452
```
384453

385454
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.
394463
- **Bug reports:** a link to your issues / discussions or wherever you want users to report bugs.
395464
- **Source:** the GitHub / GitLab link for your project.
396465

397-
{emphasize-lines="27-30"}
466+
{emphasize-lines="36-39"}
398467
```toml
399468
[build-system]
400469
requires = ["hatchling"]
@@ -403,9 +472,18 @@ build-backend = "hatchling.build"
403472
[project]
404473
name = "pyospackage"
405474
version = "0.1.0"
406-
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
407-
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
408-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
475+
description = """
476+
Tools that update the pyOpenSci contributor and review metadata
477+
that is posted on our website
478+
"""
479+
authors = [
480+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
481+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
482+
]
483+
maintainers = [
484+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
485+
{ name = "New Friend", email = "newbie@pyopensci.org" }
486+
]
409487
readme = "README.md"
410488
license = {file = 'LICENSE'}
411489
requires-python = ">=3.10"
@@ -445,9 +523,18 @@ build-backend = "hatchling.build"
445523
[project]
446524
name = "pyospackage"
447525
version = "0.1.0"
448-
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
449-
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]
450-
maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }]
526+
description = """
527+
Tools that update the pyOpenSci contributor and review metadata
528+
that is posted on our website
529+
"""
530+
authors = [
531+
{ name = "Firstname Lastname", email = "email@pyopensci.org"},
532+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" }
533+
]
534+
maintainers = [
535+
{ name = "Secondperson Fullname", email = "email2@pyopensci.org" },
536+
{ name = "New Friend", email = "newbie@pyopensci.org" }
537+
]
451538
readme = "README.md"
452539
license = {file = 'LICENSE'}
453540
requires-python = ">=3.10"

0 commit comments

Comments
 (0)