From 4eb21e594a0dc41c839d3814d32ae37d4432a4b6 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Mon, 29 Jan 2024 16:20:17 -0700 Subject: [PATCH 1/4] Fix: use hatch for workflow --- .../python-package-build-tools.md | 4 +- tutorials/1-installable-code.md | 222 ++++++++++++------ tutorials/get-to-know-hatch.md | 125 ++++++++++ tutorials/intro.md | 7 + 4 files changed, 282 insertions(+), 76 deletions(-) create mode 100644 tutorials/get-to-know-hatch.md diff --git a/package-structure-code/python-package-build-tools.md b/package-structure-code/python-package-build-tools.md index 86d5534d..0d63e901 100644 --- a/package-structure-code/python-package-build-tools.md +++ b/package-structure-code/python-package-build-tools.md @@ -1,7 +1,5 @@ # Python Packaging Tools - - ## Tools for building your package There are a several different build tools that you can use to [create your Python package's _sdist_ and _wheel_ distributions](python-package-distribution-files-sdist-wheel). Below, we discuss the features, @@ -361,7 +359,7 @@ Build your sdist and wheel distributions|✅| Hatch will build the sdist and whe ``` -_\*\* There is some argument about this approach placing a burden on maintainers to create a custom build system. But others appreciate the flexibility. The Hatch build hook approach is also comparable with the features offered by PDM._ +_There is some argument about this approach placing a burden on maintainers to create a custom build system. But others appreciate the flexibility. The Hatch build hook approach is also comparable with the features offered by PDM._ ### Why you might not want to use Hatch diff --git a/tutorials/1-installable-code.md b/tutorials/1-installable-code.md index 10c8ad0c..9be8fe75 100644 --- a/tutorials/1-installable-code.md +++ b/tutorials/1-installable-code.md @@ -47,26 +47,18 @@ In this lesson you will learn: **What you need to complete this lesson** To complete this lesson you will need a local Python -environment and shell on your computer. +environment and shell on your computer. You will also need to have [Hatch installed](get-to-know-hatch). -You are welcome to use any Python environment manager that you choose. If you are using Windows or are not familiar with Shell, you may want to check out the Carpentries shell lesson[^shell-lesson]. Windows users will likely need to configure a tool for any Shell and git related steps. -:::{todo} -When this lesson is published, unlink -* [If you need guidance creating a Python environment, review this lesson](extras/1-create-environment.md) which walks you through creating an environment using both `venv` and `conda`. -::: - -* If you aren't sure which environment manager to use and -you are a scientist, we suggest that you use `conda`, particularly if you are working with spatial data. - **What comes next** In the upcoming lessons you will learn how to: +* [Publish your package to PyPI](publish-pypi) * Add a README file to your package to support community use * Add additional project metadata to your package to support PyPI publication -* Publish your package to PyPI + ::: @@ -108,7 +100,7 @@ Notice a few things about the above layout: 1. Within the `src` directory you have a package directory called `pyospackage`. Use the name of your package for that directory name. This will be the name for importing your package in Python code once installed. 1. In your package directory, you have an `__init__.py` file and all of your Python modules. You will learn more about the `__init__.py` file below. 1. The `pyproject.toml` file lives at the root directory of your package. -1. The name of the root directory for the package is **pyospackage** which is the name of the package. This is not a requirement but you will often see that the GitHub / GitLab repo and the root directory name are the same as the package name. +1. The name of the root directory for the package is **pyospackage** which is the name of the package. This is not a requirement but you will often see that the GitHub / GitLab repository and the root directory name are the same as the package name. ### What is an `__init__.py` file? @@ -158,56 +150,43 @@ Neither 'setup.py' nor 'pyproject.toml' found. ## Time to create your Python package! Now that you understand the basics of the Python package directory structure, and associated key files (`__init__.py` and `pyproject.toml`), it's time to create your Python package! -Below you will create a directory structure similar to the structure described above. +Below you will create a directory structure similar to the structure described above using Hatch. -If you don’t wish to create each of the files and directories below, you -can always [fork and clone and customize the pyOpenSci example package.](https://github.com/pyOpenSci/pyosPackage) ## Step 1: Set Up the Package Directory Structure -Below you create the basic directory structure required for your Python package. -Note that there are instructions for creating the files and directories using shell. However you can also create files and directories in your preferred file directory tool (e.g. Finder on macOS or File Explorer on Windows or even a tool such as VS Code or Spyder) if you wish. - -### Create your package's project directory structure -* Create a new project directory for your package. Choose a name for your package, preferably in lowercase and without spaces. For this tutorial we'll use `pyospackage`. - -Inside the project directory: +* Open your shell or preferred terminal. +* cd to the location where you'd like your package directory to live. Hatch will create the package directory for you +* Choose a name for your package, preferably in lowercase and without spaces. For this tutorial we'll use `pyospackage`. -- Create a directory called `src` -- Within the `src` directory, create a directory that is named after your package. This subdirectory will contain your package’s code. -- It is ok if the project directory for your package and the directory in `src` have the same name +Next run: ```bash -# Create a project directory in shell and a src directory within -mkdir -p pyospackage/src/pyospackage - -# Change directory into pyospackage project dir -cd pyospackage - -# View the current file structure -ls +➜ hatch new pyospackage +pyospackage +├── src +│ └── pyospackage +│ ├── __about__.py +│ └── __init__.py +├── LICENSE.txt +├── README.md +└── pyproject.toml ``` -### Add your `__init__.py` and `pyproject.toml` files -Next create two files: -- Inside the package directory, create a new file named `__init__.py` . This file ensures Python sees this directory as a package. You will use this file to customize how parts of your package are imported and to declare your package’s version in a future lesson. -- At the root of your project, create a file called `pyproject.toml` - -```bash -# Create a pyproject.toml file in your project directory -touch pyproject.toml -# Create an empty init file within your src/pyospackage directory -touch src/pyospackage/__init__.py -``` Your final project directory structure should look like this: ```bash -pyospackage/ # This is your project directory - └─ pyproject.toml - └─ src/ # This is your package directory where your code lives - └── pyospackage/ - ├── __init__.py + +pyospackage # This is your project directory +├── src +│ └── pyospackage # This is your package directory where your code lives +│ ├── __about__.py +│ └── __init__.py +├── LICENSE.txt +├── README.md +└── pyproject.toml # this file contains package metadata + ``` ## Step 2: Add code to your package @@ -240,8 +219,8 @@ pyospackage/ 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: -1. It has a [numpy-style docstring](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html#three-python-docstring-formats-and-why-we-like-numpy-style) -2. It uses [typing](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html#adding-type-hints-to-your-docstrings) +1. It has a [numpy-style docstring](numpy-docstring) +2. It uses [typing](type-hints) Python can support many different docstrings formats depending on the documentation build system you wish to use. The most popular supported formats for documenting Python objects are NumPy Style Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext Style Docstrings[^epytextdoc]. @@ -276,9 +255,10 @@ def add_num(a: int, b: int) -> int: return a + b ``` -## Step 4. Add metadata to your `pyproject.toml` file +## Step 4. Modify metadata in your `pyproject.toml` file -Next, you will add some metadata (information) to your `pyproject.toml` file. You are +Next, you will modify some of the metadata (information) that +Hatch adds to your `pyproject.toml` file. You are are welcome to copy the file we have in our [example pyospackage GitHub repository](https://github.com/pyOpenSci/pyosPackage). :::{admonition} Brief overview of the TOML file @@ -295,26 +275,108 @@ For instance, a `build-system` table most often holds two (2) variables: [hatchling](https://pypi.org/project/hatchling/) 2. `build-backend = `, which is used to define the specific build-backend name, (in this example we are using `hatchling.build`). +```toml +# An example of the build-system table which contains two variables - requires and build-backend +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" +``` + TOML organizes data structures, defining relationships within a configuration file. +[Learn more about the pyproject.toml format here.](../package-structure-code/pyproject-toml-python-package-metadata) +::: + :::{todo} You will learn more about the `pyproject.toml` format in the [next lesson when you add additional metadata / information to this file.](5-pyproject-toml.md) ::: +- Open up the `pyproject.toml` file that Hatch created in your favorite text editor. Is should look something like the example below. + + ```toml -# An example of the build-system table which contains two variables - requires and build-backend [build-system] requires = ["hatchling"] build-backend = "hatchling.build" + +[project] +name = "pyospackage" +dynamic = ["version"] +description = '' +readme = "README.md" +requires-python = ">=3.8" +license = "MIT" +keywords = [] +authors = [ + { name = "Leah Wasser", email = "leah@pyopensci.org" }, +] +classifiers = [ + "Development Status :: 4 - Beta", + "Programming Language :: Python", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: Implementation :: CPython", + "Programming Language :: Python :: Implementation :: PyPy", +] +dependencies = [] + +[project.urls] +Documentation = "https://github.com/unknown/pyospackage#readme" +Issues = "https://github.com/unknown/pyospackage/issues" +Source = "https://github.com/unknown/pyospackage" + +[tool.hatch.version] +path = "src/pyospackage/__about__.py" + ``` -[Learn more about the pyproject.toml format here.](../package-structure-code/pyproject-toml-python-package-metadata) +Edit the file as follows: + +1. Delete `dynamic = ["version"]`: This sets up dynamic versioning based on tags stored in your git commit history. We will walk through implementing this in a later lesson. +2. Add `version = 0.1.0` in the place of `dynamic = ["version"]` which you just deleted. This sets up manual versioning. +3. Fill in the description if it doesn't already exist. + +```toml +[project] +name = "pyospackage" +# dynamic = ["version"] <- replace this... +version = 0.1 # with this +description = 'A simple Python package that adds numbers together' # Add a description of your package if that is not already populated +``` + +3. Remove the `[tool.hatch.version]` table from the bottom of the file. + +```toml +[tool.hatch.version] +path = "src/pyospackage/__about__.py" +``` + +:::{note} +You will learn how to automate defining a package +version using git tags in the version and release your package lesson. ::: -- Open up your `pyproject.toml` file in your favorite text editor. -- Add the metadata below to your `pyproject.toml` +### Step 3: Adjust your 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. + +* Remove support for python 3.8 + +Also because we are assuming you're creating a pure Python package, you can remove the following classifiers: + +```toml +"Programming Language :: Python :: Implementation :: CPython", +"Programming Language :: Python :: Implementation :: PyPy", +``` + +Your new pyproject.toml file should now look something like this: + ```toml [build-system] @@ -322,17 +384,32 @@ requires = ["hatchling"] build-backend = "hatchling.build" [project] -name = "pyospackage" # rename this if you plan to publish to test PyPI -# Here you add the package version manually. -# You will learn how to setup dynamic versioning in a followup tutorial. -version = "1.1.0" +name = "pyospackage" +version = "0.1.0" +description = 'A python package that adds numbers together.' +readme = "README.md" +requires-python = ">=3.9" +license = "MIT" +keywords = [] +authors = [ + { name = "FirstName LastName", email = "youremail@youremail.org" }, +] +classifiers = [ + "Development Status :: 4 - Beta", + "Programming Language :: Python", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", +] +dependencies = [] + +[project.urls] +Documentation = "https://github.com/unknown/pyospackage#readme" +Issues = "https://github.com/unknown/pyospackage/issues" +Source = "https://github.com/unknown/pyospackage" ``` - -Note that above you manually add your package's version number to the -`pyproject.toml` file. You will learn how to automate defining a package -version using git tags in the version and release your package lesson. - :::{admonition} The bare minimum needed in a pyproject.toml file :class: tip @@ -352,11 +429,11 @@ At this point you should have: You are now ready to install (and build) your Python package! -Let’s try it out. +While you can do this using hatch, we are going to use pip for this lesson, so you can see how to install your tool into your preferred environment. -- First open your preferred shell (Windows users may be using something like gitbash) and `cd` into your project directory +- First open your preferred shell (Windows users may be using something like gitbash) and `cd` into your project directory if you are not already there. - Activate the Python environment that you wish to use. -- Finally run `python -m pip install -e .` +- Run `python -m pip install -e .` :::{todo} Add this back in when the lesson is published @@ -484,15 +561,14 @@ pyOpenSci repository. ## Congratulations! You created your first Python package You did it! You have now created a Python package that you can install -into any Python environment. While there is still more to do if you want -to publish your package, you have completed the first major step. +into any Python environment. In the upcoming lessons you will: +* Learn how to [build and publish your Python package to (test) PyPI](publish-pypi) * Add a README file and LICENSE to your package * Add more metadata to your `pyproject.toml` file to support PyPI publication. -* Learn how to build your package distribution files (**sdist** and **wheel**) and publish to **test PyPI**. -* Finally you will learn how to publish to **conda-forge** from **PyPI**. +* learn how to publish to **conda-forge** from **PyPI**. :::{todo} This is the content with links once the links are live we can uncomment this and remove the unlinked content above! diff --git a/tutorials/get-to-know-hatch.md b/tutorials/get-to-know-hatch.md new file mode 100644 index 00000000..6ae7a224 --- /dev/null +++ b/tutorials/get-to-know-hatch.md @@ -0,0 +1,125 @@ +# Get to know hatch + +Our Python packaging tutorials use the tool Hatch. +In this tutorial, you will install and get to know hatch a bit more before starting to use it. + +## Install Hatch +To begin, install Hatch following the +[instructions here](https://hatch.pypa.io/latest/install/). + +:::{tip} +If you are comfortable using [pipx](https://pipx.pypa.io/stable/) to install hatch, we encourage you to do so. pipx will ensure that your package is available across all of your Python environments on your computer rather than just in the environment that you install it into. + +However if you are not sure about pipx, you can install hatch using pip or conda. +::: + +### Configure hatch + +Once you have installed hatch, you will want to customize the configuration. + +Hatch stores your configuration information in a [config.toml file](https://hatch.pypa.io/latest/config/project-templates/). + +While you can update the `config.toml` file through the command line, +it might be easier to look at it and update it in a text editor if you are using it for the first time. + +### Step 1: Open and edit your config.toml file + +To open the config file in your file browser, run the following command in your shell: + +`hatch config explore` + +This will open up a directory window that will allow you to double click on the file and open it in your favorite text editor + +### Step 2 - update your email and name + +Once the file is open, update the [template] table of the config.toml file with your name and email. This information will be used in any pyproject.toml metadata files that you create using hatch. + +```toml +[template] +name = "firstName LastName" +email = "your-email@your-domain.org" +``` + +### Step 3 + +Next, set tests to false in the `[template.plugins.default]` table. + +While tests are important, setting tests to true will create a more complex pyproject.toml file. That we won't need to use in this beginner friendly tutorial series. + +Your config.toml file should look something like the one below. It's ok if you have + +```toml +mode = "local" +project = "" +shell = "" + +[dirs] +project = [] +python = "isolated" +data = "/Users/your/path/Application Support/hatch" +cache = "/Users/your/path/Library/Caches/hatch" + +[dirs.env] + +[projects] + +[publish.index] +repo = "main" + +[template] +name = "Leah Wasser" +email = "leah@pyopensci.org" + +[template.licenses] +headers = true +default = [ + "MIT", +] + +[template.plugins.default] +tests = false +ci = false +src-layout = true + +[terminal.styles] +``` + +Also notice that the default license option is MIT. While we will discuss license in more detail in a later lesson... the MIT license is the recommended permissive license from choosealicense.com and as such we will use it for this tutorial series. + +You are of course welcome to select another license + +:::{todo} +I think we'd need the SPDX license options here if they want to chose bsd-3 for instance +::: + +### Step 4: Close the config file and run hatch config show + +Once you have completed the steps above run the following command in your shell. + +`hatch config show` + +hatch config show will print out the contents of your config.toml file in your shell. look at the values and ensure that your name, email is set. Also make sure that tests=false. + +## Hatch features + +Hatch offers a suite of features that will make creating, publishing +and maintaining your Python package easier. + +:::{admonition} +: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) +::: + +[More on hatch here](hatch) + +A few features that hatch offers + +1. it will convert metadata stored in a setup.py or setup.cfg file to a pyproject.toml file for you. While we haove not extensively tested this feature yet, please let us know if you try it! +2. It will help you by storing configuration information for publishing to PyPI after you've entered it once. + +Use `hatch -h` to see all of the available commands. + + +## What's next + +In the next lesson you'll learn how to package and make your code installable using Hatch. diff --git a/tutorials/intro.md b/tutorials/intro.md index 964a1601..44517122 100644 --- a/tutorials/intro.md +++ b/tutorials/intro.md @@ -24,6 +24,13 @@ understanding the steps involved in creating a Python package. * In the second series, you will learn about infrastructure and documentation needed to support package maintenance. +:::{toctree} +:hidden: +:caption: Python Packaging Tutorial Setup + +Get to know Hatch +::: + :::{toctree} :hidden: :caption: Python Packaging 101 From 4e1d595532f98ef5035f2b0bcd111a551900c00f Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 30 Jan 2024 11:05:30 -0700 Subject: [PATCH 2/4] Fix: Edits from review --- tutorials/1-installable-code.md | 8 +++++--- tutorials/get-to-know-hatch.md | 9 ++++++--- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/tutorials/1-installable-code.md b/tutorials/1-installable-code.md index 9be8fe75..78b62a04 100644 --- a/tutorials/1-installable-code.md +++ b/tutorials/1-installable-code.md @@ -156,8 +156,10 @@ Below you will create a directory structure similar to the structure described a ## Step 1: Set Up the Package Directory Structure * Open your shell or preferred terminal. -* cd to the location where you'd like your package directory to live. Hatch will create the package directory for you -* Choose a name for your package, preferably in lowercase and without spaces. For this tutorial we'll use `pyospackage`. +* Use the shell `cd` command to navigate in your shell to the location where you'd like your package directory to live. Hatch will create the package directory for you +* Choose a name for your package. The name should: + * Have no spaces (*Required*) + * Use all lowercase characters (*Recommended*). For this tutorial we will use `pyospackage`. Next run: @@ -293,7 +295,7 @@ You will learn more about the `pyproject.toml` format in the [next lesson when you add additional metadata / information to this file.](5-pyproject-toml.md) ::: -- Open up the `pyproject.toml` file that Hatch created in your favorite text editor. Is should look something like the example below. +- Open up the `pyproject.toml` file that Hatch created in your favorite text editor. It should look something like the example below. ```toml diff --git a/tutorials/get-to-know-hatch.md b/tutorials/get-to-know-hatch.md index 6ae7a224..61183b96 100644 --- a/tutorials/get-to-know-hatch.md +++ b/tutorials/get-to-know-hatch.md @@ -13,7 +13,7 @@ If you are comfortable using [pipx](https://pipx.pypa.io/stable/) to install hat However if you are not sure about pipx, you can install hatch using pip or conda. ::: -### Configure hatch +## Configure hatch Once you have installed hatch, you will want to customize the configuration. @@ -44,7 +44,10 @@ email = "your-email@your-domain.org" Next, set tests to false in the `[template.plugins.default]` table. -While tests are important, setting tests to true will create a more complex pyproject.toml file. That we won't need to use in this beginner friendly tutorial series. +While tests are important, setting the tests configuration in Hatch +to `true` will create a more complex pyproject.toml file. You won't +need to use this feature in this beginner friendly tutorial series +but we will introduce it in later tutorials. Your config.toml file should look something like the one below. It's ok if you have @@ -114,7 +117,7 @@ and maintaining your Python package easier. A few features that hatch offers -1. it will convert metadata stored in a setup.py or setup.cfg file to a pyproject.toml file for you. While we haove not extensively tested this feature yet, please let us know if you try it! +1. it will convert metadata stored in a setup.py or setup.cfg file to a pyproject.toml file for you. While we have not extensively tested this feature yet, please let us know if you try it! 2. It will help you by storing configuration information for publishing to PyPI after you've entered it once. Use `hatch -h` to see all of the available commands. From 4b923a46bc927cc7fd7b19b3946bccba607cac98 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 14 Feb 2024 18:37:48 -0700 Subject: [PATCH 3/4] Fix: edits from review --- tutorials/1-installable-code.md | 54 +++++++++++++++++++++++++++++---- tutorials/get-to-know-hatch.md | 7 +++-- 2 files changed, 53 insertions(+), 8 deletions(-) diff --git a/tutorials/1-installable-code.md b/tutorials/1-installable-code.md index 78b62a04..72317edf 100644 --- a/tutorials/1-installable-code.md +++ b/tutorials/1-installable-code.md @@ -160,10 +160,48 @@ Below you will create a directory structure similar to the structure described a * Choose a name for your package. The name should: * Have no spaces (*Required*) * Use all lowercase characters (*Recommended*). For this tutorial we will use `pyospackage`. + * Only use letter and the characters _ or - in the name. This means that the name `pyos*package` is not an acceptable name. However, the names `pyos_package` or `pyos-package` both are ok -Next run: +:::{admonition} Hatch and project names +Hatch makes some decisions for your project's name when you run `hatch new` + +These include using: +* dashes for the top level directory +* dashes for the project name in the pyproject.toml +* underscores for the package directory name ```bash +❯ hatch new pyos-package +pyos-package +├── src +│ └── pyos_package +│ ├── __about__.py +│ └── __init__.py +├── LICENSE.txt +├── README.md +└── pyproject.toml + +``` +If you use a name with underscores, Hatch will return the same thing: + +```bash +➜ hatch new pyos_package +pyos-package +├── src +│ └── pyos_package +│ ├── __about__.py +│ └── __init__.py +├── LICENSE.txt +├── README.md +└── pyproject.toml +``` +In both of the examples above the project name in the pyproject.toml file that hatch creates is `pyos-package`. +::: + + +Next run: + +```console ➜ hatch new pyospackage pyospackage ├── src @@ -193,8 +231,11 @@ pyospackage # This is your project directory ## Step 2: Add code to your package -Within the `pyospackage` subdirectory, add one (1) or more Python modules (.py files) containing the code that you want your package to access and run. -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. +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. + +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. :::{admonition} Python modules and the `__init__.py` file :class: tip @@ -202,7 +243,7 @@ If you don't have code already and are just learning how to create a Python pack When you see the word module, we are referring to a `.py` file containing Python code. -The `__init__.py` allows Python to recognize that a directory contains at least one (1) module that may be imported and used in your code. +The `__init__.py` allows Python to recognize that a directory contains at least one module that may be imported and used in your code. A package can have multiple modules[^python-modules]. ::: @@ -228,7 +269,7 @@ Python can support many different docstrings formats depending on the documentat **pyOpensci recommends using the NumPy Docstring convention.** -If you aren’t familiar with docstrings or typing yet, that is ok. We will get to it later in our tutorial series. Or, you can review the pyOpenSci [packaging guide](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html) for an overview. +If you aren’t familiar with docstrings or typing yet, that is ok. You can review [this page in the pyOpenSci packaging guide](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html) for an overview of both topics. ```python def add_num(a: int, b: int) -> int: @@ -358,7 +399,8 @@ description = 'A simple Python package that adds numbers together' # Add a descr path = "src/pyospackage/__about__.py" ``` -:::{note} +:::{todo} +When this lesson exists, uncomment this admonition You will learn how to automate defining a package version using git tags in the version and release your package lesson. ::: diff --git a/tutorials/get-to-know-hatch.md b/tutorials/get-to-know-hatch.md index 61183b96..57748e89 100644 --- a/tutorials/get-to-know-hatch.md +++ b/tutorials/get-to-know-hatch.md @@ -49,7 +49,7 @@ to `true` will create a more complex pyproject.toml file. You won't need to use this feature in this beginner friendly tutorial series but we will introduce it in later tutorials. -Your config.toml file should look something like the one below. It's ok if you have +Your `config.toml` file should look something like the one below. ```toml mode = "local" @@ -87,7 +87,10 @@ src-layout = true [terminal.styles] ``` -Also notice that the default license option is MIT. While we will discuss license in more detail in a later lesson... the MIT license is the recommended permissive license from choosealicense.com and as such we will use it for this tutorial series. +Also notice that the default license option is MIT. While we will discuss +license in more detail in a later lesson, the MIT license is the +recommended permissive license from [choosealicense.com](https://www.choosealicense.com) and as such we will +use it for this tutorial series. You are of course welcome to select another license From be44491b41a00f124c28b30643d851cb85e0b8d4 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Wed, 14 Feb 2024 18:51:29 -0700 Subject: [PATCH 4/4] Fix: spelling and grammar --- tutorials/1-installable-code.md | 4 ++-- tutorials/get-to-know-hatch.md | 2 +- tutorials/intro.md | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tutorials/1-installable-code.md b/tutorials/1-installable-code.md index 72317edf..a25be592 100644 --- a/tutorials/1-installable-code.md +++ b/tutorials/1-installable-code.md @@ -232,7 +232,7 @@ pyospackage # This is your project directory ## Step 2: Add code 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. 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. @@ -267,7 +267,7 @@ If you are following along and making a Python package from scratch then you can Python can support many different docstrings formats depending on the documentation build system you wish to use. The most popular supported formats for documenting Python objects are NumPy Style Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext Style Docstrings[^epytextdoc]. -**pyOpensci recommends using the NumPy Docstring convention.** +**pyOpenSci recommends using the NumPy Docstring convention.** If you aren’t familiar with docstrings or typing yet, that is ok. You can review [this page in the pyOpenSci packaging guide](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html) for an overview of both topics. diff --git a/tutorials/get-to-know-hatch.md b/tutorials/get-to-know-hatch.md index 57748e89..11cd57c8 100644 --- a/tutorials/get-to-know-hatch.md +++ b/tutorials/get-to-know-hatch.md @@ -120,7 +120,7 @@ and maintaining your Python package easier. A few features that hatch offers -1. it will convert metadata stored in a setup.py or setup.cfg file to a pyproject.toml file for you. While we have not extensively tested this feature yet, please let us know if you try it! +1. it will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you. While we have not extensively tested this feature yet, please let us know if you try it! 2. It will help you by storing configuration information for publishing to PyPI after you've entered it once. Use `hatch -h` to see all of the available commands. diff --git a/tutorials/intro.md b/tutorials/intro.md index 44517122..d820c8e2 100644 --- a/tutorials/intro.md +++ b/tutorials/intro.md @@ -7,7 +7,7 @@ create a Python package. :::{figure-md} packaging-outline -Diagram showing the lessons in our packaging tutorial. There are 6 total - what is a python package, make code pip installable, publish your package to PyPI, add a readme and license file, add metadata for pypi and finally publish to conda forge. +Diagram showing the lessons in our packaging tutorial. There are 6 total - what is a Python package, make code pip installable, publish your package to PyPI, add a README and LICENSE file, add metadata for PyPI and finally publish to conda forge. This lesson is the first in a series of lessons to help you get started with Python packaging. ::: @@ -278,12 +278,12 @@ what the input and output elements of each function are. [You can learn more abo ### Python packages and environments 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 +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 -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. +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. You don't have to publish to PyPI to make your code installable. With the correct file structure and project metadata you can make your code