blog-image 0.1.0__tar.gz

blog_image-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Discuter sur Discord
+    url: https://discord.gg/FS2xqJ4QT6
+    about: Le salon #blog-image du serveur F-Overseas Solutions — la réponse y arrive plus vite que dans une issue.
+  - name: Question d'usage (Q&A)
+    url: https://github.com/foverseas/blog-image/discussions/categories/q-a
+    about: Comment choisir ses formats, une police qui ne se charge pas, un titre qui se coupe mal — une réponse marquée ici sert au suivant.

blog_image-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --locked --extra dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # resolve_fonts() falls back to DejaVu when the spec names no family;
+      # the runner image is not guaranteed to carry it.
+      - name: Install the fallback font family
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends fonts-dejavu-core
+
+      - uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --locked --extra dev
+
+      - name: Run the tests
+        run: uv run pytest -q

blog_image-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Publier sur PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # L'authentification auprès de PyPI se fait par ce jeton OIDC,
+      # pas par un secret : il n'y a aucun token à stocker ici.
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      # Un tag qui ne correspond pas à la version du paquet publierait un
+      # numéro inattendu, et PyPI n'accepte jamais deux fois la même version.
+      - name: Vérifier que le tag correspond à la version du paquet
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv version --short)"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::le tag $GITHUB_REF_NAME annonce $tag, pyproject.toml dit $version"
+            exit 1
+          fi
+
+      - name: Construire la distribution
+        run: uv build
+
+      - name: Vérifier les métadonnées
+        run: uvx twine check dist/*
+
+      - uses: pypa/gh-action-pypi-publish@v1.14.3

blog_image-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.DS_Store
+
+# generated cards
+out/
+*.png
+!docs/*.png

blog_image-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Journal des changements
+
+Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/) et le
+versionnage [SemVer](https://semver.org/lang/fr/).
+
+## [0.1.0] - 2026-10-24
+
+Première version.
+
+### Ajouté
+
+- Génération des images de couverture d'un article dans plusieurs rapports
+  d'image à partir d'un fichier YAML, pour ne plus entretenir à la main trois
+  fichiers qui divergent au premier changement de titre.
+- Trois formats par défaut — 16:9 (1600×900) pour Open Graph et l'en-tête du
+  billet, 4:3 (1600×1200) pour l'emplacement Discover, 1:1 (1200×1200) pour les
+  recadrages sociaux. Les ratios `3x2`, `2x1`, `4x5` et `9x16` sont connus, et
+  toute taille s'écrit en pixels (`1240x700`).
+- Clés de description en français ou en anglais (`titre` ou `title`, `fond` ou
+  `background`). Une clé inconnue est une erreur plutôt qu'un silence.
+- Coupe automatique du titre sur la largeur mesurée de la police, avec
+  réduction du corps tant que le compte de lignes ou la largeur dépasse. Une
+  seule description sert les trois formats.
+- Respect des espaces insécables : un `?` ou un `:` français ne part pas seul à
+  la ligne.
+- Motifs `particules` et `grille`, ou `aucun`, dimensionnés sur l'unité
+  typographique et non sur la bande qu'ils occupent.
+- Résolution de police multi-plateforme : une famille, un gabarit de chemin
+  contenant `%s`, ou une paire de fichiers explicite. À défaut, repli sur IBM
+  Plex Mono, DejaVu puis Arial, avec un message qui dit où l'outil a cherché.
+- Interface en ligne de commande (`-o`, `-f`, `-n`, `--dry-run`, `-q`) et API
+  Python (`load_spec`, `resolve_fonts`, `render`).
+
+### Notes
+
+- Le rendu est reproductible : les mêmes descriptions produisent les mêmes
+  fichiers, octet pour octet, de Pillow 11.3 à Pillow 13.0.
+- 29 tests, exécutés en intégration continue sur Python 3.10, 3.12 et 3.14.
+- Le paquet n'est pas publié sur PyPI ; il s'installe depuis ce dépôt avec
+  `uv tool install git+https://github.com/foverseas/blog-image`.
+
+[0.1.0]: https://github.com/foverseas/blog-image/releases/tag/v0.1.0

blog_image-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 F-Overseas Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blog_image-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: blog-image
+Version: 0.1.0
+Summary: Generate article cover images in several aspect ratios from a short YAML file.
+Project-URL: Homepage, https://github.com/foverseas/blog-image
+Project-URL: Repository, https://github.com/foverseas/blog-image
+Project-URL: Issues, https://github.com/foverseas/blog-image/issues
+Project-URL: Discord, https://discord.gg/FS2xqJ4QT6
+Author: F-Overseas Solutions
+License-Expression: MIT
+License-File: LICENSE
+Keywords: blog,cover-image,og-image,pillow,social-card
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# blog-image
+
+[![CI](https://github.com/foverseas/blog-image/actions/workflows/ci.yml/badge.svg)](https://github.com/foverseas/blog-image/actions/workflows/ci.yml)
+
+Génère les images de couverture d'un article dans plusieurs formats, à partir
+d'un fichier YAML de trois lignes.
+
+```yaml
+# image.yml
+titre: "Combien coûte une application mobile"
+accent: "#00ff99"
+fond:   "#1c1c22"
+```
+
+```console
+$ blog-image image.yml
+  -> article-16x9.png   1600x900
+  -> article-4x3.png    1600x1200
+  -> article-1x1.png    1200x1200
+```
+
+![Exemple de carte 16:9](https://raw.githubusercontent.com/foverseas/blog-image/v0.1.0/docs/exemple-16x9.png)
+
+Trois formats parce qu'un article en a besoin de trois : le 16:9 pour Open
+Graph et l'en-tête du billet, le 4:3 pour l'emplacement Discover, le 1:1 pour
+les recadrages sociaux. Les générer séparément, c'est trois fichiers qui
+divergent au premier changement de titre.
+
+## Installation
+
+Avec [uv](https://docs.astral.sh/uv/), sans rien installer de permanent :
+
+```console
+$ uvx --from blog-image blog-image image.yml
+```
+
+Pour l'avoir sous la main partout :
+
+```console
+$ uv tool install blog-image      # ou : pipx install blog-image
+```
+
+Et en développement, depuis les sources :
+
+```console
+$ git clone https://github.com/foverseas/blog-image
+$ cd blog-image
+$ uv sync --extra dev             # crée .venv d'après uv.lock
+$ uv run blog-image examples/image.yml
+```
+
+`pip install blog-image` fonctionne aussi : c'est un paquet ordinaire, uv n'est
+pas une dépendance.
+
+Il faut Python 3.10, Pillow et PyYAML. La police par défaut est JetBrains
+Mono ; si elle n'est pas installée, le programme retombe sur IBM Plex Mono,
+DejaVu puis Arial, et dit où il a cherché s'il ne trouve rien.
+
+## Le fichier de description
+
+Seul `titre` est obligatoire. Les clés s'écrivent en français ou en anglais.
+
+| Clé | Alias | Défaut | Rôle |
+| --- | --- | --- | --- |
+| `titre` | `title` | — | le titre, coupé automatiquement sur la largeur réelle de la police |
+| `sous-titre` | `subtitle` | vide | une ligne sous le titre ; une liste devient autant de lignes |
+| `chapeau` | `eyebrow` | vide | surtitre en capitales espacées, dans la couleur d'accent |
+| `pied` | `footer` | vide | le pied de carte, précédé d'une pastille |
+| `fond` | `background` | `#1c1c22` | fond de la carte |
+| `texte` | `foreground` | `#ffffff` | couleur du texte |
+| `accent` | — | `#00ff99` | pastille, surtitre, point final, motif |
+| `motif` | — | `particules` | `particules`, `grille` ou `aucun` |
+| `graine` | `seed` | `0` | change la disposition du motif sans rien toucher d'autre |
+| `police` | `font` | JetBrains Mono | nom de famille, gabarit de chemin contenant `%s`, ou `{regular:, bold:}` |
+| `formats` | — | `[16x9, 4x3, 1x1]` | ratios connus ou tailles explicites en pixels |
+| `nom` | `name` | `article` | base du nom de fichier |
+| `sortie` | `out` | `.` | dossier de sortie, relatif au fichier YAML |
+| `point` | `dot` | `true` | le point d'accent après le titre |
+| `lignes-max` | `max_lines` | `4` | au-delà, le titre rapetisse au lieu de déborder |
+
+Les couleurs s'écrivent `#rgb`, `#rrggbb` ou `[28, 28, 34]`. Une clé inconnue
+est une erreur : une faute de frappe dans un nom de clé ne se voit sinon qu'une
+fois la carte terminée.
+
+Ratios connus : `16x9`, `4x3`, `3x2`, `2x1`, `1x1`, `4x5`, `9x16`. Pour tout
+autre besoin, écrivez la taille en pixels — `1240x700`.
+
+Voir [`examples/complet.yml`](examples/complet.yml) pour un fichier avec toutes
+les clés.
+
+## En ligne de commande
+
+```console
+$ blog-image image.yml                      # formats du fichier
+$ blog-image image.yml -o public/blog       # ailleurs
+$ blog-image image.yml -f 16x9 -f 1200x628  # autres formats
+$ blog-image image.yml --dry-run            # ce qui serait écrit, sans écrire
+```
+
+`-n/--name` remplace la base du nom de fichier, `-q/--quiet` coupe la sortie.
+Une erreur de description sort en code 2 avec un message en clair, pas une
+trace.
+
+## Comme bibliothèque
+
+```python
+from pathlib import Path
+from blog_image import load_spec, render, resolve_fonts
+
+spec = load_spec(Path("image.yml"))
+fonts = resolve_fonts(spec.font)
+for fmt in spec.formats:
+    render(spec, fonts, fmt, spec.path_for(fmt))
+```
+
+## Trois décisions qui expliquent le reste du code
+
+**Tout est dessiné à 3× puis réduit en Lanczos.** C'est ce qui tient les
+filets d'un pixel et le petit corps, pas l'anticrénelage du rastériseur, qui
+est inégal à ces tailles. La réduction est suivie d'une quantification sur 256
+couleurs : sur un aplat, elle ne se voit pas et divise le poids du fichier par
+deux.
+
+**Le corps du texte est calculé sur une unité, pas sur la largeur.** Une carte
+1:1 n'est pas plus large qu'une 4:3 mais elle a bien plus de place ; dimensionner
+sur la largeur seule la laisse creuse. L'unité corrige la largeur par l'écart
+entre le ratio demandé et le 16:9 :
+
+```python
+unit = width * (1 + max(0.0, height / width - 0.5625) * 0.34)
+```
+
+**Le titre est coupé sur la largeur mesurée de la police**, pas sur un nombre
+de caractères, et le corps diminue tant que le compte de lignes dépasse
+`lignes-max`. C'est ce qui évite d'écrire une coupe différente par format.
+
+Le motif, lui, est dimensionné sur la même unité et non sur la bande qu'il
+occupe : en 16:9 cette bande fait quelques centaines de pixels, en 1:1 cinq
+fois plus, et un décor calé sur la bande disparaît dans le premier cas et
+écrase le second. Seul le nombre de marques dépend de la place disponible.
+
+## Tests
+
+```console
+$ uv run pytest
+```
+
+Le rendu est reproductible : les mêmes descriptions donnent les mêmes fichiers,
+octet pour octet, d'une version de Pillow à l'autre. `uv.lock` est versionné
+pour que ce soit vrai d'une machine à l'autre aussi.
+
+## Journal des changements
+
+Voir [CHANGELOG.md](CHANGELOG.md).
+
+## Contact
+
+Une question d'usage, un titre qui se coupe mal, une idée de format : le
+[Discord](https://discord.gg/FS2xqJ4QT6) est le chemin le plus court. Les questions posées dans les
+[Discussions](https://github.com/foverseas/blog-image/discussions/categories/q-a) y gagnent une réponse qui
+reste trouvable, et les bugs vont dans les [issues](https://github.com/foverseas/blog-image/issues).
+
+## Licence
+
+MIT.

blog_image-0.1.0/README.md

@@ -0,0 +1,165 @@
+# blog-image
+
+[![CI](https://github.com/foverseas/blog-image/actions/workflows/ci.yml/badge.svg)](https://github.com/foverseas/blog-image/actions/workflows/ci.yml)
+
+Génère les images de couverture d'un article dans plusieurs formats, à partir
+d'un fichier YAML de trois lignes.
+
+```yaml
+# image.yml
+titre: "Combien coûte une application mobile"
+accent: "#00ff99"
+fond:   "#1c1c22"
+```
+
+```console
+$ blog-image image.yml
+  -> article-16x9.png   1600x900
+  -> article-4x3.png    1600x1200
+  -> article-1x1.png    1200x1200
+```
+
+![Exemple de carte 16:9](https://raw.githubusercontent.com/foverseas/blog-image/v0.1.0/docs/exemple-16x9.png)
+
+Trois formats parce qu'un article en a besoin de trois : le 16:9 pour Open
+Graph et l'en-tête du billet, le 4:3 pour l'emplacement Discover, le 1:1 pour
+les recadrages sociaux. Les générer séparément, c'est trois fichiers qui
+divergent au premier changement de titre.
+
+## Installation
+
+Avec [uv](https://docs.astral.sh/uv/), sans rien installer de permanent :
+
+```console
+$ uvx --from blog-image blog-image image.yml
+```
+
+Pour l'avoir sous la main partout :
+
+```console
+$ uv tool install blog-image      # ou : pipx install blog-image
+```
+
+Et en développement, depuis les sources :
+
+```console
+$ git clone https://github.com/foverseas/blog-image
+$ cd blog-image
+$ uv sync --extra dev             # crée .venv d'après uv.lock
+$ uv run blog-image examples/image.yml
+```
+
+`pip install blog-image` fonctionne aussi : c'est un paquet ordinaire, uv n'est
+pas une dépendance.
+
+Il faut Python 3.10, Pillow et PyYAML. La police par défaut est JetBrains
+Mono ; si elle n'est pas installée, le programme retombe sur IBM Plex Mono,
+DejaVu puis Arial, et dit où il a cherché s'il ne trouve rien.
+
+## Le fichier de description
+
+Seul `titre` est obligatoire. Les clés s'écrivent en français ou en anglais.
+
+| Clé | Alias | Défaut | Rôle |
+| --- | --- | --- | --- |
+| `titre` | `title` | — | le titre, coupé automatiquement sur la largeur réelle de la police |
+| `sous-titre` | `subtitle` | vide | une ligne sous le titre ; une liste devient autant de lignes |
+| `chapeau` | `eyebrow` | vide | surtitre en capitales espacées, dans la couleur d'accent |
+| `pied` | `footer` | vide | le pied de carte, précédé d'une pastille |
+| `fond` | `background` | `#1c1c22` | fond de la carte |
+| `texte` | `foreground` | `#ffffff` | couleur du texte |
+| `accent` | — | `#00ff99` | pastille, surtitre, point final, motif |
+| `motif` | — | `particules` | `particules`, `grille` ou `aucun` |
+| `graine` | `seed` | `0` | change la disposition du motif sans rien toucher d'autre |
+| `police` | `font` | JetBrains Mono | nom de famille, gabarit de chemin contenant `%s`, ou `{regular:, bold:}` |
+| `formats` | — | `[16x9, 4x3, 1x1]` | ratios connus ou tailles explicites en pixels |
+| `nom` | `name` | `article` | base du nom de fichier |
+| `sortie` | `out` | `.` | dossier de sortie, relatif au fichier YAML |
+| `point` | `dot` | `true` | le point d'accent après le titre |
+| `lignes-max` | `max_lines` | `4` | au-delà, le titre rapetisse au lieu de déborder |
+
+Les couleurs s'écrivent `#rgb`, `#rrggbb` ou `[28, 28, 34]`. Une clé inconnue
+est une erreur : une faute de frappe dans un nom de clé ne se voit sinon qu'une
+fois la carte terminée.
+
+Ratios connus : `16x9`, `4x3`, `3x2`, `2x1`, `1x1`, `4x5`, `9x16`. Pour tout
+autre besoin, écrivez la taille en pixels — `1240x700`.
+
+Voir [`examples/complet.yml`](examples/complet.yml) pour un fichier avec toutes
+les clés.
+
+## En ligne de commande
+
+```console
+$ blog-image image.yml                      # formats du fichier
+$ blog-image image.yml -o public/blog       # ailleurs
+$ blog-image image.yml -f 16x9 -f 1200x628  # autres formats
+$ blog-image image.yml --dry-run            # ce qui serait écrit, sans écrire
+```
+
+`-n/--name` remplace la base du nom de fichier, `-q/--quiet` coupe la sortie.
+Une erreur de description sort en code 2 avec un message en clair, pas une
+trace.
+
+## Comme bibliothèque
+
+```python
+from pathlib import Path
+from blog_image import load_spec, render, resolve_fonts
+
+spec = load_spec(Path("image.yml"))
+fonts = resolve_fonts(spec.font)
+for fmt in spec.formats:
+    render(spec, fonts, fmt, spec.path_for(fmt))
+```
+
+## Trois décisions qui expliquent le reste du code
+
+**Tout est dessiné à 3× puis réduit en Lanczos.** C'est ce qui tient les
+filets d'un pixel et le petit corps, pas l'anticrénelage du rastériseur, qui
+est inégal à ces tailles. La réduction est suivie d'une quantification sur 256
+couleurs : sur un aplat, elle ne se voit pas et divise le poids du fichier par
+deux.
+
+**Le corps du texte est calculé sur une unité, pas sur la largeur.** Une carte
+1:1 n'est pas plus large qu'une 4:3 mais elle a bien plus de place ; dimensionner
+sur la largeur seule la laisse creuse. L'unité corrige la largeur par l'écart
+entre le ratio demandé et le 16:9 :
+
+```python
+unit = width * (1 + max(0.0, height / width - 0.5625) * 0.34)
+```
+
+**Le titre est coupé sur la largeur mesurée de la police**, pas sur un nombre
+de caractères, et le corps diminue tant que le compte de lignes dépasse
+`lignes-max`. C'est ce qui évite d'écrire une coupe différente par format.
+
+Le motif, lui, est dimensionné sur la même unité et non sur la bande qu'il
+occupe : en 16:9 cette bande fait quelques centaines de pixels, en 1:1 cinq
+fois plus, et un décor calé sur la bande disparaît dans le premier cas et
+écrase le second. Seul le nombre de marques dépend de la place disponible.
+
+## Tests
+
+```console
+$ uv run pytest
+```
+
+Le rendu est reproductible : les mêmes descriptions donnent les mêmes fichiers,
+octet pour octet, d'une version de Pillow à l'autre. `uv.lock` est versionné
+pour que ce soit vrai d'une machine à l'autre aussi.
+
+## Journal des changements
+
+Voir [CHANGELOG.md](CHANGELOG.md).
+
+## Contact
+
+Une question d'usage, un titre qui se coupe mal, une idée de format : le
+[Discord](https://discord.gg/FS2xqJ4QT6) est le chemin le plus court. Les questions posées dans les
+[Discussions](https://github.com/foverseas/blog-image/discussions/categories/q-a) y gagnent une réponse qui
+reste trouvable, et les bugs vont dans les [issues](https://github.com/foverseas/blog-image/issues).
+
+## Licence
+
+MIT.

blog_image-0.1.0/blog_image/__init__.py

@@ -0,0 +1,8 @@
+"""Generate article cover images in several aspect ratios from a short YAML file."""
+
+from .config import Format, Spec, load_spec
+from .fonts import FontSet, resolve_fonts
+from .render import render
+
+__version__ = "0.1.0"
+__all__ = ["FontSet", "Format", "Spec", "load_spec", "render", "resolve_fonts"]

blog_image-0.1.0/blog_image/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

blog_image-0.1.0/blog_image/cli.py

@@ -0,0 +1,61 @@
+"""Command line entry point: `blog-image image.yml`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import SpecError, load_spec, parse_format, slugify
+from .fonts import FontError, resolve_fonts
+from .render import render
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="blog-image",
+        description="Generate article cover images in several aspect ratios from a short YAML file.",
+    )
+    parser.add_argument("spec", type=Path, help="YAML file describing the card")
+    parser.add_argument("-o", "--out", type=Path, help="output directory (overrides `sortie`)")
+    parser.add_argument(
+        "-f",
+        "--format",
+        action="append",
+        dest="formats",
+        metavar="RATIO",
+        help="format to render, repeatable; overrides `formats` (e.g. 16x9, 1x1, 1600x900)",
+    )
+    parser.add_argument("-n", "--name", help="base name for the files (overrides `nom`)")
+    parser.add_argument("--dry-run", action="store_true", help="list what would be written and stop")
+    parser.add_argument("-q", "--quiet", action="store_true", help="print nothing on success")
+    parser.add_argument("--version", action="version", version=f"blog-image {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    try:
+        spec = load_spec(args.spec)
+        if args.formats:
+            spec.formats = tuple(parse_format(token) for token in args.formats)
+        if args.out is not None:
+            spec.out = args.out
+        if args.name:
+            spec.name = slugify(args.name)
+        fonts = None if args.dry_run else resolve_fonts(spec.font)
+    except (SpecError, FontError) as error:
+        print(f"blog-image: {error}", file=sys.stderr)
+        return 2
+
+    for fmt in spec.formats:
+        path = spec.path_for(fmt)
+        if not args.dry_run:
+            render(spec, fonts, fmt, path)
+        if not args.quiet:
+            prefix = "would write" if args.dry_run else "->"
+            print(f"  {prefix} {path}   {fmt.width}x{fmt.height}")
+
+    return 0