Metadata-Version: 2.1
Name: thunagen
Version: 0.3.2
Summary: Google Cloud function to generate thumbnail for images in Google Storage.
Home-page: https://github.com/sunshine-tech/thunagen.git
License: Apache-2.0
Keywords: google,cloud,storage,functions,thumbnail
Author: Nguyễn Hồng Quân
Author-email: ng.hong.quan@gmail.com
Maintainer: Nguyễn Hồng Quân
Maintainer-email: ng.hong.quan@gmail.com
Requires-Python: >=3.7,<4.0
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Requires-Dist: Pillow (>=7.0.0,<8.0.0)
Requires-Dist: google-cloud-pubsub (>=1.1.0,<2.0.0)
Requires-Dist: google-cloud-storage (>=1.24.1,<2.0.0)
Requires-Dist: importlib_metadata (>=1.3.0,<2.0.0)
Requires-Dist: lazy_object_proxy (>=1.4.3,<2.0.0)
Requires-Dist: logbook (>=1.5.3,<2.0.0)
Requires-Dist: python-dotenv (>=0.10.3,<0.11.0)
Requires-Dist: single-version (>=1.1,<2.0)
Project-URL: Repository, https://github.com/sunshine-tech/thunagen.git
Description-Content-Type: text/x-rst

========
Thunagen
========


.. image:: https://madewithlove.now.sh/vn?heart=true&colorA=%23ffcd00&colorB=%23da251d
.. image:: https://badge.fury.io/py/thunagen.svg
   :target: https://pypi.org/project/thunagen/


Google Cloud function to generate thumbnail for images in Google Storage.

Convention
----------

The thumbnails are placed in a folder "thumbnails" at the same place as original file.

The thumbnail size is appended to filename, right before the extention part. For example:


.. code-block::

    bucket/
    └── folder/
        ├── photo.jpg
        └── thumbnails/
            ├── photo_128x128.jpg
            └── photo_512x512.jpg
        ├── photo-missing-extension
        └── thumbnails/
            ├── photo-missing-extension_128x128
            └── photo-missing-extension_512x512


The function expects these environment variables to be set:

- ``THUMB_SIZES``: Size of thumbnails to be generated. Example: ``512x512,128x128``.

- ``MONITORED_PATHS``: Folders (and theirs children) where the function will process the uploaded images. Muliple paths are separated by ":", like ``user-docs:user-profiles``. If you want to monitor all over the bucket, set it as ``/``.

The variables can be passed via *.env* file in the working directory.

After finishing generating thumbnail, the function will publish a message to Google Cloud Pub/Sub service, at topic ``thumbnail-generated/{bucket_name}/{image_path}``, with the message being JSON string of thumbnail info (size and path). Example:

- Topic: ``thumbnail-generated/bucket/folder/photo.jpg``

- Message:

    .. code-block:: json

        {
            "128x128": "folder/thumbnails/photo_128x128.jpg",
            "512x512": "folder/thumbnails/photo_512x512.jpg"
        }

This feature allows other application to know when the thumbnails are ready.


Why Thunagen
------------

I'm aware that there is already a `Firebase extension <https://firebase.google.com/products/extensions/storage-resize-images>`_ for the same purpose.
But that extension, when doing its job, need to create a temporary file and in many cases, falling into race condition when the temporary file is deleted by another execution of the same cloud function. Thunagen, on the other hand, generates the file and uploads (back to Storage) on-the-fly (in memory), so it doesn't get into that issue.


Installation
------------

Thunagen is distributed via PyPI. You can install it with ``pip``::

    pip install thunagen


Include to your project
-----------------------

Thunagen is provided without a *main.py* file, for you to incorporate more easily to your project, where you may have your own way to configure deployment environment (different bucket for "staging" and "production", for example).

To include Thunagen, from your *main.py*, do:

.. code-block:: py

    from thunagen.functions import generate_gs_thumbnail


Credit
------

Thunagen is brought to you by `Nguyễn Hồng Quân <https://github.com/hongquan>`_, from SunshineTech (Việt Nam).

