thumbleweed 0.1.1__tar.gz

thumbleweed-0.1.1/.gitignore

@@ -0,0 +1,32 @@
+# Rust
+/target/
+**/*.rs.bk
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+.mypy_cache/
+.pytest_cache/
+.zed/
+
+# Maturin
+*.whl

thumbleweed-0.1.1/.nextest.toml

@@ -0,0 +1,8 @@
+# cargo-nextest configuration
+# Note: this crate is a PyO3 extension module; Python-level tests are run
+# via pytest (see [tool.pytest.ini_options] in pyproject.toml).
+
+[profile.default]
+retries = 3
+fail-fast = false
+status-level = "all"

thumbleweed-0.1.1/Cargo.lock

@@ -0,0 +1,154 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91fd8e38a3b50ed1167fb981cd6fd60147e091784c427b8f7183a7ee32c31c12"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e368e7ddfdeb98c9bca7f8383be1648fd84ab466bf2bc015e94008db6d35611e"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f29e10af80b1f7ccaf7f69eace800a03ecd13e883acfacc1e5d0988605f651e"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df6e520eff47c45997d2fc7dd8214b25dd1310918bbb2642156ef66a67f29813"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4cdc218d835738f81c2338f822078af45b4afdf8b2e33cbb5916f108b813acb"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "thiserror"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "thumbleweed"
+version = "0.1.1"
+dependencies = [
+ "pyo3",
+ "thiserror",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"

thumbleweed-0.1.1/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "thumbleweed"
+version = "0.1.1"
+edition = "2024"
+description = "Fast ThumbHash encode/decode – Python bindings via PyO3"
+license = "MIT"
+readme = "README.md"
+
+[lib]
+name = "_core"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "^0.28.3", features = ["extension-module"] }
+thiserror = "2"
+
+[profile.release]
+lto           = true
+codegen-units = 1
+opt-level     = 3
+strip         = true
+
+# ── Free-threaded Python 3.13+ (no GIL) ────────────────────────────────────
+# pyo3 0.23+ enables this automatically when building against a free-threaded
+# interpreter; no extra feature flag needed.

thumbleweed-0.1.1/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 thumbhash-py contributors
+
+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.

thumbleweed-0.1.1/PKG-INFO

@@ -0,0 +1,329 @@
+Metadata-Version: 2.4
+Name: thumbleweed
+Version: 0.1.1
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Dist: pillow>12 ; extra == 'dev'
+Requires-Dist: pytest>=9 ; extra == 'dev'
+Requires-Dist: maturin>=1.10 ; extra == 'dev'
+Requires-Dist: pillow>11 ; extra == 'pillow'
+Provides-Extra: dev
+Provides-Extra: pillow
+License-File: LICENCE
+Summary: Fast ThumbHash encode/decode – Rust-powered Python bindings
+Keywords: thumbhash,image,placeholder,blurhash
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Bug Tracker, https://github.com/New-Elysium/thumbleweed/issues
+Project-URL: Repository, https://github.com/New-Elysium/thumbleweed
+
+# thumbhash
+
+**Fast ThumbHash encode/decode for Python — Rust-powered, zero mandatory dependencies.**
+
+A modern, OSS drop-in replacement for [`fast-thumbhash`](https://pypi.org/project/fast-thumbhash/),
+built with [maturin](https://www.maturin.rs/) and [PyO3](https://pyo3.rs/).
+
+- ✅ Python 3.10 – 3.14 (including free-threaded `3.13t` / `3.14t`)
+- ✅ Pillow > 11 integration (optional)
+- ✅ Typed (`py.typed` + `.pyi` stubs)
+- ✅ Pure-Rust core — no C extensions, no NumPy required
+
+---
+
+## Installation
+
+```bash
+pip install thumbleweed
+# with Pillow helpers:
+pip install "thumbleweed[pillow]"
+```
+
+---
+
+## Quick-start
+
+### Raw RGBA bytes
+
+```python
+import thumbleweed as tw
+
+# Encode -------------------------------------------------------------------
+# rgba_bytes must be a bytes/bytearray of length w*h*4 (R G B A, non-premult.)
+hash_bytes: bytes = tw.encode(w, h, rgba_bytes)
+
+# Decode -------------------------------------------------------------------
+w_out, h_out, rgba_out = tw.decode(hash_bytes)
+
+# Helpers ------------------------------------------------------------------
+r, g, b, a = tw.average_rgba(hash_bytes)   # dominant colour [0, 1]
+ratio = tw.approximate_aspect_ratio(hash_bytes)  # width / height
+```
+
+### Pillow images
+
+```python
+from PIL import Image
+import thumbleweed as tw
+
+img = Image.open("photo.jpg")
+
+hash_bytes = tw.encode_image(img)         # any mode, any size
+placeholder: Image.Image = tw.decode_image(hash_bytes)   # RGBA, ≈32 px
+placeholder.save("placeholder.png")
+```
+
+`encode_image` automatically converts the image to RGBA and shrinks it so
+the longest side is ≤ 100 px (the algorithm's hard limit).
+
+---
+
+## API reference
+
+| Function | Description |
+|---|---|
+| `encode(w, h, rgba) → bytes` | Encode raw RGBA bytes → ThumbHash |
+| `decode(hash) → (w, h, rgba)` | Decode ThumbHash → raw RGBA bytes |
+| `average_rgba(hash) → (r,g,b,a)` | Dominant colour in [0, 1] |
+| `approximate_aspect_ratio(hash) → float` | Width / height of the original image |
+| `encode_image(img) → bytes` | Encode a Pillow `Image` *(requires Pillow)* |
+| `decode_image(hash) → Image` | Decode a ThumbHash to a Pillow `Image` *(requires Pillow)* |
+
+---
+
+## Building from source
+
+### Prerequisites
+
+| Tool | Version | Install |
+|---|---|---|
+| Rust (stable) | ≥ 1.75 (tested with **1.95.0**) | `curl https://sh.rustup.rs -sSf \| sh` |
+| Python | 3.9 – **3.14** | system / pyenv |
+| maturin | ≥ 1.7, < 2 | `pip install "maturin>=1.7,<2"` |
+
+> **Ubuntu 26.04 / Python 3.14 note** — Ubuntu 26.04 ships Python 3.14.
+> The steps below work unchanged; maturin detects the interpreter automatically.
+
+### 1 — Clone and enter the project
+
+```bash
+git clone https://github.com/New-Elysium/thumbleweed.git
+cd thumbleweed
+```
+
+### 2 — Set up a virtual environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install "maturin>=1.10,<2" "Pillow>12" pytest
+```
+
+### 3 — Development build (editable)
+
+Compiles the Rust extension and installs the package in editable mode so
+that changes to the Python files in `python/thumbhash/` take effect
+immediately without a rebuild.
+
+```bash
+maturin develop --release
+```
+
+### 4 — Run the tests
+
+```bash
+pytest -v
+```
+
+### 5 — Build release wheels
+
+#### Local wheel (current platform only)
+
+```bash
+maturin build --release
+# wheel lands in  target/wheels/thumbhash-*.whl
+pip install target/wheels/thumbhash-*.whl
+```
+
+#### Portable `manylinux` wheels (for PyPI)
+
+Use the official maturin Docker image to build wheels that are compatible
+with virtually every Linux distribution:
+
+```bash
+docker run --rm \
+  -v "$(pwd)":/io \
+  -w /io \
+  ghcr.io/pyo3/maturin:latest \
+  build --release --out dist
+```
+
+Wheels for each CPython version land in `dist/`.
+
+#### macOS (universal2)
+
+```bash
+rustup target add aarch64-apple-darwin x86_64-apple-darwin
+maturin build --release --target universal2-apple-darwin
+```
+
+#### Windows
+
+```powershell
+maturin build --release
+```
+
+#### Free-threaded Python 3.13t / 3.14t
+
+maturin ≥ 1.7 detects the free-threaded interpreter automatically.
+Just activate the `python3.14t` (or `python3.13t`) virtual environment and
+run `maturin develop` or `maturin build` as normal.
+
+---
+
+## Publishing to PyPI
+
+### One-time setup
+
+```bash
+pip install twine
+# Create a PyPI account and generate an API token at https://pypi.org/manage/account/token/
+```
+
+Store the token in `~/.pypirc`:
+
+```ini
+[pypi]
+  username = __token__
+  password = pypi-<your-token-here>
+```
+
+Or export it as an environment variable:
+
+```bash
+export MATURIN_PYPI_TOKEN=pypi-<your-token-here>
+```
+
+### Build all wheels with `maturin publish` (recommended)
+
+`maturin publish` builds *and* uploads in one step.  It uses
+[`cibuildwheel`](https://cibuildwheel.pypa.io/) conventions internally when
+run in CI.
+
+```bash
+maturin publish --token pypi-<your-token-here>
+```
+
+### Manual upload with twine
+
+If you built wheels separately (e.g. via the Docker approach above):
+
+```bash
+twine upload dist/*.whl dist/*.tar.gz
+```
+
+### CI / GitHub Actions (recommended for cross-platform wheels)
+
+Create `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+          manylinux: auto   # builds manylinux wheels on Linux
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: dist
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        # Trusted publishing — no API token needed when configured on PyPI
+```
+
+> **Tip**: Enable [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+> on PyPI to avoid managing API tokens in GitHub secrets.
+
+---
+
+## Project layout
+
+```
+thumbhash-py/
+├── Cargo.toml          # Rust crate manifest
+├── pyproject.toml      # maturin + PEP 621 metadata
+├── README.md
+├── src/
+│   └── lib.rs          # Rust implementation + PyO3 bindings
+├── python/
+│   └── thumbhash/
+│       ├── __init__.py # Public Python API + Pillow helpers
+│       ├── _core.pyi   # Type stubs for the compiled extension
+│       └── py.typed    # PEP 561 marker
+└── tests/
+    └── test_thumbhash.py
+```
+
+---
+
+## Algorithm
+
+ThumbHash is a compact image placeholder algorithm by
+[Evan Wallace](https://evanw.github.io/thumbhash/).  It encodes images using
+a discrete cosine transform (DCT) into a small byte string (typically 5–32
+bytes) that decodes to a smooth, colourful placeholder.
+
+Compared to BlurHash it supports a more accurate aspect ratio, alpha
+transparency, and better colour fidelity.
+
+---
+
+## Licence
+
+MIT — see [LICENCE](LICENCE).
+