Tutorial for Python SDK

You can find the Python SDK also at the Pypi repository, check out https://pypi.org/project/toilmore-sdk/.

Prerequisites:

  • A token and domain to make requests to the API, see the quick start guide.
  • Python 3.7 or higher.
  • An image to optimize.

Installing

Step 1. Install

We highly recommend to create a python virtual environment.

$ virtualenv venv -p python3

Activate the virtual environment:

$ source venv/bin/activate

Install the sdk:

$ pip install toilmore-sdk

Step 2. Create script

  • Light API

If you plan to use the Light API, create a file e.g light.py, paste the code below.

Make sure to provide a valid authentication token as the api_token and its related domain as the domain. Also, be sure to add the path of the image you want to optimize as the image_path.


import os
import asyncio

from toilmoresdk import (
    LIGHT_API,
    Toilmore,
)
from toilmoresdk.submit_machine import (
    OptimizationResponseStatus,
    RejectionNoticeToHumanEnum,
)
from toilmoresdk.stream_helpers import store_file_content
from toilmoresdk.api_config import ApiConfig
from toilmoresdk.constants import PrecursorEnum
from toilmoresdk import constants

config = ApiConfig(
    # LIGHT_API contains our light api endpoint.
    api_endpoint=LIGHT_API,
    # Use a valid API token below:
    api_token='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    # Use a valid domain below, as received when
    # you created the token.
    domain='YYYYYYYYYYYYYYYYYYYYYYYYYY'
)

toilmore = Toilmore(config)

loop = asyncio.get_event_loop()

image_path = "./my_image.jpg"
precursor = PrecursorEnum.WEBP0
r = loop.run_until_complete(
    toilmore.optimize(image_path, precursor)
)

if r.status == OptimizationResponseStatus.FAILURE:
    rejection_notice = r.rejection_notice
    rejection_notice_enum = rejection_notice.rejection_notice
    human_readable = RejectionNoticeToHumanEnum[
        rejection_notice_enum.name
    ].value
    print(
        f'Failure: {human_readable} '
        f'rejection_notice: { rejection_notice.rejection_notice}, '
        f'inner_error: {rejection_notice.inner_error}'
    )
elif r.status == OptimizationResponseStatus.SUCCESS:
    base_filename, file_extension = os.path.splitext(image_path)
    output_filename = '{}{}'.format(
        base_filename,
        constants.PrecursorToExtensionEnum[precursor.name].value
    )
    output_dir = os.path.join(
        os.path.abspath(os.path.dirname(image_path)),
        output_filename
    )
    loop.run_until_complete(
        store_file_content(
            r.response_stream,
            output_dir
        )
    )
    print('Optimized image stored at: ', output_dir)

Step 3. Run script and optimize your image

To send your image for optimization, simply run the below command:

$ python light.py

Your image will be sent for optimization, and if nothing unexpected happens it will be sent to the same folder as the original image.

Would you like to run the SDK as a command line?

See the example below:


toilmoresdk --api-endpoint light --image-path ./my_image.jpg --api-token XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --domain YYYYYYYYYYYYYYYYYYYYYYYYYY --precursor webp0 --max-overhead 2 --output ./my_image.webp --verbose

and with short version of the parameters:


toilmoresdk -e light -i ./my_image.jpg -t XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -d YYYYYYYYYYYYYYYYYYYYYYYYYY -p webp0 -m 2 -o ./my_image.webp -v

Try: toilmoresdk --help and you will get examples, and all the options needed.

Video tutorial

The video tutorial below using VS code takes you through the quick process of setting up Pixellena Python SDK:

Updated: