How to Create a Package

import os, tempfile
# Disable Hatch colour
os.environ['NO_COLOR']='1'
os.chdir(tempfile.mkdtemp())

We have already discussed that the main feature of a Distribution package is the additional metadata like the author’s contact details, and description. We will need to define this metadata so that it can be used to build the distribution. At this point, it is necessary to start talking about packaging tools and standards.

Create your first package with Hatch¶

All of this history is quite confusing. Understandably, people have built tools that hide all of this complexity, and provide additional features like environment management, tool support, etc. You need to make a choice about which tool to use. It’s quite hard to make a choice without knowing how to compare the different options, so I’m going to suggest we use Hatch. Ultimately, it’s quite easy to switch between these tools, so don’t worry about making the “perfect” choice. See the Packaging Python Projects for more detail.

Defining your project scaffolding¶

The most important file in modern Python packaging is the pyproject.toml file. It has three important sections:

Any modern Python Build backend should understand the contents of the [project] table. The hatch new command makes it easy to get started with this:

!hatch new arrow-to-knee

arrow-to-knee
├── src
│   └── arrow_to_knee
│       ├── __about__.py
│       └── __init__.py
├── tests
│   └── __init__.py
├── LICENSE.txt
├── README.md
└── pyproject.toml

Customising your pyproject.toml¶

Hatch has created several files and directories under a new directory ./arrow-to-knee/. Let’s first take a glance at the pyproject.toml:

!head arrow-to-knee/pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "arrow-to-knee"
dynamic = ["version"]
description = ''
readme = "README.md"
requires-python = ">=3.8"

You can see that there’s already some metadata here like the [build-system] table, and the required Python version. A helpful overview of these fields and their supported values is given in Writing your pyproject.toml.

Upgrade an existing project to use Hatch¶

If you already have a Python package that was designed to use setuptools, hatch comes with an easy-to-use upgrade tool, hatch new --init:

hatch new --init

This command will ask you a few questions, and upgrade your project to use Hatch!

Build your first distributions¶

With our basic project scaffolding, we have all the pieces required to build our first distributions! The hatch build command does everything we need:

%%bash
cd ./arrow-to-knee
hatch build

─────────────────────────────────�

��── sdist ────────────────────────────�

��────────

Setting up build environment

dist/arrow_to_knee-0.0.1.tar.gz

─────────────────────────────────�

��── wheel ────────────────────────────�

��────────

dist/arrow_to_knee-0.0.1-py3-none-any.whl

We can look at these distributions just like we did in Notebook-code!