Merge branch 'main' into copyleft

sneakers-the-rat · sneakers-the-rat · commit e65d4aadbdbc · 2024-03-19T14:55:14.000-07:00
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -461,6 +461,17 @@
         "review",
         "tutorial"
       ]
+    },
+    {
+      "login": "tomalrussell",
+      "name": "Tom Russell",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2762769?v=4",
+      "profile": "https://github.com/tomalrussell",
+      "contributions": [
+        "code",
+        "review",
+        "tutorial"
+      ]
     }
   ],
   "contributorsPerLine": 7,
diff --git a/.zenodo.json b/.zenodo.json
@@ -109,11 +109,6 @@
             "affiliation": "",
             "name": "Van der Walt, Stéfan"
         },
-        {
-            "type": "Other",
-            "affiliation": "",
-            "name": "Schwartz, Eli"
-        },
         {
             "type": "Other",
             "affiliation": "Quansight",
@@ -201,6 +196,36 @@
             "affiliation": "",
             "name": "Knorps, Maria"
         },
+        {
+            "type": "Other",
+            "affiliation": "",
+            "name": "Schwartz, Eli"
+        },
+        {
+            "type": "Other",
+            "affiliation": "",
+            "name": "Burns, Jackson"
+        },
+        {
+            "type": "Other",
+            "affiliation": "",
+            "name": "Jaimergp"
+        },
+        {
+            "type": "Other",
+            "affiliation": "",
+            "name": "h-vetinari"
+        },
+        {
+            "type": "Other",
+            "affiliation": "",
+            "name": "Ogasawara, Ivan"
+        },
+        {
+            "type": "Other",
+            "affiliation": "",
+            "name": "Russell, Tom"
+        },
         {
             "type": "Other",
             "affiliation": "",
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # <img src="https://www.pyopensci.org/images/logo.png" width=100 /> pyOpenSci scientific Python Packaging Guide
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-44-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-45-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
@@ -131,6 +131,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/h-vetinari"><img src="https://avatars.githubusercontent.com/u/33685575?v=4?s=100" width="100px;" alt="h-vetinari"/><br /><sub><b>h-vetinari</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=h-vetinari" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Ah-vetinari" title="Reviewed Pull Requests">👀</a> <a href="#tutorial-h-vetinari" title="Tutorials">✅</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://xmnlab.github.io"><img src="https://avatars.githubusercontent.com/u/5209757?v=4?s=100" width="100px;" alt="Ivan Ogasawara"/><br /><sub><b>Ivan Ogasawara</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=xmnlab" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Axmnlab" title="Reviewed Pull Requests">👀</a> <a href="#tutorial-xmnlab" title="Tutorials">✅</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/tomalrussell"><img src="https://avatars.githubusercontent.com/u/2762769?v=4?s=100" width="100px;" alt="Tom Russell"/><br /><sub><b>Tom Russell</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=tomalrussell" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Atomalrussell" title="Reviewed Pull Requests">👀</a> <a href="#tutorial-tomalrussell" title="Tutorials">✅</a></td>
     </tr>
   </tbody>
 </table>
diff --git a/index.md b/index.md
@@ -71,7 +71,7 @@ by the community now! Join our community review process or watch development of
 :class-card: left-aligned
 
 * [What is a Python package?](/tutorials/intro)
-* [Make your code installable](/tutorials/1-installable-code)
+* [Make your code installable](/tutorials/installable-code)
 * [Publish your package to (test) PyPi](/tutorials/publish-pypi)
 * [Publish your package to conda-forge](/tutorials/publish-conda-forge)
 
diff --git a/package-structure-code/publish-python-package-pypi-conda.md b/package-structure-code/publish-python-package-pypi-conda.md
@@ -19,7 +19,7 @@ Below you will learn more specifics about the differences between PyPI and conda
 :::
 
 
-:::{figure-md} pypi-conda-channels
+:::{figure-md} upload-conda-forge
 
 <img src="../images/publish-python-package-pypi-conda.png" alt="Image showing the progression of creating a Python package, building it and then publishing to PyPI and conda-forge. You take your code and turn it into distribution files (sdist and wheel) that PyPI accepts. then there is an arrow towards the PyPI repository where ou publish both distributions. From PyPI if you create a conda-forge recipe you can then publish to conda-forge. " width="700px">
 
diff --git a/package-structure-code/python-package-build-tools.md b/package-structure-code/python-package-build-tools.md
@@ -403,6 +403,7 @@ Build your sdist and wheel distributions|✅|Poetry will build your sdist and wh
 
 <!-- TODO: responses here on poetry's future dev work: https://github.com/python-poetry/poetry/discussions/7525 -->
 
+(challenges-with-poetry)=
 ### Challenges with Poetry
 
 Some challenges of Poetry include:
diff --git a/package-structure-code/python-package-distribution-files-sdist-wheel.md b/package-structure-code/python-package-distribution-files-sdist-wheel.md
@@ -1,15 +1,14 @@
 # Learn about Building a Python Package
 
 
-:::{figure-md} pypi-conda-channels
+:::{figure-md} pypi-conda-overview
 
 <img src="../images/publish-python-package-pypi-conda.png" alt="Image showing the progression of creating a Python package, building it and then publishing to PyPI and conda-forge. You take your code and turn it into distribution files (sdist and wheel) that PyPI accepts. then there is an arrow towards the PyPI repository where ou publish both distributions. From PyPI if you create a conda-forge recipe you can then publish to conda-forge. " width="700px">
 
 Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. conda-forge requires an source distribution on PyPI in order to build your package on conda-forge. You do not need to rebuild your package to publish to conda-forge.
 :::
 
 You need to build your Python package in order to publish it to PyPI (or a conda channel). The build process organizes your code and metadata into a distribution format that can be uploaded to PyPI and subsequently downloaded and installed by users. NOTE: you need to publish a sdist to PyPI in order for conda-forge to properly build your package automatically.
-:::
 
 (build-package)=
 ## What is building a Python package?
diff --git a/tests/run-tests.md b/tests/run-tests.md
@@ -16,7 +16,7 @@ Python versions.
 
 
 
-### Tools to run your tests
+## Tools to run your tests
 
 There are three categories of tools that will make is easier to setup
 and run your tests in various environments:
@@ -80,7 +80,7 @@ extensions that can be used to add functionality such as:
 - [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) allows you to analyze the code coverage of your package during your tests, and generates a report that you can [upload to codecov](https://codecov.io/).
 
 :::{todo}
-[Learn more about code coverage here.](code-cov)
+Learn more about code coverage here. (add link)
 :::
 
 ```{note}
diff --git a/tests/tests-ci.md b/tests/tests-ci.md
@@ -6,7 +6,7 @@ CI can also be triggered for pull requests and pushes to your repository. This m
 
 ::::{todo}
 ```{note}
-[Learn more about Continuous Integration and how it can be used, here.](ci)
+Learn more about Continuous Integration and how it can be used, here. (add link)
 ```
 ::::
 
diff --git a/tutorials/add-license-coc.md b/tutorials/add-license-coc.md
@@ -62,7 +62,7 @@ There are several ways to add a LICENSE file:
 :::{tip}
 If you completed the past lessons including
 
-1. [Making your code installable](1-installable-code.md) and
+1. [Making your code installable](installable-code.md) and
 2. [publishing your package to PyPI](publish-pypi.md)
 
 then you already have a **LICENSE** file containing text for the MIT license in your Python package. Thus you can skip to the next section of this tutorial which walks you through adding a CODE_OF_CONDUCT.
@@ -153,7 +153,7 @@ You can use your code of conduct as a tool that can be referenced when moderatin
 If you are unsure of what language to add to your `CODE_OF_CONDUCT`
 file, we suggest that you adopt the [contributor covenant language](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as a starting place.
 
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](#)
+![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)
 
 The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, similar to the LICENSE file.
 
diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
@@ -3,7 +3,7 @@
 In the previous lessons you learned:
 
 1. [What a Python package is](intro.md)
-2. [How to make your code installable](1-installable-code)
+2. [How to make your code installable](installable-code)
 3. [How to publish your package to (test) PyPI](publish-pypi.md)
 4. [How to publish your package to conda-forge](publish-conda-forge.md)
 
@@ -196,6 +196,10 @@ Short description here using non-technical language that describes what your pac
 
 ## How to install pyosPackage
 
+:::{todo}
+- when i add more to the pyos package this can use that readme>
+:::
+
 To install this package run:
 
 `pip install pyosPackage`
@@ -217,11 +221,14 @@ You can also add any links to tutorials in your documentation here.
 
 ## Community
 
-Add information here about contributing to your package. Be sure to add links to your `CODE_OF_CONDUCT.md` file and your development guide. For now this section might be empty. You can go back and fill it in later.
+Add information here about contributing to your package. Be sure to add links to your
+`CODE_OF_CONDUCT.md` file and your development guide. For now this section might be
+empty. You can go back and fill it in later.
 
 ## How to cite pyosPackage
 
 citation information here
+````
 
 ## <i class="fa-solid fa-hands-bubbles"></i> Wrap up
 
diff --git a/tutorials/get-to-know-hatch.md b/tutorials/get-to-know-hatch.md
@@ -111,7 +111,7 @@ hatch config show will print out the contents of your config.toml file in your s
 Hatch offers a suite of features that will make creating, publishing
 and maintaining your Python package easier.
 
-:::{admonition}
+:::{admonition} Comparison to other tools
 :class: tip
 [We compared hatch to several of the other popular packaging tools in the ecosystem including flit, pdm and poetry. Learn more here](package-features)
 :::
diff --git a/tutorials/installable-code.md b/tutorials/installable-code.md
@@ -229,10 +229,9 @@ pyospackage # This is your project directory
 
 ```
 
-## Step 2: Add code to your package
+## Step 2: Add module to your package
 
-Within the `pyospackage` subdirectory, add one or more Python modules.
-A Python module refers to a `.py` file containing the code that you want your package to access and run.
+A Python module refers to a `.py` file containing the code that you want your package to access and run. Within the `pyospackage` subdirectory, add at least one Python modules (.py files).
 
 If you don't have code already and are just learning how to create a Python package, then create an empty `add_numbers.py` file. You will
 populate the `add_numbers.py` file with code provided below.
@@ -258,7 +257,7 @@ pyospackage/
        ├── add_numbers.py
 ```
 
-## Step 3. Add code to your `add_numbers.py` module
+## Step 3: Add code to your module
 
 If you are following along and making a Python package from scratch then you can add the code below to your `add_numbers.py` module. The function below adds two integers together and returns the result. Notice that the code below has a few features that we will review in future tutorials:
 
@@ -298,7 +297,7 @@ def add_num(a: int, b: int) -> int:
     return a + b
 ```
 
-## Step 4. Modify metadata in your `pyproject.toml` file
+## Step 4: Modify metadata in your `pyproject.toml` file
 
 Next, you will modify some of the metadata (information) that
 Hatch adds to your `pyproject.toml` file. You are
@@ -404,18 +403,28 @@ You will learn how to automate defining a package
 version using git tags in the version and release your package lesson.
 :::
 
-### Step 3: Adjust your project classifiers
+### OPTIONAL: Adjust project classifiers
 
 Hatch by default provides a list of classifiers that define what
-Python versions your package supports. While this won't impact your package build, let's remove some of them that you likely don't need.
+Python versions your package supports. These classifiers do not
+in any way impact your package's build and are primarily
+intended to be used when you publish your package to PyPI.
 
-* Remove support for python 3.8
+If you don't plan on publishing to PyPI, you can skip this section.
+However, if you wish, you can clean it up a bit.
 
-Also because we are assuming you're creating a pure Python package, you can remove the following classifiers:
+To begin:
+
+* Remove support for Python 3.8
+
+Also because you are creating a pure Python package, you can
+in this lesson, you can remove the following classifiers:
 
 ```toml
+classifiers = [
 "Programming Language :: Python :: Implementation :: CPython",
 "Programming Language :: Python :: Implementation :: PyPy",
+]
 ```
 
 Your new pyproject.toml file should now look something like this:
@@ -462,7 +471,7 @@ Once you have your project metadata in the pyproject.toml file, you will
 rarely update it. In the next lesson you’ll add more metadata and structure to this file.
 :::
 
-## Step 5. Install your package locally
+## Step 5: Install your package locally
 
 At this point you should have:
 
@@ -480,7 +489,7 @@ While you can do this using hatch, we are going to use pip for this lesson, so y
 
 :::{todo}
 Add this back in when the lesson is published
-- Activate the Python environment that you wish to use. If you need help with working with virtual environments [check out this lesson](extras/1-create-environment.md).
+- Activate the Python environment that you wish to use. If you need help with working with virtual environments check out this lesson (add link).
 :::
 
 ```bash
@@ -562,7 +571,7 @@ pyosPackage                   0.1.0          /Users/yourusername/path/here/pyosP
 ...
 ```
 
-## 6. Test out your new package
+## Step 6: Test out your new package
 
 After installing your package, type “python” at the command prompt in your chosen terminal to start
 a Python session in your active Python environment.
@@ -613,13 +622,11 @@ In the upcoming lessons you will:
 * Add more metadata to your `pyproject.toml` file to support PyPI publication.
 * learn how to publish to **conda-forge** from **PyPI**.
 
-
 * Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to your package
-* [Add more metadata to your `pyproject.toml`](5-pyproject-toml.md) file to support PyPI publication.
+* [Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to support PyPI publication.
 * [Learn how to build your package distribution](publish-pypi) files (**sdist** and **wheel**) and publish to **test PyPI**.
 * Finally you will learn how to [publish to **conda-forge**](publish-conda-forge) from **PyPI**.
 
-
 ## Footnotes
 
 [^shell-lesson]: [Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)
diff --git a/tutorials/intro.md b/tutorials/intro.md
@@ -36,7 +36,7 @@ Get to know Hatch <get-to-know-hatch>
 :caption: Create and publish a Python Package
 
 What is a Python package? <self>
-Make your code installable <1-installable-code>
+Make your code installable <installable-code>
 Publish to PyPI <publish-pypi>
 Publish to conda-forge <publish-conda-forge>
 :::
@@ -290,7 +290,7 @@ You can install a Python package into a Python environment in the same way
 you might install NumPy or Pandas. Installing your package into an environment
 allows you to access it from any code run with that specific Python environment activated.
 
-:::{figure-md} packages-environment
+:::{figure-md} packages-environment-install
 
 <img src="../images/tutorials/environment-package-install.png" alt="Diagram showing the steps associated with creating a package and then installing it. The first arrow says your package and the second says pip install package. The second arrow leads to a box that represents a Python environment that already has some packages installed such as Pandas and NumPy. Your package will also get installed into that same environment when you pip install it." width="700px">
 
@@ -315,11 +315,11 @@ Then you can create a conda-forge recipe using the [Grayskull](https://github.co
 
 [You will learn more about the conda-forge publication process here.](publish-conda-forge.md)
 
-:::{figure-md} build-workflow-tutorial
+:::{figure-md} publish-package-pypi-conda-overview
 <img src="../images/tutorials/publish-package-pypi-conda.png" alt="Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. an arrow to the right takes you to a build distribution files box. that box leads you to either publishing to testPyPI or the real PyPI. From PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." width="700px">
 
 In the image above, you can see the steps associated with publishing
-your package on PyPI and conda-forge. Note that the distribution files that PyPI requires are the [sdist](#python-source-distribution) and [wheel](#python-wheel) files. Once you are ready to make your code publicly installable, you can publish it on PyPI. Once your code is on PyPI it is straight forward to then publish to conda-forge. You create a recipe using the Grayskull package and then you open a pr in the conda-forge recipe repository. You will learn more about this process in the [conda-forge lesson](#).
+your package on PyPI and conda-forge. Note that the distribution files that PyPI requires are the [sdist](#python-source-distribution) and [wheel](#python-wheel) files. Once you are ready to make your code publicly installable, you can publish it on PyPI. Once your code is on PyPI it is straight forward to then publish to conda-forge. You create a recipe using the Grayskull package and then you open a pr in the conda-forge recipe repository. You will learn more about this process in the [conda-forge lesson](/tutorials/publish-conda-forge).
 :::
 
 ## Yay, your package has users! Now what?
@@ -346,5 +346,5 @@ The elements above are also important for future maintenance of your package. In
 In future lessons you will learn more about the infrastructure around a published Python package that makes it both easier to maintain, easier for others to contribute to and easier for other scientists to use. However, first we want to get you to your initial goal of publishing a Python package.
 
 In this next lesson you will learn how to create a basic installable Python package.
-Make your code pip installable <1-installable-code>
+Make your code pip installable <installable-code>
 :::
diff --git a/tutorials/publish-conda-forge.md b/tutorials/publish-conda-forge.md
diff --git a/tutorials/publish-pypi.md b/tutorials/publish-pypi.md
diff --git a/tutorials/pyproject-toml.md b/tutorials/pyproject-toml.md
