Version specification in main text of tutorials/pyproject-toml.md

tutorials/pyproject-toml.md

@@ -296,7 +296,10 @@ license = {file = "LICENSE"}
 ```
 ### Step 3: Specify Python version with `requires-python`
 
-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.
+Add the `requires-python` field to your `pyproject.toml` `[project]` table.
+The `requires-python` field helps pip identify which Python versions that your package supports.
+It is set to a single value.
+The [packaging specification](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-requires-python) defines`requires-python` as a string that uses version specifiers. Most projects will specify the oldest Python version supported by the package. In some advanced cases, an upper bound is set to indicate which future Python versions, if any, will be supported.
 
 
 {emphasize-lines="22"}
@@ -334,8 +337,42 @@ The `dependencies =` section contains a list (or array in the toml language) of
 [build-system] # <- this is a table
 requires = ["hatchling"] # this is an array (or list) of requirements
 ```
+
 dependencies are added in an array (similar to a Python list) structure.
 
+```toml
+dependencies = ["numpy", "requests", "pandas", "pydantic"]
+```
+
+A dependency can be limited to specific versions using a **version specifier.**
+If the dependency has no version specifier after the dependency name, your package can use any version of the dependent package.
+Code changes over time, bugs are fixed, APIs change, and so it's good to be clear about which version of the dependency you wrote your code to be compatible with - a package you wrote this year probably isn't compatible with numpy v0.0.1!
+
+[Learn more about various ways to specify ranges of package versions here.](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5)
+
+The most common version specifier is a **lower bound,** allowing any version higher than the specified version.
+Ideally you should set this to the lowest version that is still compatible with your package, but in practice for new packages this is often set at the version that was current at the time the package was written[^lowerbound].
+
+[^lowerbound]: Some packaging tools will do this for you when you add a dependency using their cli interface. For example [`poetry add`](https://python-poetry.org/docs/cli/#add) will add the most recent version with a `^` specifier, and [`pdm add`](https://pdm-project.org/latest/reference/cli/#add) will add the most recent version with `>=`.
+
+Lower bounds look like this:
+
+```toml
+dependencies = [ "numpy>=1.0" ]
+```
+
+Commas are used to separate individual dependencies, and each package in your `dependencies` section can use different types of version specifiers:
+
+```toml
+dependencies = [
+  "numpy>=1.0",      # Greater than or equal to 1.0
+  "requests==10.1",  # Exactly 10.1
+  "pandas",          # Any version
+  "pydantic>=1.7,<2" # Greater than or equal to 1.7, but less than 2
+]
+```
+
+Your `pyproject.toml` file will now look like this:
 
 {emphasize-lines="24"}
 ```toml
@@ -362,31 +399,30 @@ readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
 
-dependencies = ["numpy", "requests", "pandas", "pydantic"]
+dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]
 ```
 
 :::{admonition} Pin dependencies with caution
-Pinning dependencies refers to specifying a specific version of a dependency like this `numpy == 1.0`. In some specific cases, you may chose to pin a package version for a specific package dependency.
+"Pinning" a dependency means setting it to a specific version, like this:
 
-Declaring lower bounds involves ensuring that a user has at least a specific version (or greater) of a package installed. This is important as often your package is not backwards compatible with an older version of a tool - for example a version of Pandas that was released 5 years ago.
-
-You can declare a lower bound using syntax like this:
-
-`ruamel-yaml>=0.17.21`
-
-[Learn more about various ways to specify ranges of package versions here.](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5)
-
-Note that unless you are building an application, you want to be cautious about pinning dependencies to precise versions. For example:
-
-`numpy == 1.0.2`
+`numpy == 1.0`.
 
+If you are building a library package that other developers will depend upon, you must be cautious before pinning to a precise dependency version. Applications, such as production websites, will often pin their dependencies since other packages will not depend on their project.
 This is because
 users will be installing your package into various environments.
 A dependency pinned to a single specific version can make
 resolving a Python environment more challenging. As such only
 pin dependencies to a specific version if you absolutely need to
 do so.
 
+Similarly, you should be cautious when specifying an upper bound on a package.
+These two specifications are equivalent:
+
+```
+pydantic>=1.10,<2
+pydantic^1.10
+```
+
 One build tool that you should be aware of that pins dependencies to an upper bound by default is Poetry. [Read more about how to safely add dependencies with Poetry, here.](challenges-with-poetry)
 :::
 
@@ -438,7 +474,7 @@ readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
 
-dependencies = ["numpy", "requests", "pandas", "pydantic"]
+dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]
 
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -488,7 +524,7 @@ readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
 
-dependencies = ["ruamel-yaml>=0.17.21", "requests", "python-dotenv", "pydantic"]
+dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]
 
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -539,7 +575,7 @@ readme = "README.md"
 license = {file = 'LICENSE'}
 requires-python = ">=3.10"
 
-dependencies = ["ruamel-yaml>=0.17.21", "requests", "python-dotenv", "pydantic"]
+dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]
 
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -612,7 +648,7 @@ classifiers = [
 ]
 
 
-dependencies = ["xarray", "requests"]
+dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]
 # This is the metadata that pip reads to understand what versions your package supports
 requires-python = ">=3.10"
 readme = "README.md"