Python client library for imgix.
Project description
.. image:: https://assets.imgix.net/imgix-logo-web-2014.pdf?page=2&fm=png&w=200&h=200
:alt: imgix logo
.. image:: https://travis-ci.org/imgix/imgix-python.png?branch=master
:alt: Build Status
:target: https://travis-ci.org/imgix/imgix-python
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
------------
.. code-block:: bash
$ 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.
.. code-block:: python
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:
.. code-block:: python
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.
.. code-block:: python
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**
To find out more, see our `blog post`_ explaining the decision to remove this feature.
.. _blog post: https://blog.imgix.com/2019/05/03/deprecating-domain-sharding
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.
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: python
# -*- 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:
.. code-block:: python
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:
.. code-block:: bash
tox
Changelog
=========
`2.2.0`_ (2019-05-07)
------------------
.. _2.2.0: https://github.com/imgix/imgix-python/compare/2.1.0...2.2.0
* deprecate domain sharding (`#41`_)(`#42`_)
.. _#41: https://github.com/imgix/imgix-python/pull/41
.. _#42: https://github.com/imgix/imgix-python/pull/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
:alt: imgix logo
.. image:: https://travis-ci.org/imgix/imgix-python.png?branch=master
:alt: Build Status
:target: https://travis-ci.org/imgix/imgix-python
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
------------
.. code-block:: bash
$ 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.
.. code-block:: python
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:
.. code-block:: python
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.
.. code-block:: python
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**
To find out more, see our `blog post`_ explaining the decision to remove this feature.
.. _blog post: https://blog.imgix.com/2019/05/03/deprecating-domain-sharding
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.
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: python
# -*- 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:
.. code-block:: python
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:
.. code-block:: bash
tox
Changelog
=========
`2.2.0`_ (2019-05-07)
------------------
.. _2.2.0: https://github.com/imgix/imgix-python/compare/2.1.0...2.2.0
* deprecate domain sharding (`#41`_)(`#42`_)
.. _#41: https://github.com/imgix/imgix-python/pull/41
.. _#42: https://github.com/imgix/imgix-python/pull/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
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.
Source Distribution
imgix-2.2.0.tar.gz
(10.4 kB
view hashes)
Built Distribution
imgix-2.2.0-py3-none-any.whl
(10.3 kB
view hashes)