Building a Django Package — Part 1: Setting Up django-healthkit

In this series, we are going to build a real Django package called django-healthkit and eventually publish it to PyPI.

In this first part, we will create the project from scratch, set up its structure, configure the package, and prepare it for development.

Prerequisites

To follow this tutorial, you should have a basic understanding of:

• Python
• Django
• pip
• Python virtual environments
• Git
• Basic Python package development concepts

We will use Python 3.10 or newer throughout this tutorial.

Creating the Project

First, create a directory for the project:

mkdir django-healthkit
cd django-healthkit

Then create a virtual environment:

python -m venv .venv

Activate the virtual environment.

On Linux and macOS:

source .venv/bin/activate

On Windows:

.venv\\Scripts\\activate

Installing Django

Install Django as a development dependency:

pip install "Django>=4.2"

Project Structure

Now create the initial project structure:

django-healthkit/
├── src/
│   └── django_healthkit/
│       ├── __init__.py
│       ├── apps.py
│       └── migrations/
│           └── __init__.py
├── tests/
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml

We are using the src layout.

The package source code lives inside src/django_healthkit/, while tests are kept in a separate tests/ directory.

Creating the Django App

Create apps.py with the following content:

from django.apps import AppConfig


class DjangoHealthkitConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "django_healthkit"

The __init__.py file makes django_healthkit a Python package.

Creating .gitignore

Create a .gitignore file in the project root:

.venv/

__pycache__/
*.py[cod]

*.egg-info/
build/
dist/

.pytest_cache/
.coverage
htmlcov/

.DS_Store

This prevents virtual environments, Python cache files, build artifacts, and other temporary files from being committed to Git.

Creating pyproject.toml

Now we get to one of the most important files in the project.

The pyproject.toml file contains the configuration required to build the package and defines its metadata and dependencies.

For the initial django-healthkit release, create the following file:

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"


[project]
name = "django-healthkit"
version = "0.1.0"
description = "Health checks for Django applications"
readme = "README.md"
requires-python = ">=3.10"

dependencies = [
    "Django>=4.2",
]

There are several important fields here.

The name field defines the package name that will eventually be published to PyPI:

name = "django-healthkit"

We are starting with version 0.1.0:

version = "0.1.0"

We also specify that Django is required by the package:

dependencies = [
    "Django>=4.2",
]

We will add more metadata and configuration to this file in the following parts.

Creating README.md

Create a README.md file in the project root:

We will expand the README later with documentation and usage examples.

Installing the Package in Editable Mode

Now that the initial structure is ready, install the package in editable mode:

pip install -e .

The -e option, also known as an Editable Install, allows changes to the package source code to be used immediately during development without reinstalling the package after every change.

We can verify that Python can import the package:

python -c "import django_healthkit; print(django_healthkit)"

If Python prints the package path, the package has been installed successfully.

Creating the First Commit

The project is now ready to be initialized as a Git repository:

git init
git add .
git commit -m "chore: initialize django-healthkit package"

At this point, we have not implemented any health checks yet.

The goal of this first part was to create a standard, installable, and maintainable Django package that is ready for further development.

In the next part, we will design the internal structure of django-healthkit and implement our first health checks.