dorothea 1.9.0__tar.gz

dorothea-1.9.0/.gitattributes

@@ -0,0 +1,7 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+*.sh text
+
+# Force unix line endings
+*.sh eol=lf

dorothea-1.9.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (ruff, format, ty)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - run: uvx prek run --all-files --show-diff-on-failure
+
+  test-full:
+    # Everything installed, including expose.sh's own dependencies, so the parity tests
+    # run. Arch ships ImageMagick 7 and ffmpeg with x264 (like the dev machine); Ubuntu's
+    # ImageMagick 6 picks different JPEG chroma subsampling than the one we match.
+    name: Tests + parity (ImageMagick, ffmpeg, perl)
+    runs-on: ubuntu-latest
+    container: archlinux:latest
+    steps:
+      - name: Install system packages
+        run: >-
+          pacman -Syu --noconfirm --needed
+          git make bash which file rsync perl imagemagick ffmpeg uv
+      - uses: actions/checkout@v7
+      - run: uv sync
+      - run: make test-cov
+
+  test-minimal:
+    # No ffmpeg or ImageMagick on the system: proves `uv tool install` needs nothing else
+    # (the bundled imageio-ffmpeg binary and Pillow are used). Parity tests skip here.
+    name: Tests without system packages
+    runs-on: ubuntu-latest
+    container: ghcr.io/astral-sh/uv:python3.14-bookworm-slim
+    steps:
+      - uses: actions/checkout@v7
+      - name: Check the environment really is minimal
+        run: |
+          ! command -v ffmpeg
+          ! command -v convert
+          ! command -v magick
+      - run: uv sync
+      - run: uv run pytest -m "not slow" --no-cov
+
+  package:
+    # Build the wheel and sdist and run them the way users will (`uvx dorothea`,
+    # `pipx run dorothea`), outside the source tree, with no ffmpeg or ImageMagick installed.
+    # Catches what the test suite can't: themes missing from the package, broken entry
+    # points, dependencies missing from pyproject.toml.
+    name: Package (uvx, pipx)
+    runs-on: ubuntu-latest
+    container: ghcr.io/astral-sh/uv:python3.14-bookworm-slim
+    steps:
+      - uses: actions/checkout@v7
+      - run: uv build
+      - name: Entry points
+        run: |
+          wheel=$(ls dist/*.whl)
+          uvx --isolated --from "$wheel" dorothea --version
+          uvx --isolated --from "$wheel" expose --version
+          uvx pipx run --no-cache --spec "$wheel" dorothea --version
+      - name: Build a gallery from the wheel and from the sdist
+        run: |
+          for dist in dist/*.whl dist/*.tar.gz; do
+            gallery=$(mktemp -d)
+            cp -r tests/data/test_run/. "$gallery"
+            rm -rf "$gallery/_site"
+            (cd "$gallery" && uvx --isolated --from "$GITHUB_WORKSPACE/$dist" dorothea -d)
+            test -s "$gallery/_site/index.html"
+            test -s "$gallery/_site/global.css"
+            test -s "$gallery/_site/nature/mountains/peak/1024.jpg"
+            echo "OK: $dist"
+          done

dorothea-1.9.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+# Publishes to PyPI when a GitHub release is published (tag like v1.9.0).
+# Uses PyPI trusted publishing: no API token is stored in the repository. One-time setup on
+# pypi.org: add a (pending) trusted publisher for project "dorothea" with owner
+# "marcolussetti", repository "dorothea", workflow "release.yml", environment "pypi".
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Check the tag matches the package version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(uv version --short)
+          if [ "$TAG" != "v$version" ]; then
+            echo "Release tag $TAG does not match pyproject version v$version" >&2
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v7
+      - run: uv publish --trusted-publishing always

dorothea-1.9.0/.gitignore

@@ -0,0 +1,55 @@
+# Windows image file caches
+Thumbs.db
+ehthumbs.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# =========================
+# Operating System Files
+# =========================
+
+# OSX
+# =========================
+
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear on external disk
+.Spotlight-V100
+.Trashes
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+_site/
+plans/
+
+# Personal gallery (local test data, not part of the project)
+knowneuropean-photos/
+.coverage
+htmlcov/

dorothea-1.9.0/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+# Pre-commit configuration for dorothea
+# Excludes legacy theme files and expose.sh
+
+# Hooks that parse Python (debug-statements) must run on the project's minimum version (3.14)
+default_language_version:
+  python: python3.14
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^(theme1/|theme2/|Markdown_1.0.1/|expose.sh)
+      - id: end-of-file-fixer
+        exclude: ^(theme1/|theme2/|Markdown_1.0.1/|expose.sh)
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=2000']
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9  # keep in sync with pyproject.toml dev group
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+        exclude: ^(theme1/|theme2/|Markdown_1.0.1/|expose.sh)
+      - id: ruff-format
+        exclude: ^(theme1/|theme2/|Markdown_1.0.1/|expose.sh)
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: uv run ty check src
+        language: system
+        types: [python]
+        pass_filenames: false

dorothea-1.9.0/CONFIG.md

@@ -0,0 +1,124 @@
+# Dorothea configuration
+
+Settings are read, in increasing order of precedence, from:
+
+1. built-in defaults (below, the same as expose.sh's)
+2. `_config.json` in the gallery folder, or `--config FILE` (`.json` or `.sh`). Without a
+   `_config.json`, expose.sh's `_config.sh` is read instead (see [MIGRATION.md](MIGRATION.md))
+3. `--set KEY=VALUE` and `-j N` on the command line
+4. draft mode (`-d`), which forces `resolution=[1024]`, `bitrate=[4]`, `video_formats=["h264"]`
+   and `download_button=false`
+
+```json
+{
+  "site_title": "Iceland 2022",
+  "theme_dir": "theme2",
+  "resolution": [2560, 1920, 1280, 640],
+  "jpeg_quality": 88
+}
+```
+
+Invalid values stop the build with a message naming each problem (exit code 2); unknown keys
+only print a warning, since they're usually typos.
+
+Changing a setting that affects image or video bytes (resolution, quality, bitrates, codec
+speed, per-post options...) re-encodes just the affected files on the next run. There's no need
+to delete `_site`.
+
+## Site and theme
+
+| Key | Default | Description |
+|---|---|---|
+| `site_title` | `"My Awesome Photos"` | Site name shown in every page. |
+| `theme_dir` | `"theme1"` | Theme: a bundled one (`theme1`, `theme2`), a folder of that name in the gallery, or an absolute path. |
+| `text_toggle` | `true` | Show a button to hide/show the text. |
+| `social_button` | `true` | Show the social sharing button. |
+| `disqus_shortname` | `""` | Disqus forum name for comments; empty disables them. |
+
+## Images
+
+| Key | Default | Description |
+|---|---|---|
+| `resolution` | `[3840, 2560, 1920, 1280, 1024, 640]` | Widths to generate (heights follow the source aspect ratio). Only sizes up to the source width are made, plus the smallest one always. |
+| `jpeg_quality` | `92` | JPEG quality (1–100) for generated images. |
+| `autorotate` | `true` | Apply EXIF orientation. |
+
+## Colours
+
+| Key | Default | Description |
+|---|---|---|
+| `extract_colors` | `true` | Extract a 7-colour palette from each photo/video for the theme (`color1`…`color7`, background, text). |
+| `default_palette` | `["#000000", "#222222", "#444444", "#666666", "#999999", "#cccccc", "#ffffff"]` | Palette (background to foreground) used when `extract_colors` is false. |
+| `backgroundcolor` | `"#000000"` | Slide background, visible before the image loads. |
+| `textcolor` | `"#ffffff"` | Default text colour. |
+| `override_textcolor` | `true` | Use `textcolor` for body text instead of the palette's last colour. |
+
+## Video
+
+Video needs ffmpeg: a system `ffmpeg` on `PATH` is used if present, otherwise the one bundled
+with Dorothea (imageio-ffmpeg).
+
+| Key | Default | Description |
+|---|---|---|
+| `video_formats` | `["h264", "vp8"]` | Formats to encode, in order of preference: `h264`, `h265`, `vp9`, `vp8`, `ogv`. |
+| `bitrate` | `[40, 24, 12, 7, 4, 2]` | Target bitrate in Mbit/s for each entry in `resolution` (the last value repeats if the list is shorter). |
+| `bitrate_maxratio` | `2` | Max bitrate as a multiple of the target (VBR). Must be ≥ 1; 1 means constant bitrate. |
+| `disable_audio` | `true` | Strip audio (otherwise it's copied as-is). |
+| `h264_encodespeed` | `"veryslow"` | x264/x265 preset: `ultrafast` … `veryslow`. Slower compresses better. |
+| `vp9_encodespeed` | `1` | VP9 speed, 0 (best, very slow) to 4 (fastest). |
+| `ffmpeg_threads` | `0` | ffmpeg `-threads` (0 = auto). Lower it to throttle CPU use. |
+| `sequence_keyword` | `"imagesequence"` | A folder whose name contains this is compiled into a video from its images. |
+| `sequence_framerate` | `24` | Frame rate of compiled image sequences. |
+
+## Downloads
+
+| Key | Default | Description |
+|---|---|---|
+| `download_button` | `false` | Offer each original in a zip with a readme. |
+| `download_readme` | `"All rights reserved"` | Text of the `readme.txt` in each zip. |
+
+## Dorothea-only
+
+| Key | Default | Description |
+|---|---|---|
+| `jobs` | `0` | Parallel workers for reading and resizing images (0 = one per CPU). Same as `-j N`. Videos always encode one at a time, since ffmpeg already uses every core. |
+
+## Command line
+
+| Flag | Description |
+|---|---|
+| `-d`, `--draft` | Draft mode: one 1024px size, fast h264 only. |
+| `-n`, `--dry-run` | List what would be built (and why) without writing anything. |
+| `-c FILE`, `--config FILE` | Use this config file (`.json` or expose.sh `.sh`). |
+| `-s KEY=VALUE`, `--set KEY=VALUE` | Override a setting; VALUE is JSON if it parses (`--set 'resolution=[1920,640]'`), else a string. Repeatable. |
+| `-j N`, `--jobs N` | Parallel workers (see `jobs`). |
+| `--convert-config` | Write `_config.json` from `_config.sh` and exit. |
+| `--version` | Print the version. |
+
+## Per-post metadata
+
+A text file next to a photo or video with the same name (`01 Glacier.txt` or `.md`) holds its
+caption. Lines before a `---` line are `key: value` metadata; the rest is Markdown. A
+`metadata.txt` in a gallery folder applies to every post in it, and a post's own metadata wins.
+
+```
+image-options: -modulate 100,120
+top: 30
+left: 5
+---
+Caption in *Markdown*.
+```
+
+| Key | Description |
+|---|---|
+| `image-options` | Extra ImageMagick `convert` arguments for this photo (needs ImageMagick installed; otherwise ignored with a warning). Not applied to video thumbnails. |
+| `video-options` | Extra ffmpeg arguments, e.g. `-ss 10 -t 5` to cut a clip. |
+| `video-filters` | ffmpeg filters appended after scaling, e.g. `hflip`. |
+| anything else | Available to the theme as `{{key}}`. theme1 uses `top`, `left`, `width`, `height` (percent), `polygon` and `textcolor`; theme2 uses `width` and `class`. `color1`…`color7` come from the extracted palette. |
+
+## Build cache
+
+Dorothea keeps `.dorothea-cache.json` in the gallery folder. It holds extracted palettes, so
+unchanged photos aren't re-analysed, and a fingerprint for every generated file, so changed
+sources, settings or metadata rebuild exactly what they affect. It's safe to delete: the next
+run re-analyses the photos and keeps any existing output that's newer than its source.

dorothea-1.9.0/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jack Qiao
+
+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.

dorothea-1.9.0/MIGRATION.md

@@ -0,0 +1,86 @@
+# Migrating from expose.sh to Dorothea
+
+Dorothea is a Python port of [expose.sh](https://github.com/Jack000/Expose). For the same
+photos and settings it produces the same site: its test suite builds galleries with both and
+checks that the file lists match, HTML/CSS/JS are byte-identical, and every image and video has
+the same file size. This page covers what you need to change, and the places where Dorothea
+deliberately behaves differently.
+
+## Install
+
+```sh
+uvx dorothea                 # run without installing (or: pipx run dorothea)
+uv tool install dorothea     # install the command (or: pipx install dorothea)
+```
+
+No system packages are required: Pillow resizes images and an ffmpeg binary is bundled.
+Optional:
+
+- a system **ffmpeg** on `PATH` is preferred over the bundled one
+- **ImageMagick** is used for colour extraction (identical palettes to expose.sh) and for
+  per-post `image-options`
+
+Run it the same way as before, inside the gallery folder: `dorothea` or `dorothea -d`. The
+command is also installed as `expose`, so `expose -d` keeps working.
+
+## Configuration
+
+Your `_config.sh` keeps working: without a `_config.json`, Dorothea reads it. It's parsed,
+never executed, so only plain assignments are supported:
+
+```sh
+site_title="Iceland 2022"        # quoted or unquoted values, comments
+resolution=(2560 1920 1280 640)  # arrays on one line
+autorotate=false                 # true/false become booleans, numbers become numbers
+```
+
+Anything else (`$(...)`, `${VAR}`, `export`, `if`) is skipped with a warning naming the line.
+To switch to JSON, the recommended format:
+
+```sh
+dorothea --convert-config        # writes _config.json from _config.sh
+```
+
+If both files exist, `_config.json` wins. Every setting is described in
+[CONFIG.md](CONFIG.md).
+
+> **Note:** expose.sh ignores `resolution`, `bitrate`, `video_formats` and `default_palette` set
+> in `_config.sh` (it reassigns them after reading the file). Dorothea honours them, so a
+> gallery that set them will now actually use those values.
+
+## New in Dorothea
+
+- **Incremental builds that notice changes.** expose.sh skips any output that already exists,
+  so edits needed a manual `rm -rf _site`. Dorothea rebuilds exactly the files whose source,
+  settings or per-post metadata changed. State lives in `.dorothea-cache.json` in the gallery
+  folder, which also caches colour palettes so re-runs are fast. An existing `_site` from
+  expose.sh is adopted as-is, and files newer than their source aren't re-encoded.
+- `-n` / `--dry-run` lists what would be built and why.
+- `--set KEY=VALUE` overrides a setting for one run; `--config FILE` picks a config file.
+- `-j N` resizes images in parallel (default: one worker per CPU).
+- Config values are validated, with a clear error instead of a broken build.
+- A failed or interrupted encode never leaves a truncated file behind; it's retried next run.
+- A corrupt photo is reported and skipped instead of aborting the build.
+
+## Intentional differences
+
+These are places where expose.sh has a bug or a platform quirk that Dorothea doesn't copy:
+
+| expose.sh | Dorothea |
+|---|---|
+| Skips hidden folders only at the top level (`.foo/`). | Skips hidden folders at any depth (`gallery/.thumbs/`). |
+| An image sequence mixing formats (JPEG + PNG) or extensions (`.JPG` + `.jpg`) silently loses frames. | Every frame is used; mixed formats are converted to lossless PNG first. |
+| Download zips for image sequences fail (it `cp`s the folder). | The zip contains the compiled sequence video. |
+| Unknown video extensions are checked with `file -ib`, using a path relative to the wrong directory, so effectively never. | Detected from the file extension's MIME type. |
+| Leaves `ffmpeg2pass-*.log` in the current folder while encoding. | Keeps 2-pass logs in a temporary folder. |
+| A non-text or non-UTF-8 caption file is skipped (`file` check). | Same, with a warning. Captions are always read and written as UTF-8. |
+| Requires ImageMagick and `zip`; video needs ffmpeg and ffprobe. | Needs nothing beyond `pip`/`uv`; ffprobe isn't used. |
+
+Caption Markdown is rendered by python-markdown and normalized to match expose.sh's
+Markdown.pl output. One exception: Markdown.pl obfuscates email autolinks (`<me@x.com>`) with
+random character entities, which by design can't be reproduced. Both versions display the same
+address.
+
+Resized JPEGs are made by Pillow rather than ImageMagick. File sizes match ImageMagick 7 (same
+chroma subsampling rules) but the bytes aren't identical, so image files won't hash the same as
+expose.sh's output; HTML, CSS and JS do.

dorothea-1.9.0/Makefile

@@ -0,0 +1,63 @@
+# Dorothea Makefile
+# Common development tasks using uv
+
+.PHONY: help test test-cov test-fast clean install lint format typecheck
+
+help:
+	@echo "Available commands:"
+	@echo "  make test       - Run all tests"
+	@echo "  make test-cov   - Run tests with coverage report"
+	@echo "  make test-fast  - Run tests without slow/parity tests"
+	@echo "  make clean      - Clean generated files and caches"
+	@echo "  make install    - Install dependencies with uv"
+	@echo "  make lint       - Run all pre-commit hooks (via prek): ruff, format, ty"
+	@echo "  make typecheck  - Type-check src/ with ty"
+	@echo "  make format     - Format code (via prek ruff-format)"
+	@echo "  make install-hooks - Install prek hooks"
+
+# Run all tests
+test:
+	uv run pytest tests/ --no-cov
+
+# Run tests with coverage
+test-cov:
+	@rm -rf .coverage htmlcov
+	uv run pytest tests/ --cov=src/dorothea --cov-report=term --cov-report=html
+
+# Run only fast tests (skip slow parity tests)
+test-fast:
+	uv run pytest tests/ -m "not slow" --no-cov
+
+# Run only parity tests
+test-parity:
+	uv run pytest tests/ -m "slow" --no-cov
+
+# Clean generated files
+clean:
+	@rm -rf .coverage htmlcov .pytest_cache
+	@rm -rf tests/__pycache__ tests/.pytest_cache
+	@find tests -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name "*.pyc" -delete 2>/dev/null || true
+
+# Install dependencies
+install:
+	uv pip install -e ".[dev]"
+
+# Install pre-commit hooks (via prek)
+install-hooks:
+	prek install-hooks
+
+# Run all pre-commit hooks on all files (via prek)
+lint:
+	prek run --all-files
+
+# Type-check with ty
+typecheck:
+	uv run ty check src
+
+# Format code only (via prek ruff-format hook)
+format:
+	prek run ruff-format --all-files
+
+# Run full CI checks locally
+ci: clean lint test-cov