Python client library for imgix.
Project description
imgix-python
is a client library for generating image URLs with imgix.
Installation
pip install imgix
Usage
To begin creating imgix URLs programmatically, 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, 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
Srcset Generation
The imgix-python package allows for generation of custom srcset
attributes, which can be invoked through create_srcset()
. By default,
the srcset generated will allow for responsive size switching by
building a list of image-width mappings.
builder = imgix.UrlBuilder("demos.imgix.net", sign_key="my-token", include_library_param=False)
srcset = builder.create_srcset("image.png")
print srcset
Will produce the following attribute value, which can then be served to the client:
https://demos.imgix.net/image.png?w=100&s=e415797545a77a9d2842dedcfe539c9a 100w,
https://demos.imgix.net/image.png?w=116&s=b2da46f5c23ef13d5da30f0a4545f33f 116w,
https://demos.imgix.net/image.png?w=134&s=b61422dead929f893c04b8ff839bb088 134w,
...
https://demos.imgix.net/image.png?w=7400&s=ad671301ed4663c3ce6e84cb646acb96 7400w,
https://demos.imgix.net/image.png?w=8192&s=a0fed46e2bbcc70ded13dc629aee5398 8192w
In cases where enough information is provided about an image's
dimensions, create_srcset()
will instead build a srcset that will
allow for an image to be served at different resolutions. The parameters
taken into consideration when determining if an image is fixed-width are
w
, h
, and ar
. By invoking create_srcset()
with either a width
or the height and aspect ratio (along with fit=crop
, typically)
provided, a different srcset will be generated for a fixed-size image
instead.
builder = imgix.UrlBuilder("demos.imgix.net", sign_key="my-token", include_library_param=False)
srcset = builder.create_srcset("image.png", {'h':800, 'ar':'3:2', 'fit':'crop'})
print srcset
Will produce the following attribute value:
https://demos.imgix.net/image.png?ar=3%3A2&dpr=1&fit=crop&h=800&s=6cf5c443d1eb98bc3d96ea569fcef088 1x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=2&fit=crop&h=800&s=d60a61a5f34545922bd8dff4e53a0555 2x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=3&fit=crop&h=800&s=590f96aa426f8589eb7e449ebbeb66e7 3x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=4&fit=crop&h=800&s=c89c2fd3148957647e86cfc32ba20517 4x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=5&fit=crop&h=800&s=3d73af69d78d49eef0f81b4b5d718a2c 5x
For more information to better understand srcset, we highly recommend Eric Portis' "Srcset and sizes" article which goes into depth about the subject.
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
Testing
Run the following to execute the project's tests and code linter:
tox
Changelog
3.1.2 (2019-03-11)
- Fix Python 2/3 compatibility issues (#57)
3.1.1 (2019-08-22)
- fix: include dpr parameter when generating fixed-width srcset (#50)
3.1.0 (2019-08-22)
- feat: add srcset generation (#48)
- build(tox): improve code coverage reporting; parallelize testing (#49)
3.0.0 (2019-06-07)
- fix: remove deprecated domain sharding functionality (#44)
- fix: remove deprecated [opts]{.title-ref} parameter (#46)
- fix: remove deprecated [sign_with_library_version]{.title-ref} parameter (#47)
2.3.0 (2019-06-06)
- feat: deprecate [domains]{.title-ref} in favor of [domain]{.title-ref} (#45)
2.2.0 (2019-05-07)
2.1.0 (2019-02-13)
- Domain validation added during [UrlBuilder]{.title-ref} initialization
- [sign_with_library_version]{.title-ref} parameter from [UrlBuilder]{.title-ref} deprecated in favor of [include_library_param]{.title-ref}.
2.0.0 (2018-08-08)
- [UrlBuilder]{.title-ref}'s [sign_mode]{.title-ref} argument removed
- [opts]{.title-ref} parameter from [UrlBuilder.create_url]{.title-ref} deprecated in favor of [params]{.title-ref}.
1.2.0 (2018-06-20)
- [sign_mode]{.title-ref} 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.