Metadata-Version: 2.1
Name: thumbhash-python
Version: 1.0.0
Summary: A Python implementation of the Thumbhash image placeholder generation algorithm.
Project-URL: Documentation, https://github.com/Astropilot/thumbhash-python#readme
Project-URL: Issues, https://github.com/Astropilot/thumbhash-python/issues
Project-URL: Source, https://github.com/Astropilot/thumbhash-python
Author-email: Yohann MARTIN <contact@codexus.fr>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.7
Requires-Dist: pillow<10.0.0,>=8.0.0
Requires-Dist: typer[all]==0.7.0
Provides-Extra: dev
Requires-Dist: black==23.1.0; extra == 'dev'
Requires-Dist: devtools[pygments]==0.10.0; extra == 'dev'
Requires-Dist: isort<6.0.0,>=5.0.6; extra == 'dev'
Requires-Dist: mypy==1.1.1; extra == 'dev'
Requires-Dist: ruff==0.0.257; extra == 'dev'
Requires-Dist: types-pillow>=9.0.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: coverage[toml]<8.0,>=6.5.0; extra == 'test'
Requires-Dist: pytest<8.0.0,>=7.1.3; extra == 'test'
Description-Content-Type: text/markdown

<h1 align="center">
    <br>
    ThumbHash for Python
</h1>
<p align="center">
  <p align="center">Open-source, end-to-end encrypted tool to manage secrets and configs across your team, devices, and infrastructure.</p>
</p>


<p align="center">
<a href="https://github.com/Astropilot/thumbhash-python/actions?query=workflow%3ATest+event%3Apush+branch%3Amain" target="_blank">
    <img src="https://github.com/Astropilot/thumbhash-python/workflows/Test/badge.svg?event=push&branch=main" alt="Test">
</a>
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/Astropilot/thumbhash-python" target="_blank">
    <img src="https://coverage-badge.samuelcolvin.workers.dev/Astropilot/thumbhash-python.svg" alt="Coverage">
</a>
<a href="https://pypi.org/project/thumbhash-python" target="_blank">
    <img src="https://img.shields.io/pypi/v/thumbhash-python?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/thumbhash-python" target="_blank">
    <img src="https://img.shields.io/pypi/pyversions/thumbhash-python.svg?color=%2334D058" alt="Supported Python versions">
</a>
<a href="https://github.com/Astropilot/thumbhash-python/blob/master/LICENSE">
    <img src="https://img.shields.io/github/license/Astropilot/thumbhash-python" alt="MIT License">
</a>
</p>

# Introduction

The thumbhash library implements the [Thumbhash](https://evanw.github.io/thumbhash/) image placeholder generation algorithm invented by [Evan Wallace](https://madebyevan.com/) in Python.

A full explanation and interactive example of the algorithm can be found at https://github.com/evanw/thumbhash

# Installation

You need Python 3.7+.

```console
$ pip install thumbhash-python
```

# Usage

Create thumbhash from image file:
```py
from thumbhash import image_to_thumbhash

with open('image.jpg', 'rb') as image_file:
    hash = image_to_thumbhash(image_file)
```

You can also pass file name as parameter to the function:
```py
from thumbhash import image_to_thumbhash

hash = image_to_thumbhash('image.jpg')
```
These functions use the Pillow library to read the image.

If you want to directly convert a rgba array to a thumbhash, you can use the low-level function:
```py
from thumbhash.encode import rgba_to_thumbhash

rgba_to_thumbhash(w: int, h: int, rgba: Sequence[int]) -> bytes
```

To decode a thumbhash into an image:
```py
from thumbhash import thumbhash_to_image

image = thumbhash_to_image("[THUMBHASH]", base_size=128)

image.show()

image.save('path/to/file.png')
```

Alternatively you can use the following function to deal directly with the pixels array (without relying on Pillow):
```py
from thumbhash.decode import thumbhash_to_rgba

def thumbhash_to_rgba(
    hash: bytes, base_size: int = 32, saturation_boost: float = 1.25
) -> Tuple[int, int, List[int]]
```

## CLI

You can also use the CLI mode to encode or decode directly via your shell.

**Usage**:

```console
$ thumbhash [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
* `--help`: Show this message and exit.

**Commands**:

* `decode`: Save thumbnail image from thumbhash
* `encode`: Get thumbhash from image

### `thumbhash decode`

Save thumbnail image from thumbhash

**Usage**:

```console
$ thumbhash decode [OPTIONS] IMAGE_PATH HASH
```

**Arguments**:

* `IMAGE_PATH`: The path where the image created from the hash will be saved  [required]
* `HASH`: The base64-encoded thumbhash  [required]

**Options**:

* `-s, --size INTEGER RANGE`: The base size of the output image  [default: 32; x>=1]
* `--saturation FLOAT`: The saturation boost factor to use  [default: 1.25]
* `--help`: Show this message and exit.

### `thumbhash encode`

Get thumbhash from image

**Usage**:

```console
$ thumbhash encode [OPTIONS] IMAGE_PATH
```

**Arguments**:

* `IMAGE_PATH`: The path of the image to convert  [required]

**Options**:

* `--help`: Show this message and exit.


## Contributing

See [Contributing documentation](./.github/CONTRIBUTING.md)

## License

`thumbhash-python` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
