Python client library for imgix.
Project description
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)
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.