python 37 lines · 7 steps

Building a typed CLI with Click

How Click's decorators declare, validate, and parse command-line arguments into typed Python values.

Explained by highlit

Click Intermediate cli decorators validation type-coercion dataclass

1import click
2 
3 
4@click.command()
5@click.argument("source", type=click.Path(exists=True, dir_okay=False, path_type=Path))
6@click.option("--output", "-o", type=click.Path(path_type=Path), default=Path("out.parquet"), show_default=True)
7@click.option("--workers", "-w", type=click.IntRange(1, 64), default=4, show_default=True)
8@click.option("--chunk-size", type=click.IntRange(min=1), default=10_000, show_default=True)
9@click.option("--compression", type=click.Choice(["snappy", "gzip", "zstd"]), default="snappy")
10@click.option("--since", type=click.DateTime(formats=["%Y-%m-%d"]), default=None)
11@click.option("--dry-run/--no-dry-run", default=False)
12@click.option("-v", "--verbose", count=True)
13def ingest(source, output, workers, chunk_size, compression, since, dry_run, verbose):
14    config = IngestConfig(
15        source=source,
16        output=output,
17        workers=workers,
18        chunk_size=chunk_size,
19        compression=compression,
20        since=since,
21        dry_run=dry_run,
22        log_level=logging.WARNING - min(verbose, 2) * 10,
23    )
24    logging.basicConfig(level=config.log_level)
25    run_pipeline(config)
26 
27 
28@dataclass(frozen=True, slots=True)
29class IngestConfig:
30    source: Path
31    output: Path
32    workers: int
33    chunk_size: int
34    compression: str
35    since: datetime | None
36    dry_run: bool
37    log_level: int

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Click's type objects validate and coerce arguments before your function ever runs.
2Layering decorators keeps parsing declarative so the function body handles only logic.
3A frozen dataclass gives parsed CLI values a single immutable home to pass downstream.

Related explainers

python

from flask import Blueprint, jsonify, request, abort
 
v1 = Blueprint("users_v1", __name__)
v2 = Blueprint("users_v2", __name__)

Versioning a Flask API with Blueprints

api versioning blueprints rest

Intermediate 7 steps

php

<?php
 
namespace App\Http\Controllers;

Streaming a filtered CSV export in Laravel

streaming csv-export query-builder

Intermediate 9 steps

python

import time
import threading
from enum import Enum
from functools import wraps

Building a circuit breaker in Python

circuit-breaker resilience decorators

Advanced 7 steps

python

from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector
from django.core.cache import cache
from django.db.models import F
from django.http import JsonResponse

Ranked full-text search in Django

full-text-search debouncing caching

Advanced 9 steps

python

import os
from datetime import timedelta

Class-based config in a Flask app factory

configuration app-factory inheritance

Intermediate 7 steps

ruby

class ApacheLogParser
  LINE_PATTERN = /\A(?<ip>\S+)\s\S+\s\S+\s\[(?<time>[^\]]+)\]\s"(?<method>[A-Z]+)\s(?<path>\S+)\s(?<protocol>[^"]+)"\s(?<status>\d{3})\s(?<bytes>\d+|-)/
 
  TIME_FORMAT = "%d/%b/%Y:%H:%M:%S %z"