diff --git a/package-structure-code/code-style-linting-format.md b/package-structure-code/code-style-linting-format.md index 1616ddc6..7c5975b4 100644 --- a/package-structure-code/code-style-linting-format.md +++ b/package-structure-code/code-style-linting-format.md @@ -174,6 +174,7 @@ Also notice that there are no spaces in the imports listed below. ::: From the project root, run: + ```bash isort src/examplePy/temporal.py ``` diff --git a/tutorials/get-to-know-hatch.md b/tutorials/get-to-know-hatch.md index 9f61cbc3..2dd90617 100644 --- a/tutorials/get-to-know-hatch.md +++ b/tutorials/get-to-know-hatch.md @@ -1,50 +1,121 @@ -# Get to know Hatch +# 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. +Our Python packaging tutorials use the tool +[Hatch](https://hatch.pypa.io/latest/). While there are [many great packaging +tools](/package-structure-code/python-package-build-tools) out there, we have +selected Hatch because: + +1. It is an end-to-end tool that supports most of the steps required to create + a quality Python package. Beginners will have fewer tools to learn if they + use Hatch. +2. It supports different build back-ends if you ever need to compile code in + other languages. +3. As a community, pyOpenSci has decided that Hatch is a user-friendly tool that + supports many different scientific Python use cases. + +In this tutorial, you will install and get to know Hatch a bit more before +starting to use it. + +You need two things to successfully complete this tutorial: + +1. You need Python installed. +2. You need Hatch installed. + +:::{important} +If you don't already have Python installed on your computer, Hatch will do it +for you when you install Hatch. +::: ## Install Hatch -To begin, install Hatch from the command line using [pipx](https://pipx.pypa.io/stable/) + +To begin, follow the operating-system-specific instructions below to install +Hatch. + +::::{tab-set} + +:::{tab-item} MAC + +Follow the instructions [here](https://hatch.pypa.io/latest/install/#installers). + +* Download the latest GUI installer for MAC [hatch-universal.pkg](https://github.com/pypa/hatch/releases/latest/download/hatch-universal.pkg). +* Run the installer and follow the setup instructions. +* If your terminal is open, then restart it. + +::: + +:::{tab-item} Windows + +* In your browser, download the correct `.msi` file for your system: +[hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi) +* Run your downloaded installer file and follow the on-screen instructions. + +::: + +:::{tab-item} Linux + +We suggest that you install Hatch using pipx on Linux. +however, if you prefer another method, check out the [Hatch installation documentation](https://hatch.pypa.io/latest/install/) for other methods. ```bash -pipx install hatch +# First install pipx +> apt install pipx +# Then install hatch using pipx +> pipx install hatch ``` -:::{tip} -Hatch can also be installed directly using `pip` or `conda`, but we encourage you to use `pipx`. -This is because `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. -If you install hatch this way you will have to take care that the environment it is installed into -is activated for the command to work. ::: +:::: + +### Check that hatch installed correctly -You can check that hatch is working properly by issuing a simple command to get the version +Once you have completed the installation instructions above, you can open your +terminal, and make sure that Hatch installed correctly using the command below: ```bash hatch --version # Hatch, version 1.9.4 ``` -Note the version numbers will likely be different +*Note the version number output of `hatch --version` will likely be +different from the output above in this tutorial.* -## Configure hatch +:::{tip} +Hatch can also be installed directly using pip or conda. We encourage you to +follow the instructions above because we have found that the Hatch installers +for Windows and Mac are the easiest and most efficient. + +Our Linux users have found success installing Hatch with pipx if they already +use apt install. + +Both approaches (using a graphical installer on Windows/Mac and pipx) ensure +that you have Hatch installed globally. A global install means that Hatch is +available across all of your Python environments on your computer. +::: -Once you have installed Hatch, you will want to customize the configuration. +## Configure Hatch -Hatch stores your configuration information in a [`config.toml` file](https://hatch.pypa.io/latest/config/project-templates/). +Once you have installed Hatch, you can customize its configuration. This +includes setting the default name and setup for every package you create. While +this step is not required, we suggest that you do it. -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. +Hatch stores your configuration in a [`config.toml` file](https://hatch.pypa.io/latest/config/project-templates/). -### Step 1: Open and edit your `config.toml` file +While you can update the `config.toml` file through the command line, it might +be easier to look at and update it in a text editor if you are using it for the +first time. -To open the config file in your file browser, run the following command in your shell: +### 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. +This will open up a directory window that allows you to double-click on the file +and open it in your favorite text editor. -You can also retrieve the location of the Hatch config file by running the following command in your shell: +You can also retrieve the location of the Hatch config file by running the +following command in your shell: ```bash hatch config find @@ -53,7 +124,9 @@ hatch config find ### 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. +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] @@ -110,7 +183,8 @@ src-layout = true 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 +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. @@ -125,7 +199,9 @@ 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 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 @@ -141,14 +217,12 @@ 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 (see [Migrating setup.py to pyproject.toml using Hatch](setup-py-to-pyproject-toml.md )) 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.