Skip to content

Reordering and renaming sections in pyproject.toml (and unfortunately a bunch more) #6

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.

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

Conversation

sneakers-the-rat
Copy link

Part of: pyOpenSci#181

Sorry this has so much in it, basically pick and choose what you want :)

ToC structure

Main thing is restructuring ToC to have a section for each field we are adding to the file so they are plainly visible as a group and can be scanned quickly. The ToC gives context to individual sections, so while we are in the "adding fields to our pyproject.toml" section, the subsections are basically a list of the fields we are adding, so we can abbreviate section headings to make them easier to scan.

Previously:

# Make your Python package PyPI ready - pyproject.toml
## What is a pyproject.toml file?
### About the .toml format
### What is the pyproject.toml used for?
### What is the metadata for?
## Time to update your pyproject.toml file
## Add metadata to your pyproject.toml `[project]` table
### Add classifiers to your metadata
### Add package dependencies
### Requires-python
### Your current pyproject.toml file
### Add your README and license
## Add the `[project.urls]` table
## Putting it all together - your completed pyproject.toml file
## Appendix - A fully commented pyproject.toml file
## Example `pyproject.toml` files
## <i class="fa-solid fa-hands-bubbles"></i> Wrap up
## Publish a new version of your package to PyPI
### Next (optional) step - publishing to conda-forge

This PR:

# Make your Python package PyPI ready - pyproject.toml
## What is a pyproject.toml file?
### About the .toml format
### What is the pyproject.toml used for?
### What is the metadata for?
## Completing your `pyproject.toml` metadata
### `description`, `authors`, `maintainers`
### `classifiers`
### `dependencies`
### `requires-python`
### `readme`, `license`
### The `[project.urls]` table
## Your completed `pyproject.toml` file
## Publish a new version of your package to PyPI
### Next (optional) step - publishing to conda-forge
## <i class="fa-solid fa-hands-bubbles"></i> Wrap up
## Appendix - Example `pyproject.toml` files
### A fully commented pyproject.toml file

So making top-level sections: what is pyproject, adding sections, done!, publish, appendix.

Ordering

I also

  • moved the appendix to the very end since it seemed like reference material, and
  • moved the annotated pyproject.toml to be part of the appendix since it is itself an example.
  • moved "wrap up" after the "publish" step since wrap ups usually happen at the end of lesson.

Version pinning

I haven't really seen a package in the wild that leaves most of its versions wide open without even a lower bound, and I think it is an important concept to introduce as like "you need to know when and why to use these" rather than "don't use these." I wrote a few paras that should be a relatively uncontroversial take on lower bounds being the default, and then made the admonition more specific about pinning exact versions being bad to do.

Additionally, i understand the term "pinning" to mean specifying a single or very narrow range of versions, like you usually say that a lockfile pins exact versions, or refer to a package's dependencies as being "pinned" when they are narrower than you want them to be. So changed languaged to reflect that: "pydantic pins versions by default" -> "pydantic sets an upper bound by default." I could be wrong about that but ya as with the rest of this, take it or leave it!

Updating example pyproject.toml throughout sections

I added an "in progress" pyproject.toml to most sections, and enabled the attrs_block extension to highlight the sections we just added, eg:

Screenshot 2024-02-27 at 4 07 12 PM

toml formatting

I tried to demonstrate clear TOML formatting throughout, and that could be something to be consolidated in the "what is toml" section, but i sort of like introducing the concepts when they are applicable (eg. multiline strings for long descriptions, arrays of tables for authors, etc.)

@lwasser
Copy link
Owner

lwasser commented Mar 1, 2024

@sneakers-the-rat the highlighting looks cool. i'll go through all of the suggestions first. You will need to rebase this before i can look at it. hopefully the dif then is easier for me to parse! it looks like some files are totally rewritten but i don't think that is actually the case if a rebase happens.

@sneakers-the-rat
Copy link
Author

Lol what on earth happened here. Ok ill rebase in a minute

…-package-guide into license-pyproject

# Conflicts:
#	tutorials/add-license-coc.md
#	tutorials/add-readme.md
#	tutorials/intro.md
#	tutorials/pyproject-toml.md
…pyproject-toml-sectioning

# Conflicts:
#	tutorials/intro.md
#	tutorials/pyproject-toml.md
@sneakers-the-rat
Copy link
Author

OK Rebased. It looks like more changes than it is because i reordered some sections:

  • "what's the difference between authors and maintainers" dropdown comes right after the "authors and maintainers" block instead of at the end of the section
  • Add a note on "it's good to have version lower bounds" outside of the admonition, and simpify the admonition text
  • The package metadata changes between examples, so i made it line up (eg. pyospackage vs pyosmeta, file="LICENSE" vs text = "MIT",
  • Moved publishing packages up before appendix, and moved fully commented pyproject.toml into "example pyproject.toml files" so they're grouped together

@sneakers-the-rat
Copy link
Author

huh there's something weird going on here where i rebased off yours just now and it's still not matching a lot of stuff. you know what nevermind.

@sneakers-the-rat
Copy link
Author

i'll just make another one. there is still some stuff that i think is worth tidying but don't rly care if it happens in this PR or not :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants