Build Process for OpenMed: Complete Packaging and Distribution Guide

The OpenMed build process uses Hatchling as the build backend and a Makefile to automate the creation of source distributions and wheels via python3 -m build, with optional publishing to PyPI through hatch publish.

OpenMed is a Python package managed in the maziyarpanahi/openmed repository that adheres to modern Python packaging standards. The build process for OpenMed relies on Hatchling as the build backend, orchestrated through a convenient Makefile that handles everything from environment setup to PyPI publication.

Prerequisites and Environment Setup

Before building OpenMed, ensure you have Python 3.10 or higher installed. The project recommends using the uv package manager for fast, reproducible environment management.

1. Install uv if you haven't already:

   pip install uv

2. Create a clean virtual environment:

   uv venv
   source .venv/bin/activate

3. Install build-time dependencies:

   uv pip install hatchling build

Build System Configuration

The build configuration resides in pyproject.toml at the repository root. According to the OpenMed source code, the file declares hatchling as the build backend:

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

Version tracking is handled dynamically. Hatch reads the version from openmed/__about__.py as specified in the pyproject.toml:

[tool.hatch.version]
path = "openmed/__about__.py"

Building the Package

The Makefile provides the primary interface for building. To create both a source distribution (.tar.gz) and a wheel (.whl), run:

make build

This command invokes python3 -m build, which generates the distribution artifacts in the dist/ directory. You can verify the output:

ls dist/

# ├── openmed-0.1.0-py3-none-any.whl

# └── openmed-0.1.0.tar.gz

Alternatively, you can run the build command directly without Make:

python3 -m build

Makefile Targets and Build Automation

The Makefile in the repository root defines several targets that streamline the build process for OpenMed:

• make build – Executes python3 -m build to generate distribution files
• make clean – Removes dist/, build/, and *.egg-info/ directories
• make publish – Calls hatch publish to upload artifacts to PyPI
• make release – Chains clean, build, and publish for a full release cycle

The relevant Makefile definitions are:

build: ## Build the package

	@echo "🔨 Building package..."
	python3 -m build

publish: ## Publish to PyPI using Hatch

	@echo "📤 Publishing to PyPI..."
	hatch publish

release: clean build publish ## Full release cycle: clean, build, publish

clean: ## Clean build artifacts

	@echo "🧹 Cleaning build artifacts..."
	rm -rf dist/ build/ *.egg-info/

Publishing to PyPI

To publish a release, ensure you have built the package first and have PyPI credentials configured in ~/.pypirc. The make publish target wraps the Hatch publishing command:

make publish

For a complete release workflow that includes cleaning old artifacts, building fresh ones, and publishing, use:

make release

This executes the full pipeline: clean → build → publish.

Documentation Build

OpenMed uses MkDocs for documentation. The Makefile includes helpers for building and serving documentation locally:

• make docs-serve – Runs uv run mkdocs serve -a 127.0.0.1:8008 for live preview
• make docs-build – Runs uv run mkdocs build --strict to generate static files

These commands rely on the docs extra defined in pyproject.toml, which includes mkdocs and mkdocs-material.

Key Files in the Build Process

Understanding these files helps when modifying the build process for OpenMed:

• pyproject.toml – Declares the hatchling.build backend, dependencies, and version path
• openmed/__about__.py – Stores the current version string read by Hatch during builds
• Makefile – Provides the build, publish, release, and clean automation targets
• scripts/release/release.py – Helper script for version bumping invoked by Makefile targets

Summary

• Build backend: OpenMed uses hatchling as specified in pyproject.toml with the hatchling.build backend
• Build command: Run make build or python3 -m build to generate wheels and source distributions in dist/
• Version location: The version is defined in openmed/__about__.py and read dynamically by Hatch
• Publishing: Use make publish (which calls hatch publish) or make release for the full cycle
• Documentation: Build docs with make docs-build or preview with make docs-serve

Frequently Asked Questions

What build backend does OpenMed use?

OpenMed uses Hatchling as its build backend. The configuration in pyproject.toml specifies build-backend = "hatchling.build" and uses Hatch's versioning system to read from openmed/__about__.py.

How do I build OpenMed from source without Make?

If you prefer not to use the Makefile, activate your virtual environment and run python3 -m build directly. This requires the build package to be installed (pip install build). The command creates both the wheel and source distribution in the dist/ directory.

Where does OpenMed store its version number?

The package version is stored in openmed/__about__.py. Hatch reads this file dynamically during the build process according to the [tool.hatch.version] configuration in pyproject.toml, eliminating the need to hardcode versions in multiple locations.

How do I publish a new release to PyPI?

Run make release from the repository root. This executes the full pipeline: cleaning old artifacts, building fresh distributions with python3 -m build, and publishing to PyPI via hatch publish. Ensure you have PyPI credentials configured in ~/.pypirc or set as environment variables.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}