Part 1: Getting Started with Python 3.12 - Setup, pyproject.toml, and Language Features

Introduction

I've been writing Python professionally for a while, but it wasn't until I built ansible-inspec — an open-source compliance automation tool — that I really felt the upgrade from older Python habits to what Python 3.12 offers. The project ships a FastAPI server, a CLI, async job execution, Pydantic v2 models, and a Prisma ORM integration, all in a single pyproject.toml-based package. Everything in this series is grounded in that real codebase.

This first part covers getting Python 3.12 running the right way, understanding the project structure, and a tour of 3.12 language features I actually reach for.

---

Why Python 3.12?

When I started ansible-inspec, I had a choice of runtime target. I settled on 3.12 (while keeping ≥ 3.8 compatibility in the metadata for now) because of:

• tomllib in the standard library — useful for reading config without extra deps

• Better error messages — NameError, SyntaxError, and ImportError now tell you exactly what's wrong and why

• typing improvements — override, TypeVar with defaults, @dataclass_transform — all reducing boilerplate in Pydantic models

• Performance — CPython 3.12 is ~5% faster than 3.11 in most benchmarks; not dramatic, but free

• f-string nesting — finally legal in 3.12, useful when building dynamic log lines

---

Installing Python 3.12

macOS

# The cleanest way on macOS is pyenv
brew install pyenv

# Add to your shell (zsh example)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

# Install Python 3.12
pyenv install 3.12.3
pyenv global 3.12.3

# Verify
python --version   # Python 3.12.3

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.12 python3.12-venv python3.12-dev

python3.12 --version

Windows

Download the official installer from python.org/downloads and tick "Add Python to PATH".

---

Project Setup

Virtual Environment

Always isolate dependencies from the system Python:

# Create a venv using 3.12 explicitly
python3.12 -m venv .venv

# Activate
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows PowerShell

# Confirm
python --version   # Python 3.12.x

Modern pyproject.toml

Python packaging has moved from setup.py to pyproject.toml. This is the structure I use in ansible-inspec:

[build-system]
requires = ["setuptools>=65.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "ansible-inspec"
version = "0.2.12"
description = "Compliance testing with Ansible and InSpec integration"
readme = "README.md"
authors = [{ name = "Htunn Thu Thu" }]
license = { text = "GPL-3.0-or-later" }
requires-python = ">=3.8"

classifiers = [
    "Programming Language :: Python :: 3.12",
    "Topic :: System :: Systems Administration",
    "Topic :: Security",
]

keywords = ["ansible", "inspec", "compliance", "automation"]

dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
    "pydantic>=2.0.0",
    "pydantic-settings>=2.0.0",
    "httpx>=0.27.0",
    "pyyaml>=6.0",
    "jinja2>=3.1.0",
]

[project.optional-dependencies]
server = [
    "prisma>=0.15.0",
    "passlib[bcrypt]>=1.7.4",
    "msal>=1.26.0",
    "python-jose[cryptography]>=3.3.0",
    "streamlit>=1.40.0",
]
dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
    "httpx>=0.27.0",
    "ruff>=0.4.0",
    "mypy>=1.10.0",
]

[project.scripts]
ansible-inspec = "ansible_inspec.cli.main:main"

[tool.setuptools.packages.find]
where = ["lib"]

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.mypy]
python_version = "3.12"
strict = true

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]

Key things to notice:

• [project.optional-dependencies] — install with pip install -e ".[server,dev]" for everything, or pip install -e . for CLI-only

• [project.scripts] — the ansible-inspec command maps directly to a Python function

• [tool.ruff] / [tool.mypy] / [tool.pytest.ini_options] — all tooling config lives in one file

Install the project in editable mode:

# CLI only
pip install -e .

# With server extras
pip install -e ".[server]"

# Everything (dev + server)
pip install -e ".[server,dev]"

---

Python 3.12 Language Features I Actually Use

Better Error Messages

# In older Python you'd get: NameError: name 'config' is not defined
# In 3.12:
# NameError: name 'config' is not defined. Did you mean: 'Config'?

class Config:
    debug: bool = False

cfg = Config()
print(config.debug)  # 3.12 hints at the right name

The improved tracebacks in 3.12 point to the exact bracket or call that failed — a genuine daily-quality-of-life improvement.

match Statement (Structural Pattern Matching, from 3.10+)

I use this in the CLI dispatcher for ansible-inspec:

