imgix 2.3.0

Python client library for imgix.

A Python client library for generating URLs with imgix. imgix is a high-performance distributed image processing service. More information can be found at http://www.imgix.com.

Installation

$ pip install imgix

Basic Usage

To begin creating imgix URLs programmatically, simply import the imgix library and create a URL builder. The URL builder can be reused to create URLs for any images on the domains it is provided.

import imgix

builder = imgix.UrlBuilder("demos.imgix.net")
print builder.create_url("/bridge.png", {'w': 100, 'h': 100})

# Prints out:
# http://demos.imgix.net/bridge.png?h=100&w=100

For HTTPS support, simply specify the HTTPS flag like so:

import imgix

builder = imgix.UrlBuilder("demos.imgix.net", use_https=True)
print builder.create_url("/bridge.png", {'w': 100, 'h': 100})

# Prints out:
# https://demos.imgix.net/bridge.png?h=100&w=100

Signed URLs

To produce a signed URL, you must enable secure URLs on your source and then provide your signature key to the URL builder.

import imgix

builder = imgix.UrlBuilder("demos.imgix.net", sign_key="test1234")
print builder.create_url("/bridge.png", {'w': 100, 'h': 100})

# Prints out:
# http://demos.imgix.net/bridge.png?h=100&w=100&s=7370d6e36bb2262e73b19578739af1af

Domain Sharded URLs

Warning: Domain Sharding has been deprecated and will be removed in the next major release. As a result, the domains argument will be deprecated in favor of domain instead.

To find out more, see our blog post explaining the decision to remove this feature.

Domain sharding enables you to spread image requests across multiple domains. This allows you to bypass the requests-per-host limits of browsers. We recommend 2-3 domain shards maximum if you are going to use domain sharding.

In order to use domain sharding, you need to add multiple domains to your source. You then provide a list of these domains to a builder.

import imgix

builder = imgix.UrlBuilder([
    "demos-1.imgix.net",
    "demos-2.imgix.net",
    "demos-3.imgix.net",
])

print builder.create_url("/bridge.png", {'w': 100, 'h': 100})
print builder.create_url("/flower.png", {'w': 100, 'h': 100})

# Prints out:
# http://demos-2.imgix.net/bridge.png?h=100&w=100
# http://demos-3.imgix.net/flower.png?h=100&w=100

By default, shards are calculated using a checksum so that the image path always resolves to the same domain. This improves caching in the browser. However, you can supply a different strategy that cycles through domains instead. For example:

import imgix

builder = imgix.UrlBuilder([
    "demos-1.imgix.net",
    "demos-2.imgix.net",
    "demos-3.imgix.net",
], shard_strategy=imgix.SHARD_STRATEGY_CYCLE)

for i in xrange(4):
    print builder.create_url("/bridge.png", {'w': 100, 'h': 100})

# Prints out:
# http://demos-1.imgix.net/bridge.png?h=100&w=100
# http://demos-2.imgix.net/bridge.png?h=100&w=100
# http://demos-3.imgix.net/bridge.png?h=100&w=100
# http://demos-1.imgix.net/bridge.png?h=100&w=100

Usage with UTF-8

For usage with non-ASCII characters, please be sure to that your project’s source files specify UTF-8 encoding:

# -*- coding: utf-8 -*-

If you don’t add this encoding, and you have an image with name for example ‘tiburón.jpeg’, you will get the following error trying to run your script:

SyntaxError: Non-ASCII character '***' in file test.py on line 6, but no encoding declared; see http://www.python.org/peps/pep-0263.html for details

Running Tests

To run the tests and format the code, simply:

tox

Changelog

2.3.0 (2019-06-06)

• feat: deprecate domains in favor of domain (#45)

2.2.0 (2019-05-07)

• deprecate domain sharding (#41)(#42)

2.1.0 (2019-02-13)

• Domain validation added during UrlBuilder initialization

• sign_with_library_version parameter from UrlBuilder deprecated in favor of include_library_param.

2.0.0 (2018-08-08)

• UrlBuilder’s sign_mode argument removed

• opts parameter from UrlBuilder.create_url deprecated in favor of params.

1.2.0 (2018-06-20)

• sign_mode argument deprecated

• License corrected to BSD-2-Clause.

• Docstrings added to classes and methods.

1.1.2 (2016-06-30)

• Proper encodeURIComponent-style URL encoding for web proxy sources. See #21 for more information.

1.1.0 (2016-02-26)

• Added automatic Base64 encoding for all Base64 variant parameters.

• Properly encoding all query keys and values.

1.0.0 (2016-01-15)

• Change UrlBuilder#create_url to accept dict instead of kwargs. This fixes an issue with reserved words that are also imgix params potentially causing errors.

0.2.1 (2016-01-15)

• Fixed a bug where any passed params that were falsy would not be passed through to imgix.

0.2.0 (2015-06-15)

• Introduces defaulting to HTTPS on all requests, per the imgix-blueprint.

0.1.0 (2015-06-11)

• Includes new functionality to sign every URL with an ixlib parameter for diagnostic purposes.

0.0.4 (2015-06-10)

• New README note about publishing packages