mkgallery 0.1.0__tar.gz

mkgallery-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  # mkgallery is a CLI app (project.scripts), not imported as a library by
+  # other projects -- versioning-strategy: increase.
+  - package-ecosystem: "pip"
+    directory: "/"
+    versioning-strategy: increase
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

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

@@ -0,0 +1,96 @@
+name: Publish Python 🐍 distribution 📦 to PyPI
+on:
+  push:
+    tags:
+      - "v[0-9]*"
+
+jobs:
+  test:
+    name: Lint and test the code 🧪
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0  # hatch-vcs needs tags to derive the version
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: 'pip'
+      - name: Install exiftool
+        run: sudo apt-get update && sudo apt-get install -y libimage-exiftool-perl
+      - name: Install hatch
+        run: python -m pip install hatch --user
+      - name: Lint
+        run: hatch fmt --check
+      - name: Type check
+        run: hatch run types:check
+      - name: Test
+        run: hatch test
+
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    needs:
+      - test
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: 'pip'
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mkgallery
+    permissions:
+      id-token: write  # mandatory for trusted publishing
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs:
+      - publish-to-pypi
+    steps:
+      - name: Create GitHub Release (stable)
+        uses: softprops/action-gh-release@v2
+        if: |
+          !contains(github.ref_name, 'a') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc')
+        with:
+          generate_release_notes: true
+      - name: Create GitHub Release (pre-release)
+        uses: softprops/action-gh-release@v2
+        if: |
+          contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc')
+        with:
+          prerelease: true
+          generate_release_notes: true

mkgallery-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.superpowers/
+src/mkgallery/__about__.py

mkgallery-0.1.0/LICENSE.txt

@@ -0,0 +1,133 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+> Required Notice: Copyright Janna Hopp (https://github.com/bytehexe)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

mkgallery-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: mkgallery
+Version: 0.1.0
+Summary: Summarise a photo collection as a single gallery page
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE.txt
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: imagehash
+Requires-Dist: jinja2
+Requires-Dist: numpy
+Requires-Dist: pillow>=10
+Requires-Dist: platformdirs
+Requires-Dist: pyexiftool
+Requires-Dist: rawpy
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# mkgallery
+
+Summarise a large photo collection — say, a year — as **one static page**: a title and a
+gallery of the most interesting pictures, picked automatically.
+
+```
+mkgallery ~/Photos/2025 --title "2025"
+```
+
+writes `2025.html` and a `2025_assets/` directory next to it. Nothing in the source
+directory is touched, and no configuration is read from it.
+
+## Requirements
+
+- Python ≥ 3.10
+- [`exiftool`](https://exiftool.org/) on `PATH`
+- Formats: JPEG, PNG, WebP, TIFF and RAW (CR2, CR3, NEF, ARW, DNG)
+
+## Install
+
+```
+pipx install .        # or: hatch run mkgallery …
+```
+
+## Usage
+
+```
+mkgallery SRC --title TITLE [options]
+```
+
+| Option | Default | |
+|---|---|---|
+| `-t, --title` | required | Page title; also names `TITLE.html` / `TITLE_assets/` |
+| `-n, --count` | 48 | Number of images shown |
+| `-o, --output-dir` | `.` | Where to write the output (must not be inside `SRC`) |
+| `--order` | `chronological` | `chronological`, or `varied` (neighbours are as dissimilar as possible) |
+| `--event-quota / --no-event-quota` | off | Every event (a run of days with photos, gaps over 24 h split events) gets at least one image; the other slots are shared in proportion to the square root of the event size |
+| `--balance` | 1 | 0–1. Down-weights images in crowded regions when clustering: 0 treats every image alike, 1 gives sparse regions the same weight as dense ones |
+| `--cache-dir` | user cache dir | Analysis cache (must not be inside `SRC`) |
+| `--no-cache` | | Do not read or write the cache |
+| `-j, --jobs` | CPU count | Parallel workers |
+
+## How images are chosen
+
+The selection is ported from [mkmapdiary](https://github.com/bytehexe/mkmapdiary)'s front page:
+
+1. Each image is analysed from a small preview (for RAW files the embedded JPEG — nothing
+   is developed at this stage): sharpness, contrast, entropy, perceptual and colour hashes.
+   Results are cached by path, size and modification time.
+2. Near-duplicates (per day), unusually soft images and flat, low-entropy images are dropped.
+3. The rest is clustered by colour and capture time into `--count` groups; the sharpest,
+   best-contrast image of each group is chosen. The picks therefore spread over the whole
+   year and over different looks. With `--event-quota` (off by default) this is done per event,
+   so a few photos from a small trip are not lost among thousands from a long holiday.
+4. Only the chosen images are converted (RAW files are developed here) into a thumbnail and
+   a 1600 px version.
+
+## Credits and licences
+
+mkgallery is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE.txt).
+
+The generated page bundles these libraries (all MIT licensed). Their licence texts and
+copyright notices are shipped in `TITLE_assets/lib/<name>/` and in
+`src/mkgallery/vendor/`:
+
+- [jQuery](https://jquery.com)
+- [Justified Gallery](https://github.com/miromannino/Justified-Gallery) — the row layout
+- [GLightbox](https://github.com/biati-digital/glightbox) — the lightbox
+
+The selection approach and metric code are adapted from mkmapdiary (same author).

mkgallery-0.1.0/README.md

@@ -0,0 +1,70 @@
+# mkgallery
+
+Summarise a large photo collection — say, a year — as **one static page**: a title and a
+gallery of the most interesting pictures, picked automatically.
+
+```
+mkgallery ~/Photos/2025 --title "2025"
+```
+
+writes `2025.html` and a `2025_assets/` directory next to it. Nothing in the source
+directory is touched, and no configuration is read from it.
+
+## Requirements
+
+- Python ≥ 3.10
+- [`exiftool`](https://exiftool.org/) on `PATH`
+- Formats: JPEG, PNG, WebP, TIFF and RAW (CR2, CR3, NEF, ARW, DNG)
+
+## Install
+
+```
+pipx install .        # or: hatch run mkgallery …
+```
+
+## Usage
+
+```
+mkgallery SRC --title TITLE [options]
+```
+
+| Option | Default | |
+|---|---|---|
+| `-t, --title` | required | Page title; also names `TITLE.html` / `TITLE_assets/` |
+| `-n, --count` | 48 | Number of images shown |
+| `-o, --output-dir` | `.` | Where to write the output (must not be inside `SRC`) |
+| `--order` | `chronological` | `chronological`, or `varied` (neighbours are as dissimilar as possible) |
+| `--event-quota / --no-event-quota` | off | Every event (a run of days with photos, gaps over 24 h split events) gets at least one image; the other slots are shared in proportion to the square root of the event size |
+| `--balance` | 1 | 0–1. Down-weights images in crowded regions when clustering: 0 treats every image alike, 1 gives sparse regions the same weight as dense ones |
+| `--cache-dir` | user cache dir | Analysis cache (must not be inside `SRC`) |
+| `--no-cache` | | Do not read or write the cache |
+| `-j, --jobs` | CPU count | Parallel workers |
+
+## How images are chosen
+
+The selection is ported from [mkmapdiary](https://github.com/bytehexe/mkmapdiary)'s front page:
+
+1. Each image is analysed from a small preview (for RAW files the embedded JPEG — nothing
+   is developed at this stage): sharpness, contrast, entropy, perceptual and colour hashes.
+   Results are cached by path, size and modification time.
+2. Near-duplicates (per day), unusually soft images and flat, low-entropy images are dropped.
+3. The rest is clustered by colour and capture time into `--count` groups; the sharpest,
+   best-contrast image of each group is chosen. The picks therefore spread over the whole
+   year and over different looks. With `--event-quota` (off by default) this is done per event,
+   so a few photos from a small trip are not lost among thousands from a long holiday.
+4. Only the chosen images are converted (RAW files are developed here) into a thumbnail and
+   a 1600 px version.
+
+## Credits and licences
+
+mkgallery is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE.txt).
+
+The generated page bundles these libraries (all MIT licensed). Their licence texts and
+copyright notices are shipped in `TITLE_assets/lib/<name>/` and in
+`src/mkgallery/vendor/`:
+
+- [jQuery](https://jquery.com)
+- [Justified Gallery](https://github.com/miromannino/Justified-Gallery) — the row layout
+- [GLightbox](https://github.com/biati-digital/glightbox) — the lightbox
+
+The selection approach and metric code are adapted from mkmapdiary (same author).