def dispatch_command(command: str, args: dict) -> None:
    match command:
        case "exec":
            run_profile(args["profile"], args["inventory"])
        case "convert":
            convert_profile(args["source"], args["output"])
        case "start-server":
            start_api_server(args.get("host", "0.0.0.0"), args.get("port", 8080))
        case _:
            print(f"Unknown command: {command}")

Much cleaner than a chain of if/elif.

Improved f-strings (3.12)

In Python 3.11 and earlier, you could not reuse the same quote type inside an f-string expression. 3.12 removes that limitation:

# Previously illegal — SyntaxError in <3.12
# Now valid in 3.12
hosts = ["web-01", "web-02", "db-01"]
msg = f"Hosts: {', '.join(h for h in hosts if h.startswith('web'))}"
print(msg)  # Hosts: web-01, web-02

# Also valid now — nested f-strings
label = "compliance"
log = f"Running {f'{label.upper()} check'} on {len(hosts)} hosts"
print(log)  # Running COMPLIANCE check on 3 hosts

Type Alias (type keyword, 3.12)

# Old style (still valid)
from typing import TypeAlias
HostList: TypeAlias = list[str]

# 3.12 — first-class `type` statement
type HostList = list[str]
type ProfileResult = dict[str, bool | str | None]

def get_results(hosts: HostList) -> list[ProfileResult]:
    return [{"host": h, "passed": True} for h in hosts]

TypeVar with Default (3.13-preview, but typing_extensions backport works on 3.12)

Not in 3.12 stdlib yet, but worth knowing. For now, the TypeVar + Generic pattern is standard:

from typing import TypeVar, Generic

T = TypeVar("T")

class JobResult(Generic[T]):
    def __init__(self, data: T, success: bool) -> None:
        self.data = data
        self.success = success

result: JobResult[dict] = JobResult(data={"host": "web-01"}, success=True)

---

Project Structure

The structure I landed on for ansible-inspec — and which I recommend for any medium-sized Python project:

ansible-inspec/
├── lib/
│   └── ansible_inspec/         # src-layout keeps the package isolated
│       ├── __init__.py
│       ├── cli/
│       │   └── main.py
│       ├── core/
│       │   └── executor.py
│       ├── server/
│       │   ├── app.py
│       │   └── routes/
│       └── models/
│           └── job.py
├── tests/
│   ├── unit/
│   └── integration/
├── docs/
├── pyproject.toml
├── Makefile
└── README.md

The lib/ src-layout (as opposed to putting the package at root) means you can't accidentally import the un-installed package during tests — pip install -e . is required, which is the correct behaviour.

The Makefile is a simple task runner:

.PHONY: install dev-install test lint format

install:
	pip install -e .

dev-install:
	pip install -e ".[server,dev]"

test:
	pytest

lint:
	ruff check lib/ tests/
	mypy lib/

format:
	ruff format lib/ tests/

---

__init__.py — The Package Entry Point

This is what lib/ansible_inspec/__init__.py looks like:

"""
ansible-inspec: Compliance testing with Ansible and InSpec integration

Copyright (C) 2026 ansible-inspec project contributors
Licensed under GPL-3.0
"""

__version__ = "0.2.12"
__author__ = "Htunn Thu Thu"
__license__ = "GPL-3.0"

UPSTREAM_PROJECTS: dict[str, dict[str, str]] = {
    "ansible": {
        "url": "https://github.com/ansible/ansible",
        "license": "GPL-3.0",
        "copyright": "Red Hat, Inc.",
    },
    "inspec": {
        "url": "https://github.com/inspec/inspec",
        "license": "Apache-2.0",
        "copyright": "Progress Software Corp.",
    },
}

Notice the type annotation on UPSTREAM_PROJECTS — using dict[str, dict[str, str]] directly (lowercase), which is valid from Python 3.9+. No from typing import Dict needed.

---

Summary

Topic	Takeaway
Installation	Use pyenv on macOS/Linux; official installer on Windows
Virtual env	Always use one; python3.12 -m venv .venv
Packaging	pyproject.toml is the standard — no more setup.py
match	Cleaner than if/elif chains for command dispatch
f-strings	3.12 removes quote nesting restrictions
type keyword	Cleaner type aliases in 3.12
Src-layout	lib/ directory prevents accidental bare imports

---

What's Next

Part 2 covers the data structures, type hints, and Pydantic v2 models I use throughout the ansible-inspec server — including how job templates and results are modelled.