this is a test does it work?
diff --git a/images/environment-package-install.png b/images/environment-package-install.png deleted file mode 100644 index 9011fec4..00000000 Binary files a/images/environment-package-install.png and /dev/null differ diff --git a/images/tutorials/packaging-lifecycle.png b/images/tutorials/packaging-lifecycle.png new file mode 100644 index 00000000..4a711ec6 Binary files /dev/null and b/images/tutorials/packaging-lifecycle.png differ diff --git a/tutorials/6-publish-pypi.md b/tutorials/6-publish-pypi.md index 6fa7d33b..a4f9e6c7 100644 --- a/tutorials/6-publish-pypi.md +++ b/tutorials/6-publish-pypi.md @@ -1,35 +1,36 @@ # Publish your Python package to PyPI + -* How to set up your account and package on PyPI and -* How to manually publish to (test) PyPI using [twine](https://twine.readthedocs.io/en/stable/). -In a followup lesson, you will learn how to automate publishing to PyPI using GitHub actions. +In the previous lessons, you've learned: +1. How to make your code pip installable. +2. How to add a `README`, `LICENSE` & `CODE of CONDUCT` file file to your package +3. How to setup your `pyproject.toml` file to support publishing on PyPI. :::{admonition} Learning Objectives :class: tip In this lesson you will learn how to: -- How to build your package's sdist and wheel distributions +- How to build your package's source (sdist) and wheel distributions - Setup an account on testPyPI (the process is similar for the real PyPI) -- Publish your package to testPyPI +- Publish your package to testPyPI using [twine](https://twine.readthedocs.io/en/stable/) Once your package is on PyPI you can then easily publish it to conda-forge using the [grayskull](https://conda.github.io/grayskull/) tool. You do not need to build the package specifically for conda, conda-forge will build from your PyPI source distribution file (sdist). You will learn how to publish to conda-forge in the [next lesson](7-publish-conda-forge.md). +In a followup lesson, you will learn how to automate publishing to PyPI using GitHub actions. ::: :::{figure-md} build-workflow-tutorial @@ -41,9 +42,7 @@ You need to build your Python package in order to publish it to PyPI (or Conda). ## Test PyPI.org vs PyPI @@ -57,7 +56,7 @@ The steps for publishing on test PyPI vs. real PyPI are the same with the exception of a different url. Thus, in this lesson you will use testPyPI to practice and learn. - @@ -125,8 +124,7 @@ files. This process is known as building your package. - + 3. You are now ready to build your package! Note that here you are using the [PyPA build tool](https://github.com/pypa/build) as a "Front end" tool that builds your package's sdist and wheel using the hatchling build back end. Remember that you defined your build backend here in the build system table of your `pyproject.toml` file. So build knows to use [hatchling](https://hatch.pypa.io/latest/). @@ -175,7 +173,7 @@ lesson. You've now created your package distribution. You're officially on your way to publishing your package on PyPI. -## 2. Setup your testPyPI account +## Step 2. Setup your testPyPI account Next, you'll setup an account on `testPyPI`. Remember that you are using testPyPI here instead of the real PyPI as a way to @@ -212,7 +210,7 @@ While you don't have to setup 2-factor authentication, we strongly suggest that you do so. ::: -## 3. Create a package upload token +## Step 3. Create a package upload token To upload your package to PyPI, you will need to create a token. Ideally this token is specific to the package that you are publishing. @@ -269,6 +267,7 @@ NOTE: the `.pypirc` file stores your token in plain text format. Thus, in anothe ::: +:::{admonition} using a .pypirc file if your always publishing manually ### Create your `.pypirc` file with authentication information To create your `.pypirc` file, do the following. @@ -297,6 +296,8 @@ Save the file and then check that it looks correct in bash using the `cat` comma $ cat ~/.pypirc ``` +::: + Now, install twine: ::::{tab-set} @@ -436,6 +437,23 @@ you wish to install your newly published package in. :::: +:::{admonition} The value of end-to-end tools like hatch, flit and poetry +In this lesson we are using core tools including: + +* hatchling +* PyPA's build +* twine + +to build and publish your package to PyPI. + +End-to-end packaging tools such as Hatch, PDM, Poetry and +Flit can manage all of the above steps but have to be +configured. + +For example, while twine users a `.pypirc` file, Hatch will cache your PyPI token information to make publishing to PyPI from your computer easier. Be sure the read the documentation for any end-to-end publication tool that you chose to use. +::: + + + + @@ -17,7 +54,7 @@ create a Python package.
-TODO: this will not be the final graphic but i want to provide the user within a roadmap. i'm intentionally splitting out each topic into lessons so people can also chose to select a topic they are having issues with rather than going through the entire thing looking for a specific topic.
+TODO: This will be replaced with a interactive CSS element that walks users through lessons
:::
## Who are these tutorials for?
@@ -31,22 +68,9 @@ understand the steps for creating a Python package.
set of blocks that are colored. then you could hover over each on to get to the lesson of choice. this would make it easier to also
customize each page with that block at the top -->
-:::{admonition} Lesson Outline
-:class: important
-
-Below are the lessons contained in the packaging 101 series. In this series you will learn about the core elements that you need to publish your package to PyPI.
-
-* What is a Python package?
-* [Make your code pip installable](1-installable-code.md)
-* Add a README file
-* Add a LICENSE file
-* Make your package PyPI ready
-* Publish your package to PyPI
-* Publish your package to Conda Forge
+In this series you will learn about the core elements that you need to publish your package to PyPI.
In the second series, you will learn about infrastructure and documentation needed to support package maintenance.
-:::
-
```{toctree}
:hidden:
@@ -75,7 +99,14 @@ After reading this lesson you will:
:::
-A Python package is a collection of related modules / code containing functions, classes and methods that are organized together in a directory. Packages allow you to group and structure your Python code, making it easier to manage and reuse code across different projects.
+A Python package is a collection of related modules / code containing
+functions, classes and methods that are organized together in a directory.
+Packages allow you to group and structure your Python code, making it easier
+to manage and reuse code across different projects.
+
+A package is installable which means that you can add the functionality within
+the package code to any Python environment and import that functionality like
+you would import numpy or matplotlib.
At a high level, you can think about each package as a toolbox filled with
different tools that perform specific actions in your code when imported and
@@ -126,9 +157,11 @@ If you intend for others to use and contribute to your code, consider who will m
:::{admonition} What pyOpenSci looks for in a package
:class: tip
-pyOpenSci will perform a set of checks for any package submitted.
-You may find these checks useful as you create your package.
-[Core components that pyOpenSci looks for.](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template)
+pyOpenSci performs an [initial set of editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) for any package submitted
+to us for peer review.
+You may find these checks useful as you create your package as a baseline for
+things that you package should have.
+
:::
## Packages are more than just code
@@ -137,12 +170,21 @@ A package in any language is more than just code. If your package is public faci
### Version control and storing your package on GitHub or GitLab
-Most Python packages live in an online version control platform such as GitHub or GitLab. GitHub and GitLab are both online platforms that
+Most Python packages live in an online version control platform such as GitHub
+or GitLab. GitHub and GitLab are both online platforms that
run [git](https://git-scm.com/) for version control. Have your software
under version control is important because it allows you to both track changes over time while also going back in history and undoing changes in the case that a change to the code base unexpectedly breaks something.
By publishing your package on GitHub or GitLab, you are now making your code public facing. this means that others can both see your code and also make contributions using a pull request - review workflow.
+:::{admonition} GitHub & GitLab vs. Git
+:class: tip
+
+GitHub and GitLab are online (cloud) platforms that run git (version control
+software) on the backend. Running git locally on your computer allows you to
+upload (`git push`) and download (`git pull`) files to GitHub and GitLab.
+:::
+
### Continuous integration and continuous deployment help you maintain your package
Platforms such as GitHub and GitLab also provide continuous integration and continuous deployment (CI/CD). Continuous integration (CI) refers to a platform that automatically runs a specific job when a certain event occurs.
@@ -157,10 +199,9 @@ Integrated CI/CD will help you maintain your software ensuing that changes to t
:::{figure-md} packaging-workflow
-
+
-The parts of a Python package... can this diagram be simplified a bit or at least
-use simpler language?? maybe it's like code, docs, metadata, tests, all packaged up in a specific structure that tools can understand and turn into an installable package. that simpler version might be better.
+The lifecycle of a scientific Python package.
:::
-
-**Readable code:** Readable code is code written with a consistent style. You can use linters and code formatters such as black and flake8 to ensure this consistency throughout your entire package. [Learn more about code formatters here.](../package-structure-code/code-style-linting-format.html)
+**Clean code:** Clean code refers to code that uses expressive variable names,
+is concise and does not repeat itself. We will dive deeper into best practices
+for clean code in future pyOpenSci tutorials.
-**Documented code:** documented code is written using docstrings that help a user understand both what the functions and methods in your code does and also what the input and output elements of each function is. [You can learn more about docstrings in our guide, here.](../documentation/write-user-documentation/document-your-code-api-docstrings)
+**Readable code:** Readable code is code written with a consistent style.
+You can use linters and code formatters such as black and flake8 to ensure
+this consistency throughout your entire package. [Learn more about code formatters here.](../package-structure-code/code-style-linting-format.html)
+**Documented code:** documented code is written using docstrings that help a
+user understand both what the functions and methods in your code does and also
+what the input and output elements of each function is. [You can learn more about docstrings in our guide, here.](../documentation/write-user-documentation/document-your-code-api-docstrings)
:::{admonition} Where do research compendia fit in?
:class: note
@@ -228,9 +277,13 @@ allows you to access it from any code run with that specific Python environment
:::{figure-md} packages-environment
-
+
-This is just a concept - the graphic should show that you can turn your script into something that can be installed into a Python environment. Or you can turn your code into a package...
+You don't have to publish to PyPI in order to make your code installable.
+WIth the correct file structure and project metadata you can make your code
+installable locally on your computer and use it for projects that you are working
+on without having to ever publish to PyPI. Publishing to PyPI is useful when you
+want to make your code public facing and share it with others.
:::
### Publishing a package
@@ -243,12 +296,11 @@ In these tutorials, you will learn [how to publish to PyPI using twine.](6-publi
Then you can create a conda-forge recipe using the grayskull tool. This recipe can then be submitted to conda-forge. [You will learn more about the conda-forge publication process here.](7-publish-conda-forge.md)
-:::{figure-md} publish-package
-
+:::{figure-md} build-workflow-tutorial
+
-TODO: make the flower simpler because not all of that goes into the published
-output. make sure to add use grayskull to publish to conda-forge from PyPI.
+Once you are ready to make your code public, you can publish it on PyPI. Once the code is on PyPI it's a simple set of steps to publish to conda forge. You create a recipe using the grayskull package and then you open a pr in the conda-forge recipe repo. You will learn more about this process in the [conda-forge lesson](#).
:::
## Yay, your package has users! Now what?