Metadata-Version: 2.4
Name: ithmb-codec
Version: 1.9.10
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Multimedia :: Graphics
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Summary: Python bindings for Ithmb-Codec — decode Apple .ithmb thumbnail files
Home-Page: https://github.com/B67687/Ithmb-Codec
Author: B67687
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/B67687/ithmb-codec/issues
Project-URL: Documentation, https://github.com/B67687/ithmb-codec/blob/main/pymod/README.md
Project-URL: Homepage, https://github.com/B67687/ithmb-codec
Project-URL: Repository, https://github.com/B67687/ithmb-codec

# ithmb-core Python Bindings

Python bindings for [ithmb-codec](https://github.com/B67687/ithmb-codec), a pure Rust decoder for Apple `.ithmb` thumbnail cache files.

## Install

```bash
pip install ithmb-codec
```

Trial builds from dev pushes are published to TestPyPI:

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ithmb-codec
```
## Build

```bash
# Install maturin if you don't have it
pip install maturin

# Build and install the package
cd pymod/
maturin develop --release
```

## Usage

```python
import ithmb_core

# Decode a single .ithmb file
with open("photo.ithmb", "rb") as f:
    data = f.read()
result = ithmb_core.decode_ithmb(data)
# result = { "width": 320, "height": 240, "data": <BGRA bytes>, "format": "BGRA", "rotation": 0 }

# Decode a PhotoDB/ArtworkDB container
with open("PhotoDB", "rb") as f:
    data = f.read()
images = ithmb_core.open_ithmb(data)
for img in images:
    print(f"{img['width']}x{img['height']}")

# List all known profiles
profiles = ithmb_core.list_profiles()
for p in profiles:
    print(f"{p['name']}: {p['width']}x{p['height']} ({p['encoding']})")
```

## API

- `decode_ithmb(data, canceled=None)` — Decode a single `.ithmb` file from bytes. Returns a dict with `width`, `height`, `data` (BGRA `bytes`), `format`, `rotation`.
- `open_ithmb(data, canceled=None)` — Decode a PhotoDB/ArtworkDB container or bare `.ithmb`. Returns a list of dicts (same shape as `decode_ithmb`).
- `list_profiles()` — List all 53 built-in decoding profiles (54 raw format IDs, 1 disabled).

## Testing

```bash
cd pymod/
uv run --frozen pytest          # 11 tests
uv run --frozen ruff check .    # E,F,UP,B,SIM,I (line-length 100, py312)
uv run --frozen basedpyright    # recommended mode
```

Local-only for now (not CI-gated) — see TECH_DEBT_AUDIT.md PYM-01.

