pax_global_header 0000666 0000000 0000000 00000000064 15252340250 0014510 g ustar 00root root 0000000 0000000 52 comment=26cdc9d69a5698ea6786821f2e0376597d3ad6ca
matthewwithanm-django-imagekit-26cdc9d/ 0000775 0000000 0000000 00000000000 15252340250 0020301 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/.coveragerc 0000664 0000000 0000000 00000000211 15252340250 0022414 0 ustar 00root root 0000000 0000000 [run]
branch = true
parallel = true
[report]
show_missing = true
skip_empty = true
skip_covered = true
precision = 2
omit =
tests/*
matthewwithanm-django-imagekit-26cdc9d/.github/ 0000775 0000000 0000000 00000000000 15252340250 0021641 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/.github/workflows/ 0000775 0000000 0000000 00000000000 15252340250 0023676 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/.github/workflows/python.yml 0000664 0000000 0000000 00000001201 15252340250 0025734 0 ustar 00root root 0000000 0000000 name: Python CI
on:
push:
branches: [ develop ]
pull_request:
branches: [ develop ]
jobs:
build:
runs-on: ubuntu-latest
strategy:
max-parallel: 4
matrix:
python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
steps:
- uses: actions/checkout@v6
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v6
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install tox tox-gh-actions
- name: Run tests
run: tox
matthewwithanm-django-imagekit-26cdc9d/.gitignore 0000664 0000000 0000000 00000000252 15252340250 0022270 0 ustar 00root root 0000000 0000000 *.db
*.egg*
*.orig
*.pyc
.DS_Store
.tox
.idea
.vscode
.coverage
.coverage.*
.venv
MANIFEST
build
dist
/tests/media/*
!/tests/media/reference.png
/venv
/venv3
/.env
/tags
matthewwithanm-django-imagekit-26cdc9d/.readthedocs.yaml 0000664 0000000 0000000 00000001573 15252340250 0023536 0 ustar 00root root 0000000 0000000 version: 2
# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.12"
# You can also specify other tool versions:
# nodejs: "20"
# rust: "1.70"
# golang: "1.20"
# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/conf.py
# You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
# builder: "dirhtml"
# Fail on all warnings to avoid broken references
# fail_on_warning: true
# Optionally build your docs in additional formats such as PDF and ePub
# formats:
# - pdf
# - epub
# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
# python:
# install:
# - requirements: docs/requirements.txt
matthewwithanm-django-imagekit-26cdc9d/AUTHORS 0000664 0000000 0000000 00000003143 15252340250 0021352 0 ustar 00root root 0000000 0000000 ImageKit was originally written by `Justin Driscoll`_.
The field-based API and other post-1.0 stuff was written by the bright people at
HZDG_.
Maintainers
-----------
* `Venelin Stoykov`_
* `Matthew Tretter`_
* `Bryan Veloso`_
* `Chris Drackett`_
* `Greg Newman`_
Contributors
------------
* `Josh Ourisman`_
* `Jonathan Slenders`_
* `Eric Eldredge`_
* `Chris McKenzie`_
* `Markus Kaiserswerth`_
* `Ryan Bagwell`_
* `Alexander Bohn`_
* `Timothée Peignier`_
* `Madis Väin`_
* `Jan Sagemüller`_
* `Clay McClure`_
* `Jannis Leidel`_
* `Sean Bell`_
* `Saul Shanabrook`_
* `Jaap Roes`_
.. _Justin Driscoll: http://github.com/jdriscoll
.. _HZDG: http://hzdg.com
.. _Bryan Veloso: http://github.com/bryanveloso
.. _Chris Drackett: http://github.com/chrisdrackett
.. _Greg Newman: http://github.com/gregnewman
.. _Josh Ourisman: http://github.com/joshourisman
.. _Jonathan Slenders: http://github.com/jonathanslenders
.. _Matthew Tretter: http://github.com/matthewwithanm
.. _Eric Eldredge: http://github.com/lettertwo
.. _Chris McKenzie: http://github.com/kenzic
.. _Ryan Bagwell: http://github.com/ryanbagwell
.. _Markus Kaiserswerth: http://github.com/mkai
.. _Alexander Bohn: http://github.com/fish2000
.. _Timothée Peignier: http://github.com/cyberdelia
.. _Madis Väin: http://github.com/madisvain
.. _Jan Sagemüller: https://github.com/version2
.. _Clay McClure: https://github.com/claymation
.. _Jannis Leidel: https://github.com/jezdez
.. _Sean Bell: https://github.com/seanbell
.. _Saul Shanabrook: https://github.com/saulshanabrook
.. _Venelin Stoykov: https://github.com/vstoykov
.. _Jaap Roes: https://github.com/jaap3
matthewwithanm-django-imagekit-26cdc9d/CONTRIBUTING.rst 0000664 0000000 0000000 00000002257 15252340250 0022750 0 ustar 00root root 0000000 0000000 Contributing
------------
We love contributions! These guidelines will help make sure we can get your
contributions merged as quickly as possible:
1. Write `good commit messages`__!
2. If you want to add a new feature, talk to us on the `mailing list`__ or
`IRC`__ first. We might already have plans, or be able to offer some advice.
3. Make sure your code passes the tests that ImageKit already has. To run the
tests, first install tox, ``pip install tox``, then use ``tox``. This will let you know about any errors or style
issues.
4. While we're talking about tests, creating new ones for your code makes it
much easier for us to merge your code quickly. ImageKit uses pytest_, so
writing tests is painless. Check out `ours`__ for examples.
5. It's a good idea to do your work in a branch; that way, you can work on more
than one contribution at a time without making them interdependent.
__ http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
__ https://groups.google.com/forum/#!forum/django-imagekit
__ irc://irc.freenode.net/imagekit
.. _pytest: https://docs.pytest.org/en/latest/
__ https://github.com/matthewwithanm/django-imagekit/tree/develop/tests
matthewwithanm-django-imagekit-26cdc9d/LICENSE 0000664 0000000 0000000 00000003076 15252340250 0021314 0 ustar 00root root 0000000 0000000 Copyright (c) 2007-2008, Justin C. Driscoll
Copyright (c) 2011, Justin C. Driscoll and Primary Maintainers
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of django-imagekit nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
matthewwithanm-django-imagekit-26cdc9d/MANIFEST.in 0000664 0000000 0000000 00000000777 15252340250 0022052 0 ustar 00root root 0000000 0000000 include AUTHORS
include LICENSE
include README.rst
include pyproject.toml
include testrunner.py
include tests/*.py
include tests/assets/Lenna.png
include tests/assets/lenna-*.jpg
include tests/media/lenna.png
prune tests/media/CACHE
prune tests/media/b
prune tests/media/photos
include docs/Makefile
include docs/conf.py
include docs/make.bat
include docs/*.rst
recursive-include docs/_themes LICENSE README.rst flask_theme_support.py theme.conf *.css_t *.css *.html
recursive-include imagekit/templates *.html
matthewwithanm-django-imagekit-26cdc9d/README.rst 0000664 0000000 0000000 00000041017 15252340250 0021773 0 ustar 00root root 0000000 0000000 |Build Status|_
.. |Build Status| image:: https://github.com/matthewwithanm/django-imagekit/actions/workflows/python.yml/badge.svg?branch=develop
.. _Build Status: https://github.com/matthewwithanm/django-imagekit/actions/workflows/python.yml
ImageKit is a Django app for processing images. Need a thumbnail? A
black-and-white version of a user-uploaded image? ImageKit will make them for
you. If you need to programmatically generate one image from another, you need
ImageKit.
ImageKit comes with a bunch of image processors for common tasks like resizing
and cropping, but you can also create your own. For an idea of what's possible,
check out the `Instakit`__ project.
**For the complete documentation on the latest stable version of ImageKit, see**
`ImageKit on RTD`_.
.. _`ImageKit on RTD`: http://django-imagekit.readthedocs.org
__ https://github.com/fish2000/instakit
Installation
============
1. Install `Pillow`_. (If you're using an ``ImageField`` in Django,
you should have already done this.)
2. ``pip install django-imagekit``
3. Add ``'imagekit'`` to your ``INSTALLED_APPS`` list in your project's ``settings.py``
.. _`Pillow`: http://pypi.python.org/pypi/Pillow
Usage Overview
==============
.. _specs:
Specs
-----
You have one image and you want to do something to it to create another image.
But how do you tell ImageKit what to do? By defining an image spec.
An **image spec** is a type of **image generator** that generates a new image
from a source image.
Defining Specs In Models
^^^^^^^^^^^^^^^^^^^^^^^^
The easiest way to use define an image spec is by using an ImageSpecField on
your model class:
.. code-block:: python
from django.db import models
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
processors=[ResizeToFill(100, 50)],
format='JPEG',
options={'quality': 60})
profile = Profile.objects.all()[0]
print(profile.avatar_thumbnail.url) # > /media/CACHE/images/982d5af84cddddfd0fbf70892b4431e4.jpg
print(profile.avatar_thumbnail.width) # > 100
As you can probably tell, ImageSpecFields work a lot like Django's
ImageFields. The difference is that they're automatically generated by
ImageKit based on the instructions you give. In the example above, the avatar
thumbnail is a resized version of the avatar image, saved as a JPEG with a
quality of 60.
Sometimes, however, you don't need to keep the original image (the avatar in
the above example); when the user uploads an image, you just want to process it
and save the result. In those cases, you can use the ``ProcessedImageField``
class:
.. code-block:: python
from django.db import models
from imagekit.models import ProcessedImageField
from imagekit.processors import ResizeToFill
class Profile(models.Model):
avatar_thumbnail = ProcessedImageField(upload_to='avatars',
processors=[ResizeToFill(100, 50)],
format='JPEG',
options={'quality': 60})
profile = Profile.objects.all()[0]
print(profile.avatar_thumbnail.url) # > /media/avatars/MY-avatar.jpg
print(profile.avatar_thumbnail.width) # > 100
This is pretty similar to our previous example. We don't need to specify a
"source" any more since we're not processing another image field, but we do need
to pass an "upload_to" argument. This behaves exactly as it does for Django
ImageFields.
.. note::
You might be wondering why we didn't need an "upload_to" argument for our
ImageSpecField. The reason is that ProcessedImageFields really are just like
ImageFields—they save the file path in the database and you need to run
syncdb (or create a migration) when you add one to your model.
ImageSpecFields, on the other hand, are virtual—they add no fields to your
database and don't require a database. This is handy for a lot of reasons,
but it means that the path to the image file needs to be programmatically
constructed based on the source image and the spec.
Defining Specs Outside of Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Defining specs as models fields is one very convenient way to process images,
but it isn't the only way. Sometimes you can't (or don't want to) add fields to
your models, and that's okay. You can define image spec classes and use them
directly. This can be especially useful for doing image processing in views—
particularly when the processing being done depends on user input.
.. code-block:: python
from imagekit import ImageSpec
from imagekit.processors import ResizeToFill
class Thumbnail(ImageSpec):
processors = [ResizeToFill(100, 50)]
format = 'JPEG'
options = {'quality': 60}
It's probably not surprising that this class is capable of processing an image
in the exact same way as our ImageSpecField above. However, unlike with the
image spec model field, this class doesn't define what source the spec is acting
on, or what should be done with the result; that's up to you:
.. code-block:: python
source_file = open('/path/to/myimage.jpg', 'rb')
image_generator = Thumbnail(source=source_file)
result = image_generator.generate()
.. note::
You don't have to use ``open``! You can use whatever File-like object you
want—including a model's ``ImageField``.
The result of calling ``generate()`` on an image spec is a file-like object
containing our resized image, with which you can do whatever you want. For
example, if you wanted to save it to disk:
.. code-block:: python
dest = open('/path/to/dest.jpg', 'wb')
dest.write(result.read())
dest.close()
Using Specs In Templates
^^^^^^^^^^^^^^^^^^^^^^^^
If you have a model with an ImageSpecField or ProcessedImageField, you can
easily use those processed image just as you would a normal image field:
.. code-block:: html
(This is assuming you have a view that's setting a context variable named
"profile" to an instance of our Profile model.)
But you can also generate processed image files directly in your template—from
any image—without adding anything to your model. In order to do this, you'll
first have to define an image generator class (remember, specs are a type of
generator) in your app somewhere, just as we did in the last section. You'll
also need a way of referring to the generator in your template, so you'll need
to register it.
.. code-block:: python
from imagekit import ImageSpec, register
from imagekit.processors import ResizeToFill
class Thumbnail(ImageSpec):
processors = [ResizeToFill(100, 50)]
format = 'JPEG'
options = {'quality': 60}
register.generator('myapp:thumbnail', Thumbnail)
.. note::
You can register your generator with any id you want, but choose wisely!
If you pick something too generic, you could have a conflict with another
third-party app you're using. For this reason, it's a good idea to prefix
your generator ids with the name of your app. Also, ImageKit recognizes
colons as separators when doing pattern matching (e.g. in the generateimages
management command), so it's a good idea to use those too!
.. warning::
This code can go in any file you want—but you need to make sure it's loaded!
In order to keep things simple, ImageKit will automatically try to load an
module named "imagegenerators" in each of your installed apps. So why don't
you just save yourself the headache and put your image specs in there?
Now that we've created an image generator class and registered it with ImageKit,
we can use it in our templates!
generateimage
"""""""""""""
The most generic template tag that ImageKit gives you is called "generateimage".
It requires at least one argument: the id of a registered image generator.
Additional keyword-style arguments are passed to the registered generator class.
As we saw above, image spec constructors expect a source keyword argument, so
that's what we need to pass to use our thumbnail spec:
.. code-block:: html
{% load imagekit %}
{% generateimage 'myapp:thumbnail' source=source_file %}
This will output the following HTML:
.. code-block:: html
You can also add additional HTML attributes; just separate them from your
keyword args using two dashes:
.. code-block:: html
{% load imagekit %}
{% generateimage 'myapp:thumbnail' source=source_file -- alt="A picture of Me" id="mypicture" %}
Not generating HTML image tags? No problem. The tag also functions as an
assignment tag, providing access to the underlying file object:
.. code-block:: html
{% load imagekit %}
{% generateimage 'myapp:thumbnail' source=source_file as th %}
Click to download a cool {{ th.width }} x {{ th.height }} image!
thumbnail
"""""""""
Because it's such a common use case, ImageKit also provides a "thumbnail"
template tag:
.. code-block:: html
{% load imagekit %}
{% thumbnail '100x50' source_file %}
Like the generateimage tag, the thumbnail tag outputs an tag:
.. code-block:: html
Comparing this syntax to the generateimage tag above, you'll notice a few
differences.
First, we didn't have to specify an image generator id; unless we tell it
otherwise, thumbnail tag uses the generator registered with the id
"imagekit:thumbnail". **It's important to note that this tag is *not* using the
Thumbnail spec class we defined earlier**; it's using the generator registered
with the id "imagekit:thumbnail" which, by default, is
``imagekit.generatorlibrary.Thumbnail``.
Second, we're passing two positional arguments (the dimensions and the source
image) as opposed to the keyword arguments we used with the generateimage tag.
Like with the generateimage tag, you can also specify additional HTML attributes
for the thumbnail tag, or use it as an assignment tag:
.. code-block:: html
{% load imagekit %}
{% thumbnail '100x50' source_file -- alt="A picture of Me" id="mypicture" %}
{% thumbnail '100x50' source_file as th %}
Using Specs in Forms
^^^^^^^^^^^^^^^^^^^^
In addition to the model field above, there's also a form field version of the
``ProcessedImageField`` class. The functionality is basically the same (it
processes an image once and saves the result), but it's used in a form class:
.. code-block:: python
from django import forms
from imagekit.forms import ProcessedImageField
from imagekit.processors import ResizeToFill
class ProfileForm(forms.Form):
avatar_thumbnail = ProcessedImageField(spec_id='myapp:profile:avatar_thumbnail',
processors=[ResizeToFill(100, 50)],
format='JPEG',
options={'quality': 60})
The benefit of using ``imagekit.forms.ProcessedImageField`` (as opposed to
``imagekit.models.ProcessedImageField`` above) is that it keeps the logic for
creating the image outside of your model (in which you would use a normal Django
ImageField). You can even create multiple forms, each with their own
ProcessedImageField, that all store their results in the same image field.
Processors
----------
So far, we've only seen one processor: ``imagekit.processors.ResizeToFill``. But
ImageKit is capable of far more than just resizing images, and that power comes
from its processors.
Processors take a PIL image object, do something to it, and return a new one.
A spec can make use of as many processors as you'd like, which will all be run
in order.
.. code-block:: python
from imagekit import ImageSpec
from imagekit.processors import TrimBorderColor, Adjust
class MySpec(ImageSpec):
processors = [
TrimBorderColor(),
Adjust(contrast=1.2, sharpness=1.1),
]
format = 'JPEG'
options = {'quality': 60}
The ``imagekit.processors`` module contains processors for many common
image manipulations, like resizing, rotating, and color adjustments. However,
if they aren't up to the task, you can create your own. All you have to do is
define a class that implements a ``process()`` method:
.. code-block:: python
class Watermark(object):
def process(self, image):
# Code for adding the watermark goes here.
return image
That's all there is to it! To use your fancy new custom processor, just include
it in your spec's ``processors`` list:
.. code-block:: python
from imagekit import ImageSpec
from imagekit.processors import TrimBorderColor, Adjust
from myapp.processors import Watermark
class MySpec(ImageSpec):
processors = [
TrimBorderColor(),
Adjust(contrast=1.2, sharpness=1.1),
Watermark(),
]
format = 'JPEG'
options = {'quality': 60}
Note that when you import a processor from ``imagekit.processors``, imagekit
in turn imports the processor from `PILKit`_. So if you are looking for
available processors, look at PILKit.
.. _`PILKit`: https://github.com/matthewwithanm/pilkit
Admin
-----
ImageKit also contains a class named ``imagekit.admin.AdminThumbnail``
for displaying specs (or even regular ImageFields) in the
`Django admin change list`_. AdminThumbnail is used as a property on
Django admin classes:
.. code-block:: python
from django.contrib import admin
from imagekit.admin import AdminThumbnail
from .models import Photo
class PhotoAdmin(admin.ModelAdmin):
list_display = ('__str__', 'admin_thumbnail')
admin_thumbnail = AdminThumbnail(image_field='thumbnail')
admin.site.register(Photo, PhotoAdmin)
To use specs defined outside of models:
.. code-block:: python
from django.contrib import admin
from imagekit.admin import AdminThumbnail
from imagekit import ImageSpec
from imagekit.processors import ResizeToFill
from imagekit.cachefiles import ImageCacheFile
from .models import Photo
class AdminThumbnailSpec(ImageSpec):
processors = [ResizeToFill(100, 30)]
format = 'JPEG'
options = {'quality': 60 }
def cached_admin_thumb(instance):
# `image` is the name of the image field on the model
cached = ImageCacheFile(AdminThumbnailSpec(instance.image))
# only generates the first time, subsequent calls use cache
cached.generate()
return cached
class PhotoAdmin(admin.ModelAdmin):
list_display = ('__str__', 'admin_thumbnail')
admin_thumbnail = AdminThumbnail(image_field=cached_admin_thumb)
admin.site.register(Photo, PhotoAdmin)
AdminThumbnail can even use a custom template. For more information, see
``imagekit.admin.AdminThumbnail``.
.. _`Django admin change list`: https://docs.djangoproject.com/en/dev/intro/tutorial02/#customize-the-admin-change-list
Management Commands
-------------------
ImageKit has one management command—``generateimages``—which will generate cache
files for all of your registered image generators. You can also pass it a list
of generator ids in order to generate images selectively.
Community
=========
Please use `the GitHub issue tracker `_
to report bugs with django-imagekit. `A mailing list `_
also exists to discuss the project and ask questions, as well as the official
`#imagekit `_ channel on Freenode.
Contributing
============
We love contributions! And you don't have to be an expert with the library—or
even Django—to contribute either: ImageKit's processors are standalone classes
that are completely separate from the more intimidating internals of Django's
ORM. If you've written a processor that you think might be useful to other
people, open a pull request so we can take a look!
You can also check out our list of `open, contributor-friendly issues`__ for
ideas.
Check out our `contributing guidelines`_ for more information about pitching in
with ImageKit.
__ https://github.com/matthewwithanm/django-imagekit/issues?labels=contributor-friendly&state=open
.. _`contributing guidelines`: https://github.com/matthewwithanm/django-imagekit/blob/develop/CONTRIBUTING.rst
matthewwithanm-django-imagekit-26cdc9d/docs/ 0000775 0000000 0000000 00000000000 15252340250 0021231 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/docs/Makefile 0000664 0000000 0000000 00000012731 15252340250 0022675 0 ustar 00root root 0000000 0000000 # Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = python $(shell which sphinx-build)
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make ' where is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ImageKit.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ImageKit.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/ImageKit"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ImageKit"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/ 0000775 0000000 0000000 00000000000 15252340250 0022655 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/docs/_themes/LICENSE 0000775 0000000 0000000 00000003507 15252340250 0023672 0 ustar 00root root 0000000 0000000 Modifications:
Copyright (c) 2010 Kenneth Reitz.
Original Project:
Copyright (c) 2010 by Armin Ronacher.
Some rights reserved.
Redistribution and use in source and binary forms of the theme, with or
without modification, are permitted provided that the following conditions
are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
* The names of the contributors may not be used to endorse or
promote products derived from this software without specific
prior written permission.
We kindly ask you to only use these themes in an unmodified manner just
for Flask and Flask-related products, not for unrelated projects. If you
like the visual style and want to use it for your own projects, please
consider making some larger changes to the themes (such as changing
font faces, sizes, colors or margins).
THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/README.rst 0000775 0000000 0000000 00000001325 15252340250 0024350 0 ustar 00root root 0000000 0000000 krTheme Sphinx Style
====================
This repository contains sphinx styles Kenneth Reitz uses in most of
his projects. It is a derivative of Mitsuhiko's themes for Flask and Flask related
projects. To use this style in your Sphinx documentation, follow
this guide:
1. put this folder as _themes into your docs folder. Alternatively
you can also use git submodules to check out the contents there.
2. add this to your conf.py: ::
sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
html_theme = 'kr'
The following themes exist:
**kr**
the standard flask documentation theme for large projects
**kr_small**
small one-page theme. Intended to be used by very small addon libraries.
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/flask_theme_support.py 0000775 0000000 0000000 00000011476 15252340250 0027321 0 ustar 00root root 0000000 0000000 # flasky extensions. flasky pygments style based on tango style
from pygments.style import Style
from pygments.token import (Comment, Error, Generic, Keyword, Literal, Name,
Number, Operator, Other, Punctuation, String,
Whitespace)
class FlaskyStyle(Style):
background_color = "#f8f8f8"
default_style = ""
styles = {
# No corresponding class for the following:
#Text: "", # class: ''
Whitespace: "underline #f8f8f8", # class: 'w'
Error: "#a40000 border:#ef2929", # class: 'err'
Other: "#000000", # class 'x'
Comment: "italic #8f5902", # class: 'c'
Comment.Preproc: "noitalic", # class: 'cp'
Keyword: "bold #004461", # class: 'k'
Keyword.Constant: "bold #004461", # class: 'kc'
Keyword.Declaration: "bold #004461", # class: 'kd'
Keyword.Namespace: "bold #004461", # class: 'kn'
Keyword.Pseudo: "bold #004461", # class: 'kp'
Keyword.Reserved: "bold #004461", # class: 'kr'
Keyword.Type: "bold #004461", # class: 'kt'
Operator: "#582800", # class: 'o'
Operator.Word: "bold #004461", # class: 'ow' - like keywords
Punctuation: "bold #000000", # class: 'p'
# because special names such as Name.Class, Name.Function, etc.
# are not recognized as such later in the parsing, we choose them
# to look the same as ordinary variables.
Name: "#000000", # class: 'n'
Name.Attribute: "#c4a000", # class: 'na' - to be revised
Name.Builtin: "#004461", # class: 'nb'
Name.Builtin.Pseudo: "#3465a4", # class: 'bp'
Name.Class: "#000000", # class: 'nc' - to be revised
Name.Constant: "#000000", # class: 'no' - to be revised
Name.Decorator: "#888", # class: 'nd' - to be revised
Name.Entity: "#ce5c00", # class: 'ni'
Name.Exception: "bold #cc0000", # class: 'ne'
Name.Function: "#000000", # class: 'nf'
Name.Property: "#000000", # class: 'py'
Name.Label: "#f57900", # class: 'nl'
Name.Namespace: "#000000", # class: 'nn' - to be revised
Name.Other: "#000000", # class: 'nx'
Name.Tag: "bold #004461", # class: 'nt' - like a keyword
Name.Variable: "#000000", # class: 'nv' - to be revised
Name.Variable.Class: "#000000", # class: 'vc' - to be revised
Name.Variable.Global: "#000000", # class: 'vg' - to be revised
Name.Variable.Instance: "#000000", # class: 'vi' - to be revised
Number: "#990000", # class: 'm'
Literal: "#000000", # class: 'l'
Literal.Date: "#000000", # class: 'ld'
String: "#4e9a06", # class: 's'
String.Backtick: "#4e9a06", # class: 'sb'
String.Char: "#4e9a06", # class: 'sc'
String.Doc: "italic #8f5902", # class: 'sd' - like a comment
String.Double: "#4e9a06", # class: 's2'
String.Escape: "#4e9a06", # class: 'se'
String.Heredoc: "#4e9a06", # class: 'sh'
String.Interpol: "#4e9a06", # class: 'si'
String.Other: "#4e9a06", # class: 'sx'
String.Regex: "#4e9a06", # class: 'sr'
String.Single: "#4e9a06", # class: 's1'
String.Symbol: "#4e9a06", # class: 'ss'
Generic: "#000000", # class: 'g'
Generic.Deleted: "#a40000", # class: 'gd'
Generic.Emph: "italic #000000", # class: 'ge'
Generic.Error: "#ef2929", # class: 'gr'
Generic.Heading: "bold #000080", # class: 'gh'
Generic.Inserted: "#00A000", # class: 'gi'
Generic.Output: "#888", # class: 'go'
Generic.Prompt: "#745334", # class: 'gp'
Generic.Strong: "bold #000000", # class: 'gs'
Generic.Subheading: "bold #800080", # class: 'gu'
Generic.Traceback: "bold #a40000", # class: 'gt'
}
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr/ 0000775 0000000 0000000 00000000000 15252340250 0023271 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr/layout.html 0000775 0000000 0000000 00000001141 15252340250 0025474 0 ustar 00root root 0000000 0000000 {%- extends "basic/layout.html" %}
{%- block extrahead %}
{{ super() }}
{% if theme_touch_icon %}
{% endif %}
{% endblock %}
{%- block relbar2 %}{% endblock %}
{%- block footer %}
{%- endblock %}
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr/relations.html 0000775 0000000 0000000 00000001116 15252340250 0026161 0 ustar 00root root 0000000 0000000
{% endif %}
{% endblock %}
{# do not display relbars #}
{% block relbar1 %}{% endblock %}
{% block relbar2 %}
{% if theme_github_fork %}
{% endif %}
{% endblock %}
{% block sidebar1 %}{% endblock %}
{% block sidebar2 %}{% endblock %}
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr_small/static/ 0000775 0000000 0000000 00000000000 15252340250 0025750 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr_small/static/flasky.css_t 0000775 0000000 0000000 00000011001 15252340250 0030272 0 ustar 00root root 0000000 0000000 /*
* flasky.css_t
* ~~~~~~~~~~~~
*
* Sphinx stylesheet -- flasky theme based on nature theme.
*
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
@import url("basic.css");
/* -- page layout ----------------------------------------------------------- */
body {
font-family: 'Georgia', serif;
font-size: 17px;
color: #000;
background: white;
margin: 0;
padding: 0;
}
div.documentwrapper {
float: left;
width: 100%;
}
div.bodywrapper {
margin: 40px auto 0 auto;
width: 700px;
}
hr {
border: 1px solid #B1B4B6;
}
div.body {
background-color: #ffffff;
color: #3E4349;
padding: 0 30px 30px 30px;
}
img.floatingflask {
padding: 0 0 10px 10px;
float: right;
}
div.footer {
text-align: right;
color: #888;
padding: 10px;
font-size: 14px;
width: 650px;
margin: 0 auto 40px auto;
}
div.footer a {
color: #888;
text-decoration: underline;
}
div.related {
line-height: 32px;
color: #888;
}
div.related ul {
padding: 0 0 0 10px;
}
div.related a {
color: #444;
}
/* -- body styles ----------------------------------------------------------- */
a {
color: #004B6B;
text-decoration: underline;
}
a:hover {
color: #6D4100;
text-decoration: underline;
}
div.body {
padding-bottom: 40px; /* saved for footer */
}
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
font-family: 'Garamond', 'Georgia', serif;
font-weight: normal;
margin: 30px 0px 10px 0px;
padding: 0;
}
{% if theme_index_logo %}
div.indexwrapper h1 {
text-indent: -999999px;
background: url({{ theme_index_logo }}) no-repeat center center;
height: {{ theme_index_logo_height }};
}
{% endif %}
div.body h2 { font-size: 180%; }
div.body h3 { font-size: 150%; }
div.body h4 { font-size: 130%; }
div.body h5 { font-size: 100%; }
div.body h6 { font-size: 100%; }
a.headerlink {
color: white;
padding: 0 4px;
text-decoration: none;
}
a.headerlink:hover {
color: #444;
background: #eaeaea;
}
div.body p, div.body dd, div.body li {
line-height: 1.4em;
}
div.admonition {
background: #fafafa;
margin: 20px -30px;
padding: 10px 30px;
border-top: 1px solid #ccc;
border-bottom: 1px solid #ccc;
}
div.admonition p.admonition-title {
font-family: 'Garamond', 'Georgia', serif;
font-weight: normal;
font-size: 24px;
margin: 0 0 10px 0;
padding: 0;
line-height: 1;
}
div.admonition p.last {
margin-bottom: 0;
}
div.highlight{
background-color: white;
}
dt:target, .highlight {
background: #FAF3E8;
}
div.note {
background-color: #eee;
border: 1px solid #ccc;
}
div.seealso {
background-color: #ffc;
border: 1px solid #ff6;
}
div.topic {
background-color: #eee;
}
div.warning {
background-color: #ffe4e4;
border: 1px solid #f66;
}
p.admonition-title {
display: inline;
}
p.admonition-title:after {
content: ":";
}
pre, tt {
font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
font-size: 0.85em;
}
img.screenshot {
}
tt.descname, tt.descclassname {
font-size: 0.95em;
}
tt.descname {
padding-right: 0.08em;
}
img.screenshot {
-moz-box-shadow: 2px 2px 4px #eee;
-webkit-box-shadow: 2px 2px 4px #eee;
box-shadow: 2px 2px 4px #eee;
}
table.docutils {
border: 1px solid #888;
-moz-box-shadow: 2px 2px 4px #eee;
-webkit-box-shadow: 2px 2px 4px #eee;
box-shadow: 2px 2px 4px #eee;
}
table.docutils td, table.docutils th {
border: 1px solid #888;
padding: 0.25em 0.7em;
}
table.field-list, table.footnote {
border: none;
-moz-box-shadow: none;
-webkit-box-shadow: none;
box-shadow: none;
}
table.footnote {
margin: 15px 0;
width: 100%;
border: 1px solid #eee;
}
table.field-list th {
padding: 0 0.8em 0 0;
}
table.field-list td {
padding: 0;
}
table.footnote td {
padding: 0.5em;
}
dl {
margin: 0;
padding: 0;
}
dl dd {
margin-left: 30px;
}
pre {
padding: 0;
margin: 15px -30px;
padding: 8px;
line-height: 1.3em;
padding: 7px 30px;
background: #eee;
border-radius: 2px;
-moz-border-radius: 2px;
-webkit-border-radius: 2px;
}
dl pre {
margin-left: -60px;
padding-left: 60px;
}
tt {
background-color: #ecf0f3;
color: #222;
/* padding: 1px 2px; */
}
tt.xref, a tt {
background-color: #FBFBFB;
}
a:hover tt {
background: #EEE;
}
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr_small/theme.conf 0000775 0000000 0000000 00000000270 15252340250 0026434 0 ustar 00root root 0000000 0000000 [theme]
inherit = basic
stylesheet = flasky.css
nosidebar = true
pygments_style = flask_theme_support.FlaskyStyle
[options]
index_logo = ''
index_logo_height = 120px
github_fork = ''
matthewwithanm-django-imagekit-26cdc9d/docs/advanced_usage.rst 0000664 0000000 0000000 00000016004 15252340250 0024715 0 ustar 00root root 0000000 0000000 Advanced Usage
**************
Models
======
The ``ImageSpecField`` Shorthand Syntax
---------------------------------------
If you've read the README, you already know what an ``ImageSpecField`` is and
the basics of defining one:
.. code-block:: python
from django.db import models
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
processors=[ResizeToFill(100, 50)],
format='JPEG',
options={'quality': 60})
This will create an ``avatar_thumbnail`` field which is a resized version of the
image stored in the ``avatar`` image field. But this is actually just shorthand
for creating an ``ImageSpec``, registering it, and associating it with an
``ImageSpecField``:
.. code-block:: python
from django.db import models
from imagekit import ImageSpec, register
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill
class AvatarThumbnail(ImageSpec):
processors = [ResizeToFill(100, 50)]
format = 'JPEG'
options = {'quality': 60}
register.generator('myapp:profile:avatar_thumbnail', AvatarThumbnail)
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
id='myapp:profile:avatar_thumbnail')
Obviously, the shorthand version is a lot, well…shorter. So why would you ever
want to go through the trouble of using the long form? The answer is that the
long form—creating an image spec class and registering it—gives you a lot more
power over the generated image.
.. _dynamic-specs:
Specs That Change
-----------------
As you'll remember from the README, an image spec is just a type of image
generator that generates a new image from a source image. How does the image
spec get access to the source image? Simple! It's passed to the constructor as
a keyword argument and stored as an attribute of the spec. Normally, we don't
have to concern ourselves with this; the ``ImageSpec`` knows what to do with the
source image and we're happy to let it do its thing. However, having access to
the source image in our spec class can be very useful…
Often, when using an ``ImageSpecField``, you may want the spec to vary based on
properties of a model. (For example, you might want to store image dimensions on
the model and then use them to generate your thumbnail.) Now that we know how to
access the source image from our spec, it's a simple matter to extract its model
and use it to create our processors list. In fact, ImageKit includes a utility
for getting this information.
.. code-block:: python
:emphasize-lines: 11-14
from django.db import models
from imagekit import ImageSpec, register
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill
from imagekit.utils import get_field_info
class AvatarThumbnail(ImageSpec):
format = 'JPEG'
options = {'quality': 60}
@property
def processors(self):
model, field_name = get_field_info(self.source)
return [ResizeToFill(model.thumbnail_width, model.thumbnail_height)]
register.generator('myapp:profile:avatar_thumbnail', AvatarThumbnail)
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
id='myapp:profile:avatar_thumbnail')
thumbnail_width = models.PositiveIntegerField()
thumbnail_height = models.PositiveIntegerField()
Now each avatar thumbnail will be resized according to the dimensions stored on
the model!
Of course, processors aren't the only thing that can vary based on the model of
the source image; spec behavior can change in any way you want.
.. _source-groups:
Source Groups
=============
When you run the ``generateimages`` management command, how does ImageKit know
which source images to use with which specs? Obviously, when you define an
ImageSpecField, the source image is being connected to a spec, but what's going
on underneath the hood?
The answer is that, when you define an ImageSpecField, ImageKit automatically
creates and registers an object called a *source group*. Source groups are
responsible for two things:
1. They dispatch signals when a source is saved, and
2. They expose a generator method that enumerates source files.
When these objects are registered (using ``imagekit.register.source_group()``),
their signals will trigger callbacks on the cache file strategies associated
with image specs that use the source. (So, for example, you can chose to
generate a file every time the source image changes.) In addition, the generator
method is used (indirectly) to create the list of files to generate with the
``generateimages`` management command.
Currently, there is only one source group class bundled with ImageKit—the one
used by ImageSpecFields. This source group
(``imagekit.specs.sourcegroups.ImageFieldSourceGroup``) represents an ImageField
on every instance of a particular model. In terms of the above description, the
instance ``ImageFieldSourceGroup(Profile, 'avatar')`` 1) dispatches a signal
every time the image in Profile's avatar ImageField changes, and 2) exposes a
generator method that iterates over every Profile's "avatar" image.
Chances are, this is the only source group you will ever need to use, however,
ImageKit lets you define and register custom source groups easily. This may be
useful, for example, if you're using the template tags "generateimage" and
"thumbnail" and the optimistic cache file strategy. Again, the purpose is
to tell ImageKit which specs are used with which sources (so the
"generateimages" management command can generate those files) and when the
source image has been created or changed (so that the strategy has the
opportunity to act on it).
A simple example of a custom source group class is as follows:
.. code-block:: python
import glob
import os
class JpegsInADirectory(object):
def __init__(self, dir):
self.dir = dir
def files(self):
os.chdir(self.dir)
for name in glob.glob('*.jpg'):
yield open(name, 'rb')
Instances of this class could then be registered with one or more spec id:
.. code-block:: python
from imagekit import register
register.source_group('myapp:profile:avatar_thumbnail', JpegsInADirectory('/path/to/some/pics'))
Running the "generateimages" management command would now cause thumbnails to be
generated (using the "myapp:profile:avatar_thumbnail" spec) for each of the
JPEGs in `/path/to/some/pics`.
Note that, since this source group doesnt send the `source_saved` signal, the
corresponding cache file strategy callbacks would not be called for them.
matthewwithanm-django-imagekit-26cdc9d/docs/caching.rst 0000664 0000000 0000000 00000027111 15252340250 0023361 0 ustar 00root root 0000000 0000000 Caching
*******
Default Backend Workflow
========================
``ImageSpec``
-------------
At the heart of ImageKit are image generators. These are classes with a
``generate()`` method which returns an image file. An image spec is a type of
image generator. The thing that makes specs special is that they accept a source
image. So an image spec is just an image generator that makes an image from some
other image.
``ImageCacheFile``
------------------
However, an image spec by itself would be vastly inefficient. Every time an
an image was accessed in some way, it would have be regenerated and saved.
Most of the time, you want to re-use a previously generated image, based on the
input image and spec, instead of generating a new one. That's where
``ImageCacheFile`` comes in. ``ImageCacheFile`` is a File-like object that
wraps an image generator. They look and feel just like regular file
objects, but they've got a little trick up their sleeve: they represent files
that may not actually exist!
.. _cache-file-strategy:
Cache File Strategy
-------------------
Each ``ImageCacheFile`` has a cache file strategy, which abstracts away when
image is actually generated. It can implement the following three methods:
* ``on_content_required`` - called by ``ImageCacheFile`` when it requires the
contents of the generated image. For example, when you call ``read()`` or
try to access information contained in the file.
* ``on_existence_required`` - called by ``ImageCacheFile`` when it requires the
generated image to exist but may not be concerned with its contents. For
example, when you access its ``url`` or ``path`` attribute.
* ``on_source_saved`` - called when the source of a spec is saved
The default strategy only defines the first two of these, as follows:
.. code-block:: python
class JustInTime(object):
def on_content_required(self, file):
file.generate()
def on_existence_required(self, file):
file.generate()
.. _cache-file-backend:
Cache File Backend
------------------
The ``generate`` method on the ``ImageCacheFile`` is further delegated to the
cache file backend, which abstracts away how an image is generated.
The cache file backend defaults to the setting
``IMAGEKIT_DEFAULT_CACHEFILE_BACKEND`` and can be set explicitly on a spec with
the ``cachefile_backend`` attribute.
The default works like this:
* Checks the file storage to see if a file exists
* If not, caches that information for 5 seconds
* If it does, caches that information in the ``IMAGEKIT_CACHE_BACKEND``
If file doesn't exist, generates it immediately and synchronously
That pretty much covers the architecture of the caching layer, and its default
behavior. I like the default behavior. When will an image be regenerated?
Whenever it needs to be! When will your storage backend get hit? Depending on
your ``IMAGEKIT_CACHE_BACKEND`` settings, as little as twice per file (once for the
existence check and once to save the generated file). What if you want to change
a spec? The generated file name (which is used as part of the cache keys) vary
with the source file name and spec attributes, so if you change any of those, a
new file will be generated. The default behavior is easy!
.. note::
Like regular Django ImageFields, IK doesn't currently cache width and height
values, so accessing those will always result in a read. That will probably
change soon though.
Optimizing
==========
There are several ways to improve the performance (reduce I/O operations) of
ImageKit. Each has its own pros and cons.
Caching Data About Generated Files
----------------------------------
Generally, once a file is generated, you will never be removing it, so by
default ImageKit will use default cache to cache the state of generated
files "forever" (or only 5 minutes when ``DEBUG = True``).
The time for which ImageKit will cache state is configured with
``IMAGEKIT_CACHE_TIMEOUT``. If set to ``None`` this means "never expire"
(default when ``DEBUG = False``). You can reduce this timeout if you want
or set it to some numeric value in seconds if your cache backend behaves
differently and for example do not cache values if timeout is ``None``.
If you clear your cache durring deployment or some other reason probably
you do not want to lose the cache for generated images especcialy if you
are using some slow remote storage (like Amazon S3). Then you can configure
separate cache (for example redis) in your ``CACHES`` config and tell ImageKit
to use it instead of the default cache by setting ``IMAGEKIT_CACHE_BACKEND``.
Pre-Generating Images
---------------------
The default cache file backend generates images immediately and synchronously.
If you don't do anything special, that will be when they are first requested—as
part of request-response cycle. This means that the first visitor to your page
will have to wait for the file to be created before they see any HTML.
This can be mitigated, though, by simply generating the images ahead of time, by
running the ``generateimages`` management command.
.. note::
If using with template tags, be sure to read :ref:`source-groups`.
Reducing Cache Backend Round Trips
----------------------------------
When rendering pages with many images, ImageKit performs one cache lookup per image
to check the cachefile state (so a page with 50 images can cause 50 cache round
trips). This can become a major request latency problem, and is highly sensitive to
the network latency to the cache.
To reduce this overhead, ImageKit provides a set of APIs that can be used to prefetch
cache states into a request-local state cache using a single ``cache.get_many()``
call:
.. code-block:: python
from imagekit.cachefiles.state import use_cachefile_state_cache, prefetch_cachefile_states
def gallery(request):
images = list(Image.objects.filter(...)[:50])
# Construct ImageCacheFile objects. (No cache request yet)
thumbs = [img.thumbnail for img in images]
# Create a request-local mapping and prefetch states
state_cache = {}
with use_cachefile_state_cache(state_cache):
prefetch_cachefile_states(thumbs, state_cache=state_cache)
return render(request, "gallery.html", {"images": images})
How it works:
1. ``use_cachefile_state_cache()`` activates a request-local in-memory cache
for the duration of the context (a plain dict is typically used).
2. ``prefetch_cachefile_states()`` fetches all cache file states in a single
``cache.get_many()`` call and stores them in the state cache.
3. During template rendering, ``ImageCacheFile.url`` accesses check the state
cache first before calling ``cache.get()``, so prefetched keys incur no
additional cache round trips.
Deferring Image Generation
--------------------------
As mentioned above, image generation is normally done synchronously. through
the default cache file backend. However, you can also take advantage of
deferred generation. In order to do this, you'll need to do two things:
1) install `celery`__ (or `django-celery`__ if you are bound to Celery<3.1)
2) tell ImageKit to use the async cachefile backend.
To do this for all specs, set the ``IMAGEKIT_DEFAULT_CACHEFILE_BACKEND`` in
your settings
.. code-block:: python
IMAGEKIT_DEFAULT_CACHEFILE_BACKEND = 'imagekit.cachefiles.backends.Async'
Images will now be generated asynchronously. But watch out! Asynchrounous
generation means you'll have to account for images that haven't been generated
yet. You can do this by checking the truthiness of your files; if an image
hasn't been generated, it will be falsy:
.. code-block:: html
{% if not profile.avatar_thumbnail %}
{% else %}
{% endif %}
Or, in Python:
.. code-block:: python
profile = Profile.objects.all()[0]
if profile.avatar_thumbnail:
url = profile.avatar_thumbnail.url
else:
url = '/path/to/placeholder.jpg'
.. note::
If you are using an "async" backend in combination with the "optimistic"
cache file strategy (see `Removing Safeguards`_ below), checking for
truthiness as described above will not work. The "optimistic" backend is
very optimistic so to say, and removes the check. Create and use the
following strategy to a) have images only created on save, and b) retain
the ability to check whether the images have already been created::
class ImagekitOnSaveStrategy(object):
def on_source_saved(self, file):
file.generate()
.. note::
If you use custom storage backend for some specs,
(storage passed to the field different than configured one)
it's required the storage to be pickleable
__ https://pypi.python.org/pypi/django-celery
__ http://www.celeryproject.org
Removing Safeguards
-------------------
Even with pre-generating images, ImageKit will still try to ensure that your
image exists when you access it by default. This is for your benefit: if you
forget to generate your images, ImageKit will see that and generate it for you.
If the state of the file is cached (see above), this is a pretty cheap
operation. However, if the state isn't cached, ImageKit will need to query the
storage backend.
For those who aren't willing to accept that cost (and who never want ImageKit
to generate images in the request-response cycle), there's the "optimistic"
cache file strategy. This strategy only generates a new image when a spec's
source image is created or changed. Unlike with the "just in time" strategy,
accessing the file won't cause it to be generated, ImageKit will just assume
that it already exists.
To use this cache file strategy for all specs, set the
``IMAGEKIT_DEFAULT_CACHEFILE_STRATEGY`` in your settings:
.. code-block:: python
IMAGEKIT_DEFAULT_CACHEFILE_STRATEGY = 'imagekit.cachefiles.strategies.Optimistic'
If you have specs that :ref:`change based on attributes of the source
`, that's not going to cut it, though; the file will also need to
be generated when those attributes change. Likewise, image generators that don't
have sources (i.e. generators that aren't specs) won't cause files to be
generated automatically when using the optimistic strategy. (ImageKit can't know
when those need to be generated, if not on access.) In both cases, you'll have
to trigger the file generation yourself—either by generating the file in code
when necessary, or by periodically running the ``generateimages`` management
command. Luckily, ImageKit makes this pretty easy:
.. code-block:: python
from imagekit.cachefiles import LazyImageCacheFile
file = LazyImageCacheFile('myapp:profile:avatar_thumbnail', source=source_file)
file.generate()
One final situation in which images won't be generated automatically when using
the optimistic strategy is when you use a spec with a source that hasn't been
registered with it. Unlike the previous two examples, this situation cannot be
rectified by running the ``generateimages`` management command, for the simple
reason that the command has no way of knowing it needs to generate a file for
that spec from that source. Typically, this situation would arise when using the
template tags. Unlike ImageSpecFields, which automatically register all the
possible source images with the spec you define, the template tags
("generateimage" and "thumbnail") let you use any spec with any source.
Therefore, in order to generate the appropriate files using the
``generateimages`` management command, you'll need to first register a source
group that represents all of the sources you wish to use with the corresponding
specs. See :ref:`source-groups` for more information.
matthewwithanm-django-imagekit-26cdc9d/docs/conf.py 0000664 0000000 0000000 00000020270 15252340250 0022531 0 ustar 00root root 0000000 0000000 #
# ImageKit documentation build configuration file, created by
# sphinx-quickstart on Sun Sep 25 17:05:55 2011.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
import re
import sys
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('..'))
sys.path.append(os.path.abspath('_themes'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.settings'
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'ImageKit'
copyright = '2011, Justin Driscoll, Bryan Veloso, Greg Newman, Chris Drackett, Matthew Tretter, Venelin Stoykov & contributors'
pkgmeta = {}
pkgmeta_file = os.path.join(os.path.dirname(__file__), '..', 'imagekit', 'pkgmeta.py')
with open(pkgmeta_file, 'r') as f:
exec(f.read(), pkgmeta)
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = re.match(r'\d+\.\d+', pkgmeta['__version__']).group()
# The full version, including alpha/beta/rc tags.
release = pkgmeta['__version__']
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'kr'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['_themes']
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
html_show_copyright = False
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'ImageKitdoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'ImageKit.tex', 'ImageKit Documentation',
'Justin Driscoll, Bryan Veloso, Greg Newman, Chris Drackett \\& Matthew Tretter', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'imagekit', 'ImageKit Documentation',
['Justin Driscoll, Bryan Veloso, Greg Newman, Chris Drackett & Matthew Tretter'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'ImageKit', 'ImageKit Documentation', 'Justin Driscoll, Bryan Veloso, Greg Newman, Chris Drackett & Matthew Tretter',
'ImageKit', 'One line description of project.', 'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
autoclass_content = 'both'
matthewwithanm-django-imagekit-26cdc9d/docs/configuration.rst 0000664 0000000 0000000 00000006511 15252340250 0024635 0 ustar 00root root 0000000 0000000 .. _settings:
Configuration
=============
Settings
--------
.. currentmodule:: django.conf.settings
.. attribute:: IMAGEKIT_DEFAULT_THUMBNAIL_FORMAT
:default: ``None``
The output format of the images generated by the ``thumbnail`` template tag.
.. attribute:: IMAGEKIT_CACHEFILE_DIR
:default: ``'CACHE/images'``
The directory to which image files will be cached.
.. attribute:: IMAGEKIT_DEFAULT_THUMBNAIL_SRCSET_SCALES
:default: ``None``
A list of scale factors, for example ``[2, 3]``. If specified, every
```` generated by the ``thumbnail`` template tag will have a ``srcset``
attribute with the given scales. To prevent this, set ``srcset=None``.
.. attribute:: IMAGEKIT_DEFAULT_FILE_STORAGE
:default: ``None``
Starting with Django 4.2, if you defined ``settings.STORAGES``:
the Django storage backend alias to retrieve the storage instance defined
in your settings, as described in the `Django file storage documentation`_.
If no value is provided for ``IMAGEKIT_DEFAULT_FILE_STORAGE``,
and none is specified by the spec definition, the ``default`` file storage
will be used.
Before Django 4.2, or if ``settings.STORAGES`` is not defined:
The qualified class name of a Django storage backend to use to save the
cached images. If no value is provided for ``IMAGEKIT_DEFAULT_FILE_STORAGE``,
and none is specified by the spec definition, `your default file storage`__
will be used.
.. _`Django file storage documentation`: https://docs.djangoproject.com/en/dev/ref/files/storage/
.. attribute:: IMAGEKIT_DEFAULT_CACHEFILE_BACKEND
:default: ``'imagekit.cachefiles.backends.Simple'``
Specifies the class that will be used to validate cached image files.
.. attribute:: IMAGEKIT_DEFAULT_CACHEFILE_STRATEGY
:default: ``'imagekit.cachefiles.strategies.JustInTime'``
The class responsible for specifying how and when cache files are
generated.
.. attribute:: IMAGEKIT_CACHE_BACKEND
:default: ``'default'``
The Django cache backend alias to retrieve the shared cache instance defined
in your settings, as described in the `Django cache section`_.
The cache is then used to store information like the state of cached
images (i.e. validated or not).
.. _`Django cache section`: https://docs.djangoproject.com/en/dev/topics/cache/#accessing-the-cache
.. attribute:: IMAGEKIT_CACHE_TIMEOUT
:default: ``None``
Use when you need to override the timeout used to cache file state.
By default it is "cache forever".
It's highly recommended that you use a very high timeout.
.. attribute:: IMAGEKIT_CACHE_PREFIX
:default: ``'imagekit:'``
A cache prefix to be used when values are stored in ``IMAGEKIT_CACHE_BACKEND``
.. attribute:: IMAGEKIT_CACHEFILE_NAMER
:default: ``'imagekit.cachefiles.namers.hash'``
A function responsible for generating file names for non-spec cache files.
.. attribute:: IMAGEKIT_SPEC_CACHEFILE_NAMER
:default: ``'imagekit.cachefiles.namers.source_name_as_path'``
A function responsible for generating file names for cache files that
correspond to image specs. Since you will likely want to base the name of
your cache files on the name of the source, this extra setting is provided.
__ https://docs.djangoproject.com/en/dev/ref/settings/#default-file-storage
matthewwithanm-django-imagekit-26cdc9d/docs/index.rst 0000664 0000000 0000000 00000000415 15252340250 0023072 0 ustar 00root root 0000000 0000000 .. include:: ../README.rst
Authors
=======
.. include:: ../AUTHORS
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. toctree::
:glob:
:maxdepth: 2
configuration
advanced_usage
caching
upgrading
matthewwithanm-django-imagekit-26cdc9d/docs/make.bat 0000664 0000000 0000000 00000011753 15252340250 0022645 0 ustar 00root root 0000000 0000000 @ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^` where ^ is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\ImageKit.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\ImageKit.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
:end
matthewwithanm-django-imagekit-26cdc9d/docs/upgrading.rst 0000664 0000000 0000000 00000010460 15252340250 0023744 0 ustar 00root root 0000000 0000000 Upgrading from 2.x
==================
ImageKit 3.0 introduces new APIs and tools that augment, improve, and in some
cases entirely replace old IK workflows. Below, you'll find some useful guides
for migrating your ImageKit 2.0 apps over to the shiny new IK3.
Model Specs
-----------
IK3 is chock full of new features and better tools for even the most
sophisticated use cases. Despite this, not too much has changed when it
comes to the most common of use cases: processing an ``ImageField`` on a model.
In IK2, you may have used an ``ImageSpecField`` on a model to process an
existing ``ImageField``:
.. code-block:: python
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(image_field='avatar',
processors=[ResizeToFill(100, 50)],
format='JPEG',
options={'quality': 60})
In IK3, things look much the same:
.. code-block:: python
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
processors=[ResizeToFill(100, 50)],
format='JPEG',
options={'quality': 60})
The major difference is that ``ImageSpecField`` no longer takes an
``image_field`` kwarg. Instead, you define a ``source``.
Image Cache Backends
--------------------
In IK2, you could gain some control over how your cached images were generated
by providing an ``image_cache_backend``:
.. code-block:: python
class Photo(models.Model):
...
thumbnail = ImageSpecField(..., image_cache_backend=MyImageCacheBackend())
This gave you great control over *how* your images are generated and stored,
but it could be difficult to control *when* they were generated and stored.
IK3 retains the image cache backend concept (now called cache file backends),
but separates the 'when' control out to cache file strategies:
.. code-block:: python
class Photo(models.Model):
...
thumbnail = ImageSpecField(...,
cachefile_backend=MyCacheFileBackend(),
cachefile_strategy=MyCacheFileStrategy())
If you are using the IK2 default image cache backend setting:
.. code-block:: python
IMAGEKIT_DEFAULT_IMAGE_CACHE_BACKEND = 'path.to.MyImageCacheBackend'
IK3 provides analogous settings for cache file backends and strategies:
.. code-block:: python
IMAGEKIT_DEFAULT_CACHEFILE_BACKEND = 'path.to.MyCacheFileBackend'
IMAGEKIT_DEFAULT_CACHEFILE_STRATEGY = 'path.to.MyCacheFileStrategy'
See the documentation on :ref:`cache file backends ` and :ref:`cache file strategies `
for more details.
Conditional model ``processors``
--------------------------------
In IK2, an ``ImageSpecField`` could take a ``processors`` callable instead of
an iterable, which allowed processing decisions to made based on other
properties of the model. IK3 does away with this feature for consistency's sake
(if one kwarg could be callable, why not all?), but provides a much more robust
solution: the custom ``spec``. See the :doc:`advanced usage ` documentation for more.
Conditonal ``cache_to`` file names
----------------------------------
IK2 provided a means of specifying custom cache file names for your
image specs by passing a ``cache_to`` callable to an ``ImageSpecField``.
IK3 does away with this feature, again, for consistency.
There is a way to achieve custom file names by overriding your spec's
``cachefile_name``, but it is not recommended, as the spec's default
behavior is to hash the combination of ``source``, ``processors``, ``format``,
and other spec options to ensure that changes to the spec always result in
unique file names. See the documentation on :ref:`specs` for more.
Processors have moved to PILKit
-------------------------------
Processors have moved to a separate project: `PILKit`_. You should not have to
make any changes to an IK2 project to use PILKit--it should be installed with
IK3, and importing from ``imagekit.processors`` will still work.
.. _`PILKit`: https://github.com/matthewwithanm/pilkit
matthewwithanm-django-imagekit-26cdc9d/imagekit/ 0000775 0000000 0000000 00000000000 15252340250 0022073 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/__init__.py 0000664 0000000 0000000 00000000426 15252340250 0024206 0 ustar 00root root 0000000 0000000 from . import conf, generatorlibrary
from .pkgmeta import *
from .registry import register, unregister
from .specs import ImageSpec
__all__ = [
'ImageSpec', 'conf', 'generatorlibrary', 'register', 'unregister',
'__title__', '__author__', '__version__', '__license__'
]
matthewwithanm-django-imagekit-26cdc9d/imagekit/admin.py 0000664 0000000 0000000 00000002453 15252340250 0023541 0 ustar 00root root 0000000 0000000 from django.template.loader import render_to_string
from django.utils.translation import gettext_lazy as _
class AdminThumbnail:
"""
A convenience utility for adding thumbnails to Django's admin change list.
"""
short_description = _('Thumbnail')
allow_tags = True
def __init__(self, image_field, template=None):
"""
:param image_field: The name of the ImageField or ImageSpecField on the
model to use for the thumbnail.
:param template: The template with which to render the thumbnail
"""
self.image_field = image_field
self.template = template
def __call__(self, obj):
if callable(self.image_field):
thumbnail = self.image_field(obj)
else:
try:
thumbnail = getattr(obj, self.image_field)
except AttributeError:
raise Exception('The property %s is not defined on %s.' %
(self.image_field, obj.__class__.__name__))
original_image = getattr(thumbnail, 'source', None) or thumbnail
template = self.template or 'imagekit/admin/thumbnail.html'
return render_to_string(template, {
'model': obj,
'thumbnail': thumbnail,
'original_image': original_image,
})
matthewwithanm-django-imagekit-26cdc9d/imagekit/cachefiles/ 0000775 0000000 0000000 00000000000 15252340250 0024161 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/cachefiles/__init__.py 0000664 0000000 0000000 00000016253 15252340250 0026301 0 ustar 00root root 0000000 0000000 import os.path
from copy import copy
from django.conf import settings
from django.core.files import File
from django.core.files.images import ImageFile
from django.utils.encoding import smart_str
from django.utils.functional import SimpleLazyObject
from ..files import BaseIKFile
from ..registry import generator_registry
from ..signals import content_required, existence_required
from ..utils import (
generate, get_by_qname, get_logger, get_singleton, get_storage
)
class ImageCacheFile(BaseIKFile, ImageFile):
"""
A file that represents the result of a generator. Creating an instance of
this class is not enough to trigger the generation of the file. In fact,
one of the main points of this class is to allow the creation of the file
to be deferred until the time that the cache file strategy requires it.
"""
def __init__(self, generator, name=None, storage=None, cachefile_backend=None, cachefile_strategy=None):
"""
:param generator: The object responsible for generating a new image.
:param name: The filename
:param storage: A Django storage object, or a callable which returns a
storage object that will be used to save the file.
:param cachefile_backend: The object responsible for managing the
state of the file.
:param cachefile_strategy: The object responsible for handling events
for this file.
"""
self.generator = generator
if not name:
try:
name = generator.cachefile_name
except AttributeError:
fn = get_by_qname(settings.IMAGEKIT_CACHEFILE_NAMER, 'namer')
name = fn(generator)
self.name = name
storage = (callable(storage) and storage()) or storage or \
getattr(generator, 'cachefile_storage', None) or get_storage()
self.cachefile_backend = (
cachefile_backend
or getattr(generator, 'cachefile_backend', None)
or get_singleton(settings.IMAGEKIT_DEFAULT_CACHEFILE_BACKEND,
'cache file backend'))
self.cachefile_strategy = (
cachefile_strategy
or getattr(generator, 'cachefile_strategy', None)
or get_singleton(settings.IMAGEKIT_DEFAULT_CACHEFILE_STRATEGY,
'cache file strategy')
)
super().__init__(storage=storage)
def _require_file(self):
if getattr(self, '_file', None) is None:
content_required.send(sender=self, file=self)
self._file = self.storage.open(self.name, 'rb')
# The ``path`` and ``url`` properties are overridden so as to not call
# ``_require_file``, which is only meant to be called when the file object
# will be directly interacted with (e.g. when using ``read()``). These only
# require the file to exist; they do not need its contents to work. This
# distinction gives the user the flexibility to create a cache file
# strategy that assumes the existence of a file, but can still make the file
# available when its contents are required.
def _storage_attr(self, attr):
if getattr(self, '_file', None) is None:
existence_required.send(sender=self, file=self)
fn = getattr(self.storage, attr)
return fn(self.name)
@property
def path(self):
return self._storage_attr('path')
@property
def url(self):
return self._storage_attr('url')
def generate(self, force=False):
"""
Generate the file. If ``force`` is ``True``, the file will be generated
whether the file already exists or not.
"""
if force or getattr(self, '_file', None) is None:
self.cachefile_backend.generate(self, force)
def _generate(self):
# Generate the file
content = generate(self.generator)
actual_name = self.storage.save(self.name, content)
# We're going to reuse the generated file, so we need to reset the pointer.
if not hasattr(content, "seekable") or content.seekable():
content.seek(0)
# Store the generated file. If we don't do this, the next time the
# "file" attribute is accessed, it will result in a call to the storage
# backend (in ``BaseIKFile._get_file``). Since we already have the
# contents of the file, what would the point of that be?
self.file = File(content)
# ``actual_name`` holds the output of ``self.storage.save()`` that
# by default returns filenames with forward slashes, even on windows.
# On the other hand, ``self.name`` holds OS-specific paths results
# from applying path normalizers like ``os.path.normpath()`` in the
# ``namer``. So, the filenames should be normalized before their
# equality checking.
if os.path.normpath(actual_name) != os.path.normpath(self.name):
get_logger().warning(
'The storage backend %s did not save the file with the'
' requested name ("%s") and instead used "%s". This may be'
' because a file already existed with the requested name. If'
' so, you may have meant to call generate() instead of'
' generate(force=True), or there may be a race condition in the'
' file backend %s. The saved file will not be used.',
self.storage,
self.name,
actual_name,
self.cachefile_backend
)
def __bool__(self):
if not self.name:
return False
# Dispatch the existence_required signal before checking to see if the
# file exists. This gives the strategy a chance to create the file.
existence_required.send(sender=self, file=self)
try:
check = self.cachefile_strategy.should_verify_existence(self)
except AttributeError:
# All synchronous backends should have created the file as part of
# `existence_required` if they wanted to.
check = getattr(self.cachefile_backend, 'is_async', False)
return self.cachefile_backend.exists(self) if check else True
def __getstate__(self):
state = copy(self.__dict__)
# file is hidden link to "file" attribute
state.pop('_file', None)
# remove storage from state as some non-FileSystemStorage can't be
# pickled
settings_storage = get_storage()
if state['storage'] == settings_storage:
state.pop('storage')
return state
def __setstate__(self, state):
if 'storage' not in state:
state['storage'] = get_storage()
self.__dict__.update(state)
def __repr__(self):
return smart_str("<%s: %s>" % (
self.__class__.__name__, self if self.name else "None")
)
class LazyImageCacheFile(SimpleLazyObject):
def __init__(self, generator_id, *args, **kwargs):
def setup():
generator = generator_registry.get(generator_id, *args, **kwargs)
return ImageCacheFile(generator)
super().__init__(setup)
def __repr__(self):
return '<%s: %s>' % (self.__class__.__name__, str(self) or 'None')
matthewwithanm-django-imagekit-26cdc9d/imagekit/cachefiles/backends.py 0000664 0000000 0000000 00000016456 15252340250 0026321 0 ustar 00root root 0000000 0000000 import warnings
from copy import copy
from django.conf import settings
from django.core.exceptions import ImproperlyConfigured
from .state import get_active_state_cache
from ..utils import get_cache, get_singleton, sanitize_cache_key
class CacheFileState:
EXISTS = 'exists'
GENERATING = 'generating'
DOES_NOT_EXIST = 'does_not_exist'
def get_default_cachefile_backend():
"""
Get the default file backend.
"""
from django.conf import settings
return get_singleton(settings.IMAGEKIT_DEFAULT_CACHEFILE_BACKEND,
'file backend')
class InvalidFileBackendError(ImproperlyConfigured):
pass
class AbstractCacheFileBackend:
"""
An abstract cache file backend. This isn't used by any internal classes and
is included simply to illustrate the minimum interface of a cache file
backend for users who wish to implement their own.
"""
def generate(self, file, force=False):
raise NotImplementedError
def exists(self, file):
raise NotImplementedError
class CachedFileBackend:
existence_check_timeout = 5
"""
The number of seconds to wait before rechecking to see if the file exists.
If the image is found to exist, that information will be cached using the
timeout specified in your CACHES setting (which should be very high).
However, when the file does not exist, you probably want to check again
in a relatively short amount of time. This attribute allows you to do that.
"""
@property
def cache(self):
if not getattr(self, '_cache', None):
self._cache = get_cache()
return self._cache
def get_key(self, file):
from django.conf import settings
return sanitize_cache_key('%s%s-state' %
(settings.IMAGEKIT_CACHE_PREFIX, file.name))
def get_state(self, file, check_if_unknown=True):
key = self.get_key(file)
# Check request-local state cache first
state_cache = get_active_state_cache()
if state_cache is not None and key in state_cache:
state = state_cache[key]
else:
state = self.cache.get(key)
# Write-through to request-local cache if active
if state_cache is not None:
state_cache[key] = state
if state is None and check_if_unknown:
exists = self._exists(file)
state = CacheFileState.EXISTS if exists else CacheFileState.DOES_NOT_EXIST
self.set_state(file, state)
return state
def set_state(self, file, state):
key = self.get_key(file)
if state == CacheFileState.DOES_NOT_EXIST:
self.cache.set(key, state, self.existence_check_timeout)
else:
self.cache.set(key, state, settings.IMAGEKIT_CACHE_TIMEOUT)
# Write-through to request-local state cache if active
state_cache = get_active_state_cache()
if state_cache is not None:
state_cache[key] = state
def __getstate__(self):
state = copy(self.__dict__)
# Don't include the cache when pickling. It'll be reconstituted based
# on the settings.
state.pop('_cache', None)
return state
def exists(self, file):
return self.get_state(file) == CacheFileState.EXISTS
def generate(self, file, force=False):
raise NotImplementedError
def generate_now(self, file, force=False):
if force or self.get_state(file) not in (CacheFileState.GENERATING, CacheFileState.EXISTS):
self.set_state(file, CacheFileState.GENERATING)
file._generate()
self.set_state(file, CacheFileState.EXISTS)
file.close()
class Simple(CachedFileBackend):
"""
The most basic file backend. The storage is consulted to see if the file
exists. Files are generated synchronously.
"""
def generate(self, file, force=False):
self.generate_now(file, force=force)
def _exists(self, file):
return bool(getattr(file, '_file', None)
or (file.name and file.storage.exists(file.name)))
def _generate_file(backend, file, force=False):
backend.generate_now(file, force=force)
class BaseAsync(Simple):
"""
Base class for cache file backends that generate files asynchronously.
"""
is_async = True
def generate(self, file, force=False):
# Schedule the file for generation, unless we know for sure we don't
# need to. If an already-generated file sneaks through, that's okay;
# ``generate_now`` will catch it. We just want to make sure we don't
# schedule anything we know is unnecessary--but we also don't want to
# force a costly existence check.
state = self.get_state(file, check_if_unknown=False)
if state not in (CacheFileState.GENERATING, CacheFileState.EXISTS):
self.schedule_generation(file, force=force)
def schedule_generation(self, file, force=False):
# overwrite this to have the file generated in the background,
# e. g. in a worker queue.
raise NotImplementedError
try:
from celery import shared_task as task
except ImportError:
pass
else:
_celery_task = task(ignore_result=True, serializer='pickle')(_generate_file)
class Celery(BaseAsync):
"""
A backend that uses Celery to generate the images.
"""
def __init__(self, *args, **kwargs):
try:
import celery # noqa
except ImportError:
raise ImproperlyConfigured('You must install celery to use'
' imagekit.cachefiles.backends.Celery.')
super().__init__(*args, **kwargs)
def schedule_generation(self, file, force=False):
_celery_task.delay(self, file, force=force)
# Stub class to preserve backwards compatibility and issue a warning
class Async(Celery):
def __init__(self, *args, **kwargs):
message = '{path}.Async is deprecated. Use {path}.Celery instead.'
warnings.warn(message.format(path=__name__), DeprecationWarning)
super().__init__(*args, **kwargs)
try:
from django_rq import job
except ImportError:
pass
else:
_rq_job = job('default', result_ttl=0)(_generate_file)
class RQ(BaseAsync):
"""
A backend that uses RQ to generate the images.
"""
def __init__(self, *args, **kwargs):
try:
import django_rq # noqa
except ImportError:
raise ImproperlyConfigured('You must install django-rq to use'
' imagekit.cachefiles.backends.RQ.')
super().__init__(*args, **kwargs)
def schedule_generation(self, file, force=False):
_rq_job.delay(self, file, force=force)
try:
from dramatiq import actor
except ImportError:
pass
else:
_dramatiq_actor = actor()(_generate_file)
class Dramatiq(BaseAsync):
"""
A backend that uses Dramatiq to generate the images.
"""
def __init__(self, *args, **kwargs):
try:
import dramatiq # noqa
except ImportError:
raise ImproperlyConfigured('You must install django-dramatiq to use'
' imagekit.cachefiles.backends.Dramatiq.')
super().__init__(*args, **kwargs)
def schedule_generation(self, file, force=False):
_dramatiq_actor.send(self, file, force=force)
matthewwithanm-django-imagekit-26cdc9d/imagekit/cachefiles/namers.py 0000664 0000000 0000000 00000006115 15252340250 0026023 0 ustar 00root root 0000000 0000000 """
Functions responsible for returning filenames for the given image generator.
Users are free to define their own functions; these are just some some sensible
choices.
"""
import os
from django.conf import settings
from ..utils import format_to_extension, suggest_extension
def source_name_as_path(generator):
"""
A namer that, given the following source file name::
photos/thumbnails/bulldog.jpg
will generate a name like this::
/path/to/generated/images/photos/thumbnails/bulldog/5ff3233527c5ac3e4b596343b440ff67.jpg
where "/path/to/generated/images/" is the value specified by the
``IMAGEKIT_CACHEFILE_DIR`` setting.
"""
source_filename = getattr(generator.source, 'name', None)
if source_filename is None or os.path.isabs(source_filename):
# Generally, we put the file right in the cache file directory.
dir = settings.IMAGEKIT_CACHEFILE_DIR
else:
# For source files with relative names (like Django media files),
# use the source's name to create the new filename.
dir = os.path.join(settings.IMAGEKIT_CACHEFILE_DIR,
os.path.splitext(source_filename)[0])
ext = suggest_extension(source_filename or '', generator.format)
return os.path.normpath(os.path.join(dir,
'%s%s' % (generator.get_hash(), ext)))
def source_name_dot_hash(generator):
"""
A namer that, given the following source file name::
photos/thumbnails/bulldog.jpg
will generate a name like this::
/path/to/generated/images/photos/thumbnails/bulldog.5ff3233527c5.jpg
where "/path/to/generated/images/" is the value specified by the
``IMAGEKIT_CACHEFILE_DIR`` setting.
"""
source_filename = getattr(generator.source, 'name', None)
if source_filename is None or os.path.isabs(source_filename):
# Generally, we put the file right in the cache file directory.
dir = settings.IMAGEKIT_CACHEFILE_DIR
else:
# For source files with relative names (like Django media files),
# use the source's name to create the new filename.
dir = os.path.join(settings.IMAGEKIT_CACHEFILE_DIR,
os.path.dirname(source_filename))
ext = suggest_extension(source_filename or '', generator.format)
basename = os.path.basename(source_filename)
return os.path.normpath(os.path.join(dir, '%s.%s%s' % (
os.path.splitext(basename)[0], generator.get_hash()[:12], ext)))
def hash(generator):
"""
A namer that, given the following source file name::
photos/thumbnails/bulldog.jpg
will generate a name like this::
/path/to/generated/images/5ff3233527c5ac3e4b596343b440ff67.jpg
where "/path/to/generated/images/" is the value specified by the
``IMAGEKIT_CACHEFILE_DIR`` setting.
"""
format = getattr(generator, 'format', None)
ext = format_to_extension(format) if format else ''
return os.path.normpath(os.path.join(settings.IMAGEKIT_CACHEFILE_DIR,
'%s%s' % (generator.get_hash(), ext)))
matthewwithanm-django-imagekit-26cdc9d/imagekit/cachefiles/state.py 0000664 0000000 0000000 00000007342 15252340250 0025661 0 ustar 00root root 0000000 0000000 """
Request-local state cache for ImageKit cachefiles to reduce cache lookups.
This module provides an optional request-local in-memory state cache that can
be used to batch prefetch cache file states, reducing round trips to the Django
cache backend.
"""
from contextlib import contextmanager
from contextvars import ContextVar
# ContextVar for storing the active state cache (a dict-like mapping) for the
# current execution context.
_active_state_cache: ContextVar = ContextVar('_active_state_cache', default=None)
@contextmanager
def use_cachefile_state_cache(state_cache=None):
"""
Context manager to activate a request-local state cache.
Usage::
from imagekit.cachefiles.state import use_cachefile_state_cache, prefetch_cachefile_states
state_cache = {}
with use_cachefile_state_cache(state_cache):
prefetch_cachefile_states(thumbs, state_cache=state_cache)
# ... render template with thumbs ...
:param state_cache: A dict-like mapping to use as the cache.
If None, a new empty dict will be created.
"""
if state_cache is None:
state_cache = {}
token = _active_state_cache.set(state_cache)
try:
yield state_cache
finally:
_active_state_cache.reset(token)
def get_active_state_cache():
"""
Get the active state cache for the current context, if any.
:return: The active dict-like mapping, or None if no cache is active.
"""
return _active_state_cache.get(None)
def prefetch_cachefile_states(files, *, state_cache=None, cache=None):
"""
Prefetch cache file states using cache.get_many().
This function computes cache keys for the given files and fetches their
states in as few cache.get_many() calls as possible. The results are stored
in the provided state_cache (or the active request-local cache if not
provided).
Example usage in a view::
from imagekit.cachefiles.state import use_cachefile_state_cache, prefetch_cachefile_states
def gallery(request):
images = list(Image.objects.filter(...))
thumbs = [img.thumbnail for img in images]
state_cache = {}
with use_cachefile_state_cache(state_cache):
prefetch_cachefile_states(thumbs, state_cache=state_cache)
return render(request, "gallery.html", {"images": images})
:param files: Iterable of ImageCacheFile objects to prefetch states for.
:param state_cache: Optional dict-like mapping to populate. If None,
the active request-local cache will be used (if any).
:param cache: Optional Django cache instance. If provided, all lookups
will use this cache. If None, each file's cachefile backend will
determine which cache to read from.
"""
from .backends import CachedFileBackend
if state_cache is None:
state_cache = get_active_state_cache()
if state_cache is None:
return
# Group keys by the Django cache object used for the lookup.
keys_by_cache = {}
for f in files:
backend = getattr(f, 'cachefile_backend', None)
if not isinstance(backend, CachedFileBackend):
continue
key = backend.get_key(f)
backend_cache = cache or backend.cache
keys_by_cache.setdefault(backend_cache, set()).add(key)
if not keys_by_cache:
return
for backend_cache, keys in keys_by_cache.items():
states = backend_cache.get_many(keys)
# Store hits in state_cache
for key, state in states.items():
state_cache[key] = state
# Also record misses so later checks don't fall back to cache.get()
for key in keys:
if key not in states:
state_cache[key] = None
matthewwithanm-django-imagekit-26cdc9d/imagekit/cachefiles/strategies.py 0000664 0000000 0000000 00000002034 15252340250 0026704 0 ustar 00root root 0000000 0000000 from ..utils import get_singleton
class JustInTime:
"""
A strategy that ensures the file exists right before it's needed.
"""
def on_existence_required(self, file):
file.generate()
def on_content_required(self, file):
file.generate()
class Optimistic:
"""
A strategy that acts immediately when the source file changes and assumes
that the cache files will not be removed (i.e. it doesn't ensure the
cache file exists when it's accessed).
"""
def on_source_saved(self, file):
file.generate()
def should_verify_existence(self, file):
return False
class DictStrategy:
def __init__(self, callbacks):
for k, v in callbacks.items():
setattr(self, k, v)
def load_strategy(strategy):
if isinstance(strategy, str):
strategy = get_singleton(strategy, 'cache file strategy')
elif isinstance(strategy, dict):
strategy = DictStrategy(strategy)
elif callable(strategy):
strategy = strategy()
return strategy
matthewwithanm-django-imagekit-26cdc9d/imagekit/conf.py 0000664 0000000 0000000 00000003057 15252340250 0023377 0 ustar 00root root 0000000 0000000 from appconf import AppConf
from django.conf import settings
from django.core.exceptions import ImproperlyConfigured
class ImageKitConf(AppConf):
CACHEFILE_NAMER = 'imagekit.cachefiles.namers.hash'
SPEC_CACHEFILE_NAMER = 'imagekit.cachefiles.namers.source_name_as_path'
CACHEFILE_DIR = 'CACHE/images'
DEFAULT_CACHEFILE_BACKEND = 'imagekit.cachefiles.backends.Simple'
DEFAULT_CACHEFILE_STRATEGY = 'imagekit.cachefiles.strategies.JustInTime'
DEFAULT_FILE_STORAGE = None
CACHE_BACKEND = None
CACHE_PREFIX = 'imagekit:'
CACHE_TIMEOUT = None
USE_MEMCACHED_SAFE_CACHE_KEY = True
def configure_cache_backend(self, value):
if value is None:
from django.core.cache import DEFAULT_CACHE_ALIAS
return DEFAULT_CACHE_ALIAS
if value not in settings.CACHES:
raise ImproperlyConfigured("{0} is not present in settings.CACHES".format(value))
return value
def configure_cache_timeout(self, value):
if value is None and settings.DEBUG:
# If value is not configured and is DEBUG set it to 5 minutes
return 300
# Otherwise leave it as is. If it is None then valies will never expire
return value
def configure_default_file_storage(self, value):
if value is None:
try:
from django.conf import DEFAULT_STORAGE_ALIAS
except ImportError: # Django < 4.2
return settings.DEFAULT_FILE_STORAGE
else:
return DEFAULT_STORAGE_ALIAS
return value
matthewwithanm-django-imagekit-26cdc9d/imagekit/exceptions.py 0000664 0000000 0000000 00000000602 15252340250 0024624 0 ustar 00root root 0000000 0000000 from pilkit.exceptions import UnknownExtension, UnknownFormat
class AlreadyRegistered(Exception):
pass
class NotRegistered(Exception):
pass
class MissingGeneratorId(Exception):
pass
class MissingSource(ValueError):
silent_variable_failure = True
# Aliases for backwards compatibility
UnknownExtensionError = UnknownExtension
UnknownFormatError = UnknownFormat
matthewwithanm-django-imagekit-26cdc9d/imagekit/files.py 0000664 0000000 0000000 00000005632 15252340250 0023555 0 ustar 00root root 0000000 0000000 import os
from django.core.files.base import ContentFile, File
from .utils import extension_to_mimetype, format_to_mimetype
class BaseIKFile(File):
"""
This class contains all of the methods we need from
django.db.models.fields.files.FieldFile, but with the model stuff ripped
out. It's only extended by one class, but we keep it separate for
organizational reasons.
"""
def __init__(self, storage):
self.storage = storage
def _require_file(self):
if not self:
raise ValueError()
def _get_file(self):
self._require_file()
if not hasattr(self, '_file') or self._file is None:
self._file = self.storage.open(self.name, 'rb')
return self._file
def _set_file(self, file):
self._file = file
def _del_file(self):
del self._file
file = property(_get_file, _set_file, _del_file)
def _get_path(self):
self._require_file()
return self.storage.path(self.name)
path = property(_get_path)
def _get_url(self):
self._require_file()
return self.storage.url(self.name)
url = property(_get_url)
def _get_size(self):
self._require_file()
if not getattr(self, '_committed', False):
return self.file.size
return self.storage.size(self.name)
size = property(_get_size)
def open(self, mode='rb'):
self._require_file()
try:
self.file.open(mode)
except ValueError:
# if the underlying file can't be reopened
# then we will use the storage to try to open it again
if self.file.closed:
# clear cached file instance
del self.file
# Because file is a property we can acces it after
# we deleted it
return self.file.open(mode)
raise
def _get_closed(self):
file = getattr(self, '_file', None)
return file is None or file.closed
closed = property(_get_closed)
def close(self):
file = getattr(self, '_file', None)
if file is not None:
file.close()
class IKContentFile(ContentFile):
"""
Wraps a ContentFile in a file-like object with a filename and a
content_type. A PIL image format can be optionally be provided as a content
type hint.
"""
def __init__(self, filename, content, format=None):
self.file = ContentFile(content)
self.file.name = filename
mimetype = getattr(self.file, 'content_type', None)
if format and not mimetype:
mimetype = format_to_mimetype(format)
if not mimetype:
ext = os.path.splitext(filename or '')[1]
mimetype = extension_to_mimetype(ext)
self.file.content_type = mimetype
@property
def name(self):
return self.file.name
def __str__(self):
return str(self.file.name or '')
matthewwithanm-django-imagekit-26cdc9d/imagekit/forms/ 0000775 0000000 0000000 00000000000 15252340250 0023221 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/forms/__init__.py 0000664 0000000 0000000 00000000070 15252340250 0025327 0 ustar 00root root 0000000 0000000 # flake8: noqa
from .fields import ProcessedImageField
matthewwithanm-django-imagekit-26cdc9d/imagekit/forms/fields.py 0000664 0000000 0000000 00000002362 15252340250 0025044 0 ustar 00root root 0000000 0000000 from django.forms import ImageField
from ..specs import SpecHost
from ..utils import generate
class ProcessedImageField(ImageField, SpecHost):
def __init__(self, processors=None, format=None, options=None,
autoconvert=True, spec_id=None, spec=None, *args, **kwargs):
if spec_id is None:
# Unlike model fields, form fields are never told their field name.
# (Model fields are done so via `contribute_to_class()`.) Therefore
# we can't really generate a good spec id automatically.
raise TypeError('You must provide a spec_id')
SpecHost.__init__(self, processors=processors, format=format,
options=options, autoconvert=autoconvert, spec=spec,
spec_id=spec_id)
super().__init__(*args, **kwargs)
def clean(self, data, initial=None):
data = super().clean(data, initial)
if data and data != initial:
spec = self.get_spec(source=data)
f = generate(spec)
# Name is required in Django 1.4. When we drop support for it
# then we can directly return the result from `generate(spec)`
f.name = data.name
return f
return data
matthewwithanm-django-imagekit-26cdc9d/imagekit/generatorlibrary.py 0000664 0000000 0000000 00000001232 15252340250 0026016 0 ustar 00root root 0000000 0000000 from .processors import Thumbnail as ThumbnailProcessor
from .registry import register
from .specs import ImageSpec
from django.conf import settings
default_thumbnail_format = getattr(settings, 'IMAGEKIT_DEFAULT_THUMBNAIL_FORMAT', None)
class Thumbnail(ImageSpec):
def __init__(self, width=None, height=None, anchor=None, crop=None, upscale=None, format=default_thumbnail_format, **kwargs):
self.processors = [ThumbnailProcessor(width, height, anchor=anchor,
crop=crop, upscale=upscale)]
super().__init__(**kwargs)
self.format = format
register.generator('imagekit:thumbnail', Thumbnail)
matthewwithanm-django-imagekit-26cdc9d/imagekit/hashers.py 0000664 0000000 0000000 00000001701 15252340250 0024101 0 ustar 00root root 0000000 0000000 import sys
from copy import copy
from hashlib import md5
from io import BytesIO
from pickle import DICT, MARK, _Pickler
class CanonicalizingPickler(_Pickler):
dispatch = copy(_Pickler.dispatch)
def save_set(self, obj):
rv = obj.__reduce_ex__(0)
rv = (rv[0], (sorted(rv[1][0]),), rv[2])
self.save_reduce(obj=obj, *rv)
dispatch[set] = save_set
if sys.version_info[:2] >= (3, 14):
def save_dict(self, obj):
write = self.write
write(MARK + DICT)
self.memoize(obj)
self._batch_setitems(sorted(obj.items()), obj)
else:
def save_dict(self, obj):
write = self.write
write(MARK + DICT)
self.memoize(obj)
self._batch_setitems(sorted(obj.items()))
dispatch[dict] = save_dict
def pickle(obj):
file = BytesIO()
CanonicalizingPickler(file, 0).dump(obj)
return md5(file.getvalue()).hexdigest()
matthewwithanm-django-imagekit-26cdc9d/imagekit/management/ 0000775 0000000 0000000 00000000000 15252340250 0024207 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/management/__init__.py 0000664 0000000 0000000 00000000000 15252340250 0026306 0 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/management/commands/ 0000775 0000000 0000000 00000000000 15252340250 0026010 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/management/commands/__init__.py 0000664 0000000 0000000 00000000000 15252340250 0030107 0 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/management/commands/generateimages.py 0000664 0000000 0000000 00000004333 15252340250 0031345 0 ustar 00root root 0000000 0000000 import re
from django.core.management.base import BaseCommand
from ...exceptions import MissingSource
from ...registry import cachefile_registry, generator_registry
class Command(BaseCommand):
help = ("""Generate files for the specified image generators (or all of them if
none was provided). Simple, glob-like wildcards are allowed, with *
matching all characters within a segment, and ** matching across
segments. (Segments are separated with colons.) So, for example,
"a:*:c" will match "a:b:c", but not "a:b:x:c", whereas "a:**:c" will
match both. Subsegments are always matched, so "a" will match "a" as
well as "a:b" and "a:b:c".""")
args = '[generator_ids]'
def add_arguments(self, parser):
parser.add_argument('generator_id', nargs='*', help=':: for model specs')
def handle(self, *args, **options):
generators = generator_registry.get_ids()
generator_ids = options['generator_id'] if 'generator_id' in options else args
if generator_ids:
patterns = self.compile_patterns(generator_ids)
generators = (id for id in generators if any(p.match(id) for p in patterns))
for generator_id in generators:
self.stdout.write('Validating generator: %s\n' % generator_id)
for image_file in cachefile_registry.get(generator_id):
if image_file.name:
self.stdout.write(' %s\n' % image_file.name)
try:
image_file.generate()
except MissingSource as err:
self.stdout.write('\t No source associated with\n')
except Exception as err:
self.stdout.write('\tFailed %s\n' % (err))
def compile_patterns(self, generator_ids):
return [self.compile_pattern(id) for id in generator_ids]
def compile_pattern(self, generator_id):
parts = re.split(r'(\*{1,2})', generator_id)
pattern = ''
for part in parts:
if part == '*':
pattern += '[^:]*'
elif part == '**':
pattern += '.*'
else:
pattern += re.escape(part)
return re.compile('^%s(:.*)?$' % pattern)
matthewwithanm-django-imagekit-26cdc9d/imagekit/models/ 0000775 0000000 0000000 00000000000 15252340250 0023356 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/models/__init__.py 0000664 0000000 0000000 00000000134 15252340250 0025465 0 ustar 00root root 0000000 0000000 # flake8: noqa
from .. import conf
from .fields import ImageSpecField, ProcessedImageField
matthewwithanm-django-imagekit-26cdc9d/imagekit/models/fields/ 0000775 0000000 0000000 00000000000 15252340250 0024624 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/models/fields/__init__.py 0000664 0000000 0000000 00000011315 15252340250 0026736 0 ustar 00root root 0000000 0000000 from django.db import models
from django.db.models.signals import class_prepared
from ...registry import register
from ...specs import SpecHost
from ...specs.sourcegroups import ImageFieldSourceGroup
from .files import ProcessedImageFieldFile
from .utils import ImageSpecFileDescriptor
class SpecHostField(SpecHost):
def _set_spec_id(self, cls, name):
spec_id = getattr(self, 'spec_id', None)
# Generate a spec_id to register the spec with. The default spec id is
# ":_"
if not spec_id:
spec_id = ('%s:%s:%s' % (cls._meta.app_label,
cls._meta.object_name, name)).lower()
# Register the spec with the id. This allows specs to be overridden
# later, from outside of the model definition.
super().set_spec_id(spec_id)
class ImageSpecField(SpecHostField):
"""
The heart and soul of the ImageKit library, ImageSpecField allows you to add
variants of uploaded images to your models.
"""
def __init__(self, processors=None, format=None, options=None,
source=None, cachefile_storage=None, autoconvert=None,
cachefile_backend=None, cachefile_strategy=None, spec=None,
id=None):
SpecHost.__init__(self, processors=processors, format=format,
options=options, cachefile_storage=cachefile_storage,
autoconvert=autoconvert,
cachefile_backend=cachefile_backend,
cachefile_strategy=cachefile_strategy, spec=spec,
spec_id=id)
# TODO: Allow callable for source. See https://github.com/matthewwithanm/django-imagekit/issues/158#issuecomment-10921664
self.source = source
def contribute_to_class(self, cls, name):
# If the source field name isn't defined, figure it out.
def register_source_group(source):
setattr(cls, name, ImageSpecFileDescriptor(self, name, source))
self._set_spec_id(cls, name)
# Add the model and field as a source for this spec id
register.source_group(self.spec_id, ImageFieldSourceGroup(cls, source))
if self.source:
register_source_group(self.source)
else:
# The source argument is not defined
# Then we need to see if there is only one ImageField in that model
# But we need to do that after full model initialization
def handle_model_preparation(sender, **kwargs):
image_fields = [f.attname for f in cls._meta.fields if
isinstance(f, models.ImageField)]
if len(image_fields) == 0:
raise Exception(
'%s does not define any ImageFields, so your %s'
' ImageSpecField has no image to act on.' %
(cls.__name__, name))
elif len(image_fields) > 1:
raise Exception(
'%s defines multiple ImageFields, but you have not'
' specified a source for your %s ImageSpecField.' %
(cls.__name__, name))
register_source_group(image_fields[0])
class_prepared.connect(handle_model_preparation, sender=cls, weak=False)
class ProcessedImageField(models.ImageField, SpecHostField):
"""
ProcessedImageField is an ImageField that runs processors on the uploaded
image *before* saving it to storage. This is in contrast to specs, which
maintain the original. Useful for coercing fileformats or keeping images
within a reasonable size.
"""
attr_class = ProcessedImageFieldFile
def __init__(self, processors=None, format=None, options=None,
verbose_name=None, name=None, width_field=None, height_field=None,
autoconvert=None, spec=None, spec_id=None, **kwargs):
"""
The ProcessedImageField constructor accepts all of the arguments that
the :class:`django.db.models.ImageField` constructor accepts, as well
as the ``processors``, ``format``, and ``options`` arguments of
:class:`imagekit.models.ImageSpecField`.
"""
# if spec is not provided then autoconvert will be True by default
if spec is None and autoconvert is None:
autoconvert = True
SpecHost.__init__(self, processors=processors, format=format,
options=options, autoconvert=autoconvert, spec=spec,
spec_id=spec_id)
models.ImageField.__init__(self, verbose_name, name, width_field,
height_field, **kwargs)
def contribute_to_class(self, cls, name):
self._set_spec_id(cls, name)
return super().contribute_to_class(cls, name)
matthewwithanm-django-imagekit-26cdc9d/imagekit/models/fields/files.py 0000664 0000000 0000000 00000000754 15252340250 0026306 0 ustar 00root root 0000000 0000000 import os
from django.db.models.fields.files import ImageFieldFile
from ...utils import generate, suggest_extension
class ProcessedImageFieldFile(ImageFieldFile):
def save(self, name, content, save=True):
filename, ext = os.path.splitext(name)
spec = self.field.get_spec(source=content)
ext = suggest_extension(name, spec.format)
new_name = '%s%s' % (filename, ext)
content = generate(spec)
return super().save(new_name, content, save)
matthewwithanm-django-imagekit-26cdc9d/imagekit/models/fields/utils.py 0000664 0000000 0000000 00000001245 15252340250 0026340 0 ustar 00root root 0000000 0000000 from ...cachefiles import ImageCacheFile
class ImageSpecFileDescriptor:
def __init__(self, field, attname, source_field_name):
self.attname = attname
self.field = field
self.source_field_name = source_field_name
def __get__(self, instance, owner):
if instance is None:
return self.field
else:
source = getattr(instance, self.source_field_name)
spec = self.field.get_spec(source=source)
file = ImageCacheFile(spec)
instance.__dict__[self.attname] = file
return file
def __set__(self, instance, value):
instance.__dict__[self.attname] = value
matthewwithanm-django-imagekit-26cdc9d/imagekit/pkgmeta.py 0000664 0000000 0000000 00000000407 15252340250 0024076 0 ustar 00root root 0000000 0000000 __title__ = 'django-imagekit'
__author__ = 'Matthew Tretter, Venelin Stoykov, Eric Eldredge, Bryan Veloso, Greg Newman, Chris Drackett, Justin Driscoll'
__version__ = '6.1.1'
__license__ = 'BSD'
__all__ = ['__title__', '__author__', '__version__', '__license__']
matthewwithanm-django-imagekit-26cdc9d/imagekit/processors/ 0000775 0000000 0000000 00000000000 15252340250 0024275 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/processors/__init__.py 0000664 0000000 0000000 00000000522 15252340250 0026405 0 ustar 00root root 0000000 0000000 from pilkit.processors import *
__all__ = [
# Base
'ProcessorPipeline', 'Adjust', 'Reflection', 'Transpose',
'Anchor', 'MakeOpaque',
# Crop
'TrimBorderColor', 'Crop', 'SmartCrop',
# Resize
'Resize', 'ResizeToCover', 'ResizeToFill', 'SmartResize',
'ResizeCanvas', 'AddBorder', 'ResizeToFit', 'Thumbnail'
]
matthewwithanm-django-imagekit-26cdc9d/imagekit/processors/base.py 0000664 0000000 0000000 00000000401 15252340250 0025554 0 ustar 00root root 0000000 0000000 import warnings
from pilkit.processors.base import *
warnings.warn('imagekit.processors.base is deprecated use imagekit.processors instead', DeprecationWarning)
__all__ = ['ProcessorPipeline', 'Adjust', 'Reflection', 'Transpose', 'Anchor', 'MakeOpaque']
matthewwithanm-django-imagekit-26cdc9d/imagekit/processors/crop.py 0000664 0000000 0000000 00000000327 15252340250 0025614 0 ustar 00root root 0000000 0000000 import warnings
from pilkit.processors.crop import *
warnings.warn('imagekit.processors.crop is deprecated use imagekit.processors instead', DeprecationWarning)
__all__ = ['TrimBorderColor', 'Crop', 'SmartCrop']
matthewwithanm-django-imagekit-26cdc9d/imagekit/processors/resize.py 0000664 0000000 0000000 00000000446 15252340250 0026154 0 ustar 00root root 0000000 0000000 import warnings
from pilkit.processors.resize import *
warnings.warn('imagekit.processors.resize is deprecated use imagekit.processors instead', DeprecationWarning)
__all__ = ['Resize', 'ResizeToCover', 'ResizeToFill', 'SmartResize', 'ResizeCanvas', 'AddBorder', 'ResizeToFit', 'Thumbnail']
matthewwithanm-django-imagekit-26cdc9d/imagekit/processors/utils.py 0000664 0000000 0000000 00000000251 15252340250 0026005 0 ustar 00root root 0000000 0000000 import warnings
from pilkit.processors.utils import *
warnings.warn('imagekit.processors.utils is deprecated use pilkit.processors.utils instead', DeprecationWarning)
matthewwithanm-django-imagekit-26cdc9d/imagekit/registry.py 0000664 0000000 0000000 00000015032 15252340250 0024316 0 ustar 00root root 0000000 0000000 from .exceptions import AlreadyRegistered, NotRegistered
from .signals import content_required, existence_required, source_saved
from .utils import autodiscover, call_strategy_method
class GeneratorRegistry:
"""
An object for registering generators. This registry provides
a convenient way for a distributable app to define default generators
without locking the users of the app into it.
"""
def __init__(self):
self._generators = {}
content_required.connect(self.content_required_receiver)
existence_required.connect(self.existence_required_receiver)
def register(self, id, generator):
registered_generator = self._generators.get(id)
if registered_generator and generator != self._generators[id]:
raise AlreadyRegistered('The generator with id %s is'
' already registered' % id)
self._generators[id] = generator
def unregister(self, id):
try:
del self._generators[id]
except KeyError:
raise NotRegistered('The generator with id %s is not'
' registered' % id)
def get(self, id, **kwargs):
autodiscover()
try:
generator = self._generators[id]
except KeyError:
raise NotRegistered('The generator with id %s is not'
' registered' % id)
if callable(generator):
return generator(**kwargs)
else:
return generator
def get_ids(self):
autodiscover()
return self._generators.keys()
def content_required_receiver(self, sender, file, **kwargs):
self._receive(file, 'on_content_required')
def existence_required_receiver(self, sender, file, **kwargs):
self._receive(file, 'on_existence_required')
def _receive(self, file, callback):
generator = file.generator
# FIXME: I guess this means you can't register functions?
if generator.__class__ in self._generators.values():
# Only invoke the strategy method for registered generators.
call_strategy_method(file, callback)
class SourceGroupRegistry:
"""
The source group registry is responsible for listening to source_* signals
on source groups, and relaying them to the image generated file strategies
of the appropriate generators.
In addition, registering a new source group also registers its generated
files with that registry.
"""
_signals = {
source_saved: 'on_source_saved',
}
def __init__(self):
self._source_groups = {}
for signal in self._signals.keys():
signal.connect(self.source_group_receiver)
def register(self, generator_id, source_group):
from .specs.sourcegroups import SourceGroupFilesGenerator
generator_ids = self._source_groups.setdefault(source_group, set())
generator_ids.add(generator_id)
cachefile_registry.register(generator_id,
SourceGroupFilesGenerator(source_group, generator_id))
def unregister(self, generator_id, source_group):
from .specs.sourcegroups import SourceGroupFilesGenerator
generator_ids = self._source_groups.setdefault(source_group, set())
if generator_id in generator_ids:
generator_ids.remove(generator_id)
cachefile_registry.unregister(generator_id,
SourceGroupFilesGenerator(source_group, generator_id))
def source_group_receiver(self, sender, source, signal, **kwargs):
"""
Relay source group signals to the appropriate spec strategy.
"""
from .cachefiles import ImageCacheFile
source_group = sender
# Ignore signals from unregistered groups.
if source_group not in self._source_groups:
return
specs = [generator_registry.get(id, source=source) for id in
self._source_groups[source_group]]
callback_name = self._signals[signal]
for spec in specs:
file = ImageCacheFile(spec)
call_strategy_method(file, callback_name)
class CacheFileRegistry:
"""
An object for registering generated files with image generators. The two are
associated with each other via a string id. We do this (as opposed to
associating them directly by, for example, putting a ``cachefiles``
attribute on image generators) so that image generators can be overridden
without losing the associated files. That way, a distributable app can
define its own generators without locking the users of the app into it.
"""
def __init__(self):
self._cachefiles = {}
def register(self, generator_id, cachefiles):
"""
Associates generated files with a generator id
"""
if cachefiles not in self._cachefiles:
self._cachefiles[cachefiles] = set()
self._cachefiles[cachefiles].add(generator_id)
def unregister(self, generator_id, cachefiles):
"""
Disassociates generated files with a generator id
"""
try:
self._cachefiles[cachefiles].remove(generator_id)
except KeyError:
pass
def get(self, generator_id):
for k, v in self._cachefiles.items():
if generator_id in v:
yield from k()
class Register:
"""
Register generators and generated files.
"""
def generator(self, id, generator=None):
if generator is None:
# Return a decorator
def decorator(cls):
self.generator(id, cls)
return cls
return decorator
generator_registry.register(id, generator)
# iterable that returns kwargs or callable that returns iterable of kwargs
def cachefiles(self, generator_id, cachefiles):
cachefile_registry.register(generator_id, cachefiles)
def source_group(self, generator_id, source_group):
source_group_registry.register(generator_id, source_group)
class Unregister:
"""
Unregister generators and generated files.
"""
def generator(self, id):
generator_registry.unregister(id)
def cachefiles(self, generator_id, cachefiles):
cachefile_registry.unregister(generator_id, cachefiles)
def source_group(self, generator_id, source_group):
source_group_registry.unregister(generator_id, source_group)
generator_registry = GeneratorRegistry()
cachefile_registry = CacheFileRegistry()
source_group_registry = SourceGroupRegistry()
register = Register()
unregister = Unregister()
matthewwithanm-django-imagekit-26cdc9d/imagekit/signals.py 0000664 0000000 0000000 00000000247 15252340250 0024110 0 ustar 00root root 0000000 0000000 from django.dispatch import Signal
# Generated file signals
content_required = Signal()
existence_required = Signal()
# Source group signals
source_saved = Signal()
matthewwithanm-django-imagekit-26cdc9d/imagekit/specs/ 0000775 0000000 0000000 00000000000 15252340250 0023210 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/specs/__init__.py 0000664 0000000 0000000 00000020362 15252340250 0025324 0 ustar 00root root 0000000 0000000 from copy import copy
from django.conf import settings
from django.db.models.fields.files import ImageFieldFile
from .. import hashers
from ..cachefiles.backends import get_default_cachefile_backend
from ..cachefiles.strategies import load_strategy
from ..exceptions import AlreadyRegistered, MissingSource
from ..registry import generator_registry, register
from ..utils import get_by_qname, open_image, process_image
class BaseImageSpec:
"""
An object that defines how an new image should be generated from a source
image.
"""
cachefile_storage = None
"""A Django storage system to use to save a cache file."""
cachefile_backend = None
"""
An object responsible for managing the state of cache files. Defaults to
an instance of ``IMAGEKIT_DEFAULT_CACHEFILE_BACKEND``
"""
cachefile_strategy = settings.IMAGEKIT_DEFAULT_CACHEFILE_STRATEGY
"""
A dictionary containing callbacks that allow you to customize how and when
the image file is created. Defaults to
``IMAGEKIT_DEFAULT_CACHEFILE_STRATEGY``.
"""
def __init__(self):
self.cachefile_backend = self.cachefile_backend or get_default_cachefile_backend()
self.cachefile_strategy = load_strategy(self.cachefile_strategy)
def generate(self):
raise NotImplementedError
MissingSource = MissingSource
"""
Raised when an operation requiring a source is attempted on a spec that has
no source.
"""
class ImageSpec(BaseImageSpec):
"""
An object that defines how to generate a new image from a source file using
PIL-based processors. (See :mod:`imagekit.processors`)
"""
processors = []
"""A list of processors to run on the original image."""
format = None
"""
The format of the output file. If not provided, ImageSpecField will try to
guess the appropriate format based on the extension of the filename and the
format of the input image.
"""
options = None
"""
A dictionary that will be passed to PIL's ``Image.save()`` method as keyword
arguments. Valid options vary between formats, but some examples include
``quality``, ``optimize``, and ``progressive`` for JPEGs. See the PIL
documentation for others.
"""
autoconvert = True
"""
Specifies whether automatic conversion using ``prepare_image()`` should be
performed prior to saving.
"""
def __init__(self, source):
self.source = source
super().__init__()
@property
def cachefile_name(self):
if not self.source:
return None
fn = get_by_qname(settings.IMAGEKIT_SPEC_CACHEFILE_NAMER, 'namer')
return fn(self)
@property
def source(self):
src = getattr(self, '_source', None)
if not src:
field_data = getattr(self, '_field_data', None)
if field_data:
src = self._source = getattr(field_data['instance'], field_data['attname'])
del self._field_data
return src
@source.setter
def source(self, value):
self._source = value
def __getstate__(self):
state = copy(self.__dict__)
# Unpickled ImageFieldFiles won't work (they're missing a storage
# object). Since they're such a common use case, we special case them.
# Unfortunately, this also requires us to add the source getter to
# lazily retrieve the source on the reconstructed object; simply trying
# to look up the source in ``__setstate__`` would require us to get the
# model instance but, if ``__setstate__`` was called as part of
# deserializing that model, the model wouldn't be fully reconstructed
# yet, preventing us from accessing the source field.
# (This is issue #234.)
if isinstance(self.source, ImageFieldFile):
field = self.source.field
state['_field_data'] = {
'instance': getattr(self.source, 'instance', None),
'attname': getattr(field, 'name', None),
}
state.pop('_source', None)
return state
def get_hash(self):
return hashers.pickle([
self.source.name,
self.processors,
self.format,
self.options,
self.autoconvert,
])
def generate(self):
if not self.source:
raise MissingSource("The spec '%s' has no source file associated"
" with it." % self)
# TODO: Move into a generator base class
# TODO: Factor out a generate_image function so you can create a generator and only override the PIL.Image creating part.
# (The tricky part is how to deal with original_format since generator base class won't have one.)
closed = self.source.closed
if closed:
# Django file object should know how to reopen itself if it was closed
# https://code.djangoproject.com/ticket/13750
self.source.open()
try:
img = open_image(self.source)
new_image = process_image(img,
processors=self.processors,
format=self.format,
autoconvert=self.autoconvert,
options=self.options)
finally:
if closed:
# We need to close the file if it was opened by us
self.source.close()
return new_image
def create_spec_class(class_attrs):
class DynamicSpecBase(ImageSpec):
def __reduce__(self):
try:
getstate = self.__getstate__
except AttributeError:
state = self.__dict__
else:
state = getstate()
return (create_spec, (class_attrs, state))
return type('DynamicSpec', (DynamicSpecBase,), class_attrs)
def create_spec(class_attrs, state):
cls = create_spec_class(class_attrs)
instance = cls.__new__(cls) # Create an instance without calling the __init__ (which may have required args).
try:
setstate = instance.__setstate__
except AttributeError:
instance.__dict__ = state
else:
setstate(state)
return instance
class SpecHost:
"""
An object that ostensibly has a spec attribute but really delegates to the
spec registry.
"""
def __init__(self, spec=None, spec_id=None, **kwargs):
spec_attrs = {k: v for k, v in kwargs.items() if v is not None}
if spec_attrs:
if spec:
raise TypeError('You can provide either an image spec or'
' arguments for the ImageSpec constructor, but not both.')
else:
spec = create_spec_class(spec_attrs)
self._original_spec = spec
if spec_id:
self.set_spec_id(spec_id)
def set_spec_id(self, id):
"""
Sets the spec id for this object. Useful for when the id isn't
known when the instance is constructed (e.g. for ImageSpecFields whose
generated `spec_id`s are only known when they are contributed to a
class). If the object was initialized with a spec, it will be registered
under the provided id.
"""
self.spec_id = id
if self._original_spec:
try:
register.generator(id, self._original_spec)
except AlreadyRegistered:
# Fields should not cause AlreadyRegistered exceptions. If a
# spec is already registered, that should be used. It is
# especially important that an error is not thrown here because
# of South, which will create duplicate models as part of its
# "fake orm," therefore re-registering specs.
pass
def get_spec(self, source):
"""
Look up the spec by the spec id. We do this (instead of storing the
spec as an attribute) so that users can override apps' specs--without
having to edit model definitions--simply by registering another spec
with the same id.
"""
if not getattr(self, 'spec_id', None):
raise Exception('Object %s has no spec id.' % self)
return generator_registry.get(self.spec_id, source=source)
matthewwithanm-django-imagekit-26cdc9d/imagekit/specs/sourcegroups.py 0000664 0000000 0000000 00000014256 15252340250 0026332 0 ustar 00root root 0000000 0000000 """
Source groups are the means by which image spec sources are identified. They
have two responsibilities:
1. To dispatch ``source_saved`` signals. (These will be relayed to the
corresponding specs' cache file strategies.)
2. To provide the source files that they represent, via a generator method named
``files()``. (This is used by the generateimages management command for
"pre-caching" image files.)
"""
import inspect
from django.db.models.signals import post_init, post_save
from django.utils.functional import wraps
from ..cachefiles import LazyImageCacheFile
from ..signals import source_saved
from ..utils import get_nonabstract_descendants
def ik_model_receiver(fn):
"""
A method decorator that filters out signals coming from models that don't
have fields that function as ImageFieldSourceGroup sources.
"""
@wraps(fn)
def receiver(self, sender, **kwargs):
if not inspect.isclass(sender):
return
for src in self._source_groups:
if issubclass(sender, src.model_class):
fn(self, sender=sender, **kwargs)
# If we find a match, return. We don't want to handle the signal
# more than once.
return
return receiver
class ModelSignalRouter:
"""
Normally, ``ImageFieldSourceGroup`` would be directly responsible for
watching for changes on the model field it represents. However, Django does
not dispatch events for abstract base classes. Therefore, we must listen for
the signals on all models and filter out those that aren't represented by
``ImageFieldSourceGroup``s. This class encapsulates that functionality.
Related:
https://github.com/matthewwithanm/django-imagekit/issues/126
https://code.djangoproject.com/ticket/9318
"""
def __init__(self):
self._source_groups = []
uid = 'ik_spec_field_receivers'
post_init.connect(self.post_init_receiver, dispatch_uid=uid)
post_save.connect(self.post_save_receiver, dispatch_uid=uid)
def add(self, source_group):
self._source_groups.append(source_group)
def init_instance(self, instance):
instance._ik = getattr(instance, '_ik', {})
def update_source_hashes(self, instance):
"""
Stores hashes of the source image files so that they can be compared
later to see whether the source image has changed (and therefore whether
the spec file needs to be regenerated).
"""
self.init_instance(instance)
instance._ik['source_hashes'] = {
attname: hash(getattr(instance, attname))
for attname in self.get_source_fields(instance)}
return instance._ik['source_hashes']
def get_source_fields(self, instance):
"""
Returns a list of the source fields for the given instance.
"""
return {
src.image_field
for src in self._source_groups
if isinstance(instance, src.model_class)}
@ik_model_receiver
def post_save_receiver(self, sender, instance=None, created=False, update_fields=None, raw=False, **kwargs):
if not raw:
self.init_instance(instance)
old_hashes = instance._ik.get('source_hashes', {}).copy()
new_hashes = self.update_source_hashes(instance)
for attname in self.get_source_fields(instance):
if update_fields and attname not in update_fields:
continue
file = getattr(instance, attname)
if file and old_hashes.get(attname) != new_hashes[attname]:
self.dispatch_signal(source_saved, file, sender, instance,
attname)
@ik_model_receiver
def post_init_receiver(self, sender, instance=None, **kwargs):
self.init_instance(instance)
source_fields = self.get_source_fields(instance)
local_fields = {
field.name: field
for field in instance._meta.local_fields
if field.name in source_fields}
instance._ik['source_hashes'] = {
attname: hash(file_field)
for attname, file_field in local_fields.items()}
def dispatch_signal(self, signal, file, model_class, instance, attname):
"""
Dispatch the signal for each of the matching source groups. Note that
more than one source can have the same model and image_field; it's
important that we dispatch the signal for each.
"""
for source_group in self._source_groups:
if issubclass(model_class, source_group.model_class) and source_group.image_field == attname:
signal.send(sender=source_group, source=file)
class ImageFieldSourceGroup:
"""
A source group that represents a particular field across all instances of a
model and its subclasses.
"""
def __init__(self, model_class, image_field):
self.model_class = model_class
self.image_field = image_field
signal_router.add(self)
def files(self):
"""
A generator that returns the source files that this source group
represents; in this case, a particular field of every instance of a
particular model and its subclasses.
"""
for model in get_nonabstract_descendants(self.model_class):
for instance in model.objects.all().iterator():
yield getattr(instance, self.image_field)
class SourceGroupFilesGenerator:
"""
A Python generator that yields cache file objects for source groups.
"""
def __init__(self, source_group, generator_id):
self.source_group = source_group
self.generator_id = generator_id
def __eq__(self, other):
return (isinstance(other, self.__class__)
and self.__dict__ == other.__dict__)
def __ne__(self, other):
return not self.__eq__(other)
def __hash__(self):
return hash((self.source_group, self.generator_id))
def __call__(self):
for source_file in self.source_group.files():
yield LazyImageCacheFile(self.generator_id,
source=source_file)
signal_router = ModelSignalRouter()
matthewwithanm-django-imagekit-26cdc9d/imagekit/templates/ 0000775 0000000 0000000 00000000000 15252340250 0024071 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/templates/imagekit/ 0000775 0000000 0000000 00000000000 15252340250 0025663 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/templates/imagekit/admin/ 0000775 0000000 0000000 00000000000 15252340250 0026753 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/templates/imagekit/admin/thumbnail.html 0000664 0000000 0000000 00000000212 15252340250 0031617 0 ustar 00root root 0000000 0000000 {% if thumbnail %}
{% endif %} matthewwithanm-django-imagekit-26cdc9d/imagekit/templatetags/ 0000775 0000000 0000000 00000000000 15252340250 0024565 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/templatetags/__init__.py 0000664 0000000 0000000 00000000000 15252340250 0026664 0 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/imagekit/templatetags/imagekit.py 0000664 0000000 0000000 00000027502 15252340250 0026737 0 ustar 00root root 0000000 0000000 from inspect import signature
from django import template
from django.template.library import parse_bits
from django.utils.encoding import force_str
from django.utils.html import escape
from django.utils.safestring import mark_safe
from django.conf import settings
from ..cachefiles import ImageCacheFile
from ..registry import generator_registry
register = template.Library()
ASSIGNMENT_DELIMETER = 'as'
HTML_ATTRS_DELIMITER = '--'
DEFAULT_THUMBNAIL_GENERATOR = 'imagekit:thumbnail'
default_thumbnail_srcset_scales = getattr(settings, 'IMAGEKIT_DEFAULT_THUMBNAIL_SRCSET_SCALES', None)
# Django 6.1 removed the takes_context parameter from the undocumented parse_bits
if 'takes_context' in signature(parse_bits).parameters:
def _parse_args_kwargs(parser, bits, params, tag_name):
return parse_bits(parser, bits, params, 'args', 'kwargs', None, [], None, False, tag_name)
else:
def _parse_args_kwargs(parser, bits, params, tag_name):
return parse_bits(parser, bits, params, 'args', 'kwargs', None, [], None, tag_name)
def get_cachefile(context, generator_id, generator_kwargs, source=None):
generator_id = generator_id.resolve(context)
kwargs = {k: v.resolve(context) for k, v in generator_kwargs.items()}
generator = generator_registry.get(generator_id, **kwargs)
return ImageCacheFile(generator)
def parse_dimensions(dimensions):
"""
Parse the width and height values from a dimension string. Valid values are
'1x1', '1x', and 'x1'. If one of the dimensions is omitted, the parse result
will be None for that value.
"""
width, height = [d.strip() and int(d) or None for d in dimensions.split('x')]
return {'width': width, 'height': height}
class GenerateImageAssignmentNode(template.Node):
def __init__(self, variable_name, generator_id, generator_kwargs):
self._generator_id = generator_id
self._generator_kwargs = generator_kwargs
self._variable_name = variable_name
def get_variable_name(self, context):
return force_str(self._variable_name)
def render(self, context):
variable_name = self.get_variable_name(context)
context[variable_name] = get_cachefile(context, self._generator_id,
self._generator_kwargs)
return ''
class GenerateImageTagNode(template.Node):
def __init__(self, generator_id, generator_kwargs, html_attrs):
self._generator_id = generator_id
self._generator_kwargs = generator_kwargs
self._html_attrs = html_attrs
def render(self, context):
file = get_cachefile(context, self._generator_id,
self._generator_kwargs)
attrs = {k: v.resolve(context) for k, v in self._html_attrs.items()}
# Only add width and height if neither is specified (to allow for
# proportional in-browser scaling).
if 'width' not in attrs and 'height' not in attrs:
attrs.update(width=file.width, height=file.height)
attrs['src'] = file.url
attr_str = ' '.join('%s="%s"' % (escape(k), escape(v)) for k, v in
attrs.items())
return mark_safe('' % attr_str)
class ThumbnailAssignmentNode(template.Node):
def __init__(self, variable_name, generator_id, dimensions, source, generator_kwargs):
self._variable_name = variable_name
self._generator_id = generator_id
self._dimensions = dimensions
self._source = source
self._generator_kwargs = generator_kwargs
def get_variable_name(self, context):
return force_str(self._variable_name)
def render(self, context):
variable_name = self.get_variable_name(context)
generator_id = self._generator_id.resolve(context) if self._generator_id else DEFAULT_THUMBNAIL_GENERATOR
kwargs = {k: v.resolve(context) for k, v in self._generator_kwargs.items()}
kwargs['source'] = self._source.resolve(context)
kwargs.update(parse_dimensions(self._dimensions.resolve(context)))
if kwargs.get('anchor'):
# ImageKit uses pickle at protocol 0, which throws infinite
# recursion errors when anchor is set to a SafeString instance.
# This converts the SafeString into a str instance.
kwargs['anchor'] = kwargs['anchor'][:]
if kwargs.get('format'):
kwargs['format'] = kwargs['format'][:]
generator = generator_registry.get(generator_id, **kwargs)
context[variable_name] = ImageCacheFile(generator)
return ''
class ThumbnailImageTagNode(template.Node):
def __init__(self, generator_id, dimensions, source, generator_kwargs, html_attrs):
self._generator_id = generator_id
self._dimensions = dimensions
self._source = source
self._generator_kwargs = generator_kwargs
self._html_attrs = html_attrs
def render(self, context):
generator_id = self._generator_id.resolve(context) if self._generator_id else DEFAULT_THUMBNAIL_GENERATOR
dimensions = parse_dimensions(self._dimensions.resolve(context))
kwargs = {k: v.resolve(context) for k, v in self._generator_kwargs.items()}
kwargs['source'] = self._source.resolve(context)
kwargs.update(dimensions)
if kwargs.get('anchor'):
# ImageKit uses pickle at protocol 0, which throws infinite
# recursion errors when anchor is set to a SafeString instance.
# This converts the SafeString into a str instance.
kwargs['anchor'] = kwargs['anchor'][:]
srcset_scales = default_thumbnail_srcset_scales
if "srcset" in kwargs:
if kwargs['srcset'] is not None:
srcset_scales = list(map(float, kwargs['srcset'].split()))
else:
srcset_scales = None
kwargs.pop("srcset")
if kwargs.get('format'):
kwargs['format'] = kwargs['format'][:]
generator = generator_registry.get(generator_id, **kwargs)
file = ImageCacheFile(generator)
srcset = []
if srcset_scales:
for scale in srcset_scales:
scaled_kwargs = dict(kwargs)
if scaled_kwargs.get("height"):
scaled_kwargs["height"] = int(scaled_kwargs["height"] * scale)
if scaled_kwargs.get("width"):
scaled_kwargs["width"] = int(scaled_kwargs["width"] * scale)
srcset.append(ImageCacheFile(generator_registry.get(generator_id, **scaled_kwargs)))
attrs = {k: v.resolve(context) for k, v in self._html_attrs.items()}
# Only add width and height if neither is specified (to allow for
# proportional in-browser scaling).
if 'width' not in attrs and 'height' not in attrs:
attrs.update(width=file.width, height=file.height)
attrs['src'] = file.url
if len(srcset) > 0:
attrs['srcset'] = f'{file.url} 1x , ' + ' , '.join(
f'{entry[0].url} {entry[1]}x' for entry in zip(srcset, srcset_scales))
attr_str = ' '.join('%s="%s"' % (escape(k), escape(v)) for k, v in
attrs.items())
return mark_safe('' % attr_str)
def parse_ik_tag_bits(parser, bits):
"""
Parses the tag name, html attributes and variable name (for assignment tags)
from the provided bits. The preceding bits may vary and are left to be
parsed by specific tags.
"""
varname = None
html_attrs = {}
tag_name = bits.pop(0)
if len(bits) >= 2 and bits[-2] == ASSIGNMENT_DELIMETER:
varname = bits[-1]
bits = bits[:-2]
if HTML_ATTRS_DELIMITER in bits:
if varname:
raise template.TemplateSyntaxError('Do not specify html attributes'
' (using "%s") when using the "%s" tag as an assignment'
' tag.' % (HTML_ATTRS_DELIMITER, tag_name))
index = bits.index(HTML_ATTRS_DELIMITER)
html_bits = bits[index + 1:]
bits = bits[:index]
if not html_bits:
raise template.TemplateSyntaxError('Don\'t use "%s" unless you\'re'
' setting html attributes.' % HTML_ATTRS_DELIMITER)
args, html_attrs = _parse_args_kwargs(parser, html_bits, [], tag_name)
if len(args):
raise template.TemplateSyntaxError('All "%s" tag arguments after'
' the "%s" token must be named.' % (tag_name,
HTML_ATTRS_DELIMITER))
return (tag_name, bits, html_attrs, varname)
@register.tag
def generateimage(parser, token):
"""
Creates an image based on the provided arguments.
By default::
{% generateimage 'myapp:thumbnail' source=mymodel.profile_image %}
generates an ```` tag::
You can add additional attributes to the tag using "--". For example,
this::
{% generateimage 'myapp:thumbnail' source=mymodel.profile_image -- alt="Hello!" %}
will result in the following markup::
For more flexibility, ``generateimage`` also works as an assignment tag::
{% generateimage 'myapp:thumbnail' source=mymodel.profile_image as th %}
"""
bits = token.split_contents()
tag_name, bits, html_attrs, varname = parse_ik_tag_bits(parser, bits)
args, kwargs = _parse_args_kwargs(parser, bits, ['generator_id'], tag_name)
if len(args) != 1:
raise template.TemplateSyntaxError('The "%s" tag requires exactly one'
' unnamed argument (the generator id).' % tag_name)
generator_id = args[0]
if varname:
return GenerateImageAssignmentNode(varname, generator_id, kwargs)
else:
return GenerateImageTagNode(generator_id, kwargs, html_attrs)
@register.tag
def thumbnail(parser, token):
"""
A convenient shortcut syntax for generating a thumbnail. The following::
{% thumbnail '100x100' mymodel.profile_image %}
is equivalent to::
{% generateimage 'imagekit:thumbnail' source=mymodel.profile_image width=100 height=100 %}
The thumbnail tag supports the "--" and "as" bits for adding html
attributes and assigning to a variable, respectively. It also accepts the
kwargs "format", "srcset", "anchor", and "crop".
To use "srcset" (generating multiple thumbnails for different pixel densities) list the scale factors::
{% thumbnail '100x100' mymodel.profile_image srcset='2 3' %}
To use "smart cropping" (the ``SmartResize`` processor)::
{% thumbnail '100x100' mymodel.profile_image %}
To crop, anchoring the image to the top right (the ``ResizeToFill``
processor)::
{% thumbnail '100x100' mymodel.profile_image anchor='tr' %}
To resize without cropping (using the ``ResizeToFit`` processor)::
{% thumbnail '100x100' mymodel.profile_image crop=0 %}
"""
bits = token.split_contents()
tag_name, bits, html_attrs, varname = parse_ik_tag_bits(parser, bits)
args, kwargs = _parse_args_kwargs(parser, bits, [], tag_name)
if len(args) < 2:
raise template.TemplateSyntaxError('The "%s" tag requires at least two'
' unnamed arguments: the dimensions and the source image.'
% tag_name)
elif len(args) > 3:
raise template.TemplateSyntaxError('The "%s" tag accepts at most three'
' unnamed arguments: a generator id, the dimensions, and the'
' source image.' % tag_name)
dimensions, source = args[-2:]
generator_id = args[0] if len(args) > 2 else None
if varname:
return ThumbnailAssignmentNode(varname, generator_id, dimensions,
source, kwargs)
else:
return ThumbnailImageTagNode(generator_id, dimensions, source, kwargs,
html_attrs)
matthewwithanm-django-imagekit-26cdc9d/imagekit/utils.py 0000664 0000000 0000000 00000011056 15252340250 0023610 0 ustar 00root root 0000000 0000000 import logging
import re
from hashlib import md5
from importlib import import_module
from django.conf import settings
from django.core.exceptions import ImproperlyConfigured
from django.core.files import File
from pilkit.utils import *
bad_memcached_key_chars = re.compile('[\u0000-\u001f\\s]+')
_autodiscovered = False
def get_nonabstract_descendants(model):
""" Returns all non-abstract descendants of the model. """
if not model._meta.abstract:
yield model
for s in model.__subclasses__():
yield from get_nonabstract_descendants(s)
def get_by_qname(path, desc):
try:
dot = path.rindex('.')
except ValueError:
raise ImproperlyConfigured("%s isn't a %s module." % (path, desc))
module, objname = path[:dot], path[dot + 1:]
try:
mod = import_module(module)
except ImportError as e:
raise ImproperlyConfigured('Error importing %s module %s: "%s"' %
(desc, module, e))
try:
obj = getattr(mod, objname)
return obj
except AttributeError:
raise ImproperlyConfigured('%s module "%s" does not define "%s"'
% (desc[0].upper() + desc[1:], module, objname))
_singletons = {}
def get_singleton(class_path, desc):
global _singletons
cls = get_by_qname(class_path, desc)
instance = _singletons.get(cls)
if not instance:
instance = _singletons[cls] = cls()
return instance
def autodiscover():
"""
Auto-discover INSTALLED_APPS imagegenerators.py modules and fail silently
when not present. This forces an import on them to register any admin bits
they may want.
Copied from django.contrib.admin
"""
global _autodiscovered
if _autodiscovered:
return
from django.utils.module_loading import autodiscover_modules
autodiscover_modules('imagegenerators')
_autodiscovered = True
def get_logger(logger_name='imagekit', add_null_handler=True):
logger = logging.getLogger(logger_name)
if add_null_handler:
logger.addHandler(logging.NullHandler())
return logger
def get_field_info(field_file):
"""
A utility for easily extracting information about the host model from a
Django FileField (or subclass). This is especially useful for when you want
to alter processors based on a property of the source model. For example::
class MySpec(ImageSpec):
def __init__(self, source):
instance, attname = get_field_info(source)
self.processors = [SmartResize(instance.thumbnail_width,
instance.thumbnail_height)]
"""
return (
getattr(field_file, 'instance', None),
getattr(getattr(field_file, 'field', None), 'attname', None),
)
def generate(generator):
"""
Calls the ``generate()`` method of a generator instance, and then wraps the
result in a Django File object so Django knows how to save it.
"""
content = generator.generate()
f = File(content)
# The size of the File must be known or Django will try to open a file
# without a name and raise an Exception.
f.size = len(content.read())
# After getting the size reset the file pointer for future reads.
content.seek(0)
return f
def call_strategy_method(file, method_name):
strategy = getattr(file, 'cachefile_strategy', None)
fn = getattr(strategy, method_name, None)
if fn is not None:
fn(file)
def get_cache():
from django.core.cache import caches
return caches[settings.IMAGEKIT_CACHE_BACKEND]
def get_storage():
try:
from django.core.files.storage import storages, InvalidStorageError
except ImportError: # Django < 4.2
return get_singleton(
settings.IMAGEKIT_DEFAULT_FILE_STORAGE, 'file storage backend'
)
else:
try:
return storages[settings.IMAGEKIT_DEFAULT_FILE_STORAGE]
except InvalidStorageError:
return get_singleton(
settings.IMAGEKIT_DEFAULT_FILE_STORAGE, 'file storage backend'
)
def sanitize_cache_key(key):
if settings.IMAGEKIT_USE_MEMCACHED_SAFE_CACHE_KEY:
# Memcached keys can't contain whitespace or control characters.
new_key = bad_memcached_key_chars.sub('', key)
# The also can't be > 250 chars long. Since we don't know what the
# user's cache ``KEY_FUNCTION`` setting is like, we'll limit it to 200.
if len(new_key) >= 200:
new_key = '%s:%s' % (new_key[:200 - 33], md5(key.encode('utf-8')).hexdigest())
key = new_key
return key
matthewwithanm-django-imagekit-26cdc9d/justfile 0000664 0000000 0000000 00000000116 15252340250 0022047 0 ustar 00root root 0000000 0000000 publish:
python -m build
python -m twine upload dist/*
test:
tox
matthewwithanm-django-imagekit-26cdc9d/pyproject.toml 0000664 0000000 0000000 00000003461 15252340250 0023221 0 ustar 00root root 0000000 0000000 [build-system]
requires = ["setuptools>=61", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "django-imagekit"
dynamic = ["version"]
description = "Automated image processing for Django models."
readme = {file = "README.rst", content-type = "text/x-rst"}
authors = [
{name = "Matthew Tretter", email = "m@tthewwithanm.com"},
]
maintainers = [
{name = "Venelin Stoykov", email = "venelin.stoykov@industria.tech"},
]
license = "BSD-3-Clause"
classifiers = [
"Development Status :: 5 - Production/Stable",
"Environment :: Web Environment",
"Framework :: Django",
"Intended Audience :: Developers",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3 :: Only",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",
"Topic :: Utilities",
]
requires-python = ">=3.9"
dependencies = [
"django-appconf",
"pilkit",
]
[project.urls]
Homepage = "http://github.com/matthewwithanm/django-imagekit/"
[project.optional-dependencies]
test = [
"beautifulsoup4",
"Pillow",
"pytest",
"pytest-cov",
"pytest-django",
]
async = ["django-celery>=3.0"]
async_rq = ["django-rq>=0.6.0"]
async_dramatiq = ["django-dramatiq>=0.4.0"]
[tool.setuptools]
include-package-data = true
zip-safe = false
[tool.setuptools.packages.find]
exclude = ["*.tests", "*.tests.*", "tests.*", "tests"]
[tool.setuptools.dynamic]
version = {attr = "imagekit.pkgmeta.__version__"}
[tool.pytest.ini_options]
django_find_project = false
DJANGO_SETTINGS_MODULE = "tests.settings"
matthewwithanm-django-imagekit-26cdc9d/tests/ 0000775 0000000 0000000 00000000000 15252340250 0021443 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/tests/__init__.py 0000664 0000000 0000000 00000000000 15252340250 0023542 0 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/tests/conftest.py 0000664 0000000 0000000 00000000314 15252340250 0023640 0 ustar 00root root 0000000 0000000 import pytest
from .utils import clear_imagekit_test_files
@pytest.fixture(scope='session', autouse=True)
def imagekit_test_files_teardown(request):
request.addfinalizer(clear_imagekit_test_files)
matthewwithanm-django-imagekit-26cdc9d/tests/imagegenerators.py 0000664 0000000 0000000 00000000663 15252340250 0025176 0 ustar 00root root 0000000 0000000 from imagekit import ImageSpec, register
from imagekit.processors import ResizeToFill
class TestSpec(ImageSpec):
__test__ = False
class ResizeTo1PixelSquare(ImageSpec):
def __init__(self, width=None, height=None, anchor=None, crop=None, **kwargs):
self.processors = [ResizeToFill(1, 1)]
super().__init__(**kwargs)
register.generator('testspec', TestSpec)
register.generator('1pxsq', ResizeTo1PixelSquare)
matthewwithanm-django-imagekit-26cdc9d/tests/media/ 0000775 0000000 0000000 00000000000 15252340250 0022522 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/tests/media/reference.png 0000664 0000000 0000000 00000351176 15252340250 0025203 0 ustar 00root root 0000000 0000000 PNG
IHDR ?1 IDATxlYmr&}_s{K^I"KF (A2,0 /~'a TK%Tl.yo;uguZp HfP z `{F )3<"H( t l&ʀKJN%)SwMjHa.@#<VMIGHD!AMA `SNAE#FGH35$"hp%i23R Ԋ&,]NniIRkʽ@K.VB`^~7/^Ww6chefL̚q3vv{hRUiW}qZBۡ =[xG{/R lH@3ܣ )nB9:RPn܅Ba %"@? :r
rss {_ꁊK"quśKj 0lі @
!w2
Q Ü
ipD0P@3h_> ALShC Dx¬ H* b$M AD`4Be'p7
q!n^D(s
X
9-2M{4Zc&)V䛛/_7:VLJqy5o~ Ίfyo | _PQuّ( cBv
t%A(""@"Hwgw> şe1u/CiwWM$o/=479 p
C
Q*Άp$Ja[X Ɣ n]DBR]y RRbx#hHZͼZࠖ$4SGpw'N}a[uZ-6d/^H+UJ*qyuq])2>~
+VT6)V F5* 14&BCᆤ#eGE`
1VD"Zogf%5I*tttJ]B=OOeCWH%0lޏ&I ')"h W=DCx3a,q3! j U@ZY|~}jf D X,fsrv6OΞ>:[<{lZm6G} =y^[/N/Ky[vW_ W_E7!2 Xm"' J{iP \
n
AXlN ur*F Gc &E [?YN_.Ȫ92%eẎǏ V^GvПZ͋onbi$~yu!}TV-{gJb@M "cK! FM!P4hn X@}Y
/5DbV)-y$GD;֪z;d+餸yCB,D BUF5J;6<=(TzHQ% n %"U5Tt{}wj3 BH7a|D BsWal|pll 7A?}9qU{ ͛b8;='~Wg =,[l 硧gaX.e: ݠ=%%а`m0Nn.?#uNz(1Y&RC ˋ]ORBsTw pPDz@].d@2R`CTJjrpg"D)^ka$QbWJUpjB8 Q2*Q T݃G ejue[ !aRRbQ0
7'#̫TGFb C8sA(ZøIL is>=ϫYY-6I~z^a%PGJQ%Ϫ9x 5^ӤVr""m+ sf@
FDZ-
hrI]>)C9Rg'}
llNw{ԕߜ6rrZ-uNΌɜd@`` OקgR?DcuFׂi7 hte7(IDraM*S-Bi
;S%!*"ݠ)S2R-(PGW @UrXD?tyuLU HT#H ʾ.(Gƽ ___OvU ?nOϞtޭ$alZ_7٢)2V0N7ۉ5-2=$~B$U_Y][݈N}aaajaUQ!0McOӝ[CI&Br^ka E$D4b""r رh JXT} 44 &,0dX *j4&xZjd# 0 a KC7B"+-S)QŲ_{}t]N>
i2
}~ɻe?^aYnwysq|{˯\^]n̾]ZD9Qry\HH7<}ԯNjbY?3C~/O ?钦;?=.$>)Ю; sFcpK3Tvl|hn\w hV@eRճ'Zs33"[Yp 7˃aW#!\-ZpXq]|Z.s)-AձTEy`PQl? yu7[F@͐9K7@
q} Xq@ܬ/0UnNYJgJ) !P ~\KS0h uQM=ٜ?;Ov?XĖwћMN.TVRBD n&"SԠ{ ܻ0\e_ A#hc
+Pm+Z+@s+$k,DU.1* c2\a%!%`3I!Ő =]E Hb D PG=:%
47ҧzh T̔r~~ lx7m~??zλq!`08_Xhe&f$p ³JK珎r n0֟\,Ճ hgǸ 5jyYru;Y{G Hl`Nkcb/S<&iJ7wDRLd$\[oo>K5
=}|e/>ǻ "z$ BQؿ o) $/͕EҡN/T7.y8$nnb5`]Ju/`nX
/VMçqj1iBroމN5F* ̔mA R#~
0)W( k 2¨=f5ħNe VYvJ%P$>9s=ī9 }CPݺnZt =ݬ$wy8#WьBg<Ka{lJ972lH5. +BoETa j ÂB?&Gvk BtRj
N%$(Ct
Ѓ::qE1
mJt_ ܧfGJ/w.z
Oz= __.:^WG_vbd 9VT%i0+Q9ղz "~"(D@jO4)a>012mo S
$#;A>9Nw%,}0Ѭ 4H
!mԈI-@J Tg ,
;,;K@KC]e
Q
7XDd*E?ZꆏsDi#! ; DkZXHƏ qZ]iVPLMH
( nAJ{ˬ9;"^2oBZ3 ԧ=[/5u-KVI^Wu#~,s[ Ǫ'4
+iS+n}X.ww13œ.C..U.+{lJ("<YLn5 &{}3U6B;,"&ZJ@f2dc-a0E Xu 1`Q'3T4d''n $Q8]R.!YanpMJ(!B]T̀{L=Qg.
Q "R!n(nn-f m K&8}|t)E`[(;` 11*4OA
iE
l4r(x2s jx& HH *R70dv.@XٷY+h@$4ZŌo W XD:"<0E?Nc=87\xO^^T/ p;`?dSC(p:8yH4{vT۩~=
B"H OjvDX9i5w6N`Z
ARfS)L#8Nc47RJ"(4qwVTbp^p0'Yu Vswa ,AE@PUxDX9"{$G +bLe: &2|*r 6B{Xm -9`HPeΎ5*"Z3RZ*L RXc@o؈s)6 B63`6(.Tca eo{YqzH}nsJIj@/nbꮹ?GRWw?n:Oz& 6xdF "twyaMv:z,K_iޥ¤#D$e7 b군F) a:Lc Se8lG*]
NA;w7u*S[0&rʩKI6L9u) ҦBQ0@蠇vIE91R @R UKej mhM*rw}y^/g:4Myf
@ jP5f($..´ @RRH~ ɂ "Ĩ.}!7isJ- ֚́c4 sftJN9f 1w<6 Wр
q oM bv @EFl
hyQ4z'ʿ
c'' ?2ȉ0RPR/c RROWZˤSHIS2@i:dM%2ZY ijY,{A 2 %E҉pGJ&j(*E͊hҼ$s4jvy_Hj1M]4}YJN 1I2}2r yq{}qu>4E֘\ pVhe wz]G!D42d-} 6A^vgؼ&IƱ& } ?`;j<2| ~ ?"m{h uY)R{j?lu? ԣMxwՊ ڇi@$54$e$BhHNɪ"(@}tdr`0e8au0ڴz
D
[Y 1Q>!T:u KE\P Hគ[pر:6`8^
ه|i1[?*$[;bI2g{sLHH5n)IUS6mdʿ
<(Ol![@TFxrrQji^COI:R ß\ Rq;<{~燏={vv*~
}s؍INJ̹V -K֧2N{{漎2d~'#O6@jJ Y`%Dߘe
f27bUu 4uCDH-Lޔ]I:3T$w}uJ2j 2/k rx sZ5Ű:Rd=Já볹kd<4:$(
R%i[4#(ɧd8r
!:WQ[R`1 @BIE%6&ëG0w]$#1ZDp@Efݑ 4!
O&`h L&^)hjA렙QT2Фh3AmM6 <
c$x<^] [t%ۚ3Ly[?# ,OVv{$u
`ҞڿwFԓ㤹~;?}fR3Et9;UMHJuRi7o)K=w7͛}jXΖ;#ݬNLb:l`4&$kN7pT$D@Q*e.V9
}DZG$IIj]jRZba)iJc; t$5#"as3hkB#39 m 4PCr o@-Rb;# ,Q{FEu:4[j*#:CCxι+5,]x{Б=k[̡}8s4,lЉ =KrIݨ$ƒj
wσMUl?~9 <սrx'P(#(: Q ID@5`z_|Ea{'5= ~G!
$C!nՀ0+Q,Ja+-qG43M)fXy\Hw!E RJ.
$ fwrOZ^#<"Di< q/dߩϚR
n _nEhzl ,
Ten8@YT=u
ԨL (.uwWXGN{IaP4 [۠ nDZc8bZ By?Lj
1gSL^fr]~,geR-+$+RH]\|~n7 gZ
}FvDUЌaN01o^}W? KVR vlb1tU *暟2H' ?1ƌƱPXSt"@=
sg=maBD9$JhJhFi* O Wo^ݼ~nwj)Qz V `!I$4zLN~0D@(G{#4(h *mص+6"H@J , @\PY`'[ zC1yR ;JR 0̞fѡ3VRN*YzaX45`>fq6ݽ?W\@ x^h}
J#QL جuYJdW|b:L@/V|
ͣM HaRBչC `R13̶ݼH&,|LM=~ f = d9+aH*"Sپ>ۯ\]s+fQ~sr~ 99U4lJGhzu~/zr yyA P`\*^Am%$)CԐJeRjc5%>0F@n#u*%;zJv$-uKw]~~(c7 p$J:>X~tsu($2uئ] Üh2 F I۫o^}W큑s:ݖioo0Nq$H[=Ѱ@L"`K "L ` IbMS'M.ٙAF$n>1K= o!1w ܛ~ʜ7@ =>PkԤ9(<8Kb)zGO.xI9.;I?]L%n:M{/wz 7KY(XÏs\Ǘ >A} P[ww`-cq5$Xjq~B"I$pk[.Z-MǩTYfpD3K%]oet<7LB0RdHR42
6DBn(h4T_,PeZ,-M\n"OdFC Fe p AcaPXa .YYָa<2!*Fe
]&C$l,?ͭLhi(f;xZ5Ty}{?}IE6VJ뜔D%Zr 9``&IpQ}0=R:@IḮIj@Dh!$anmF%-UR>B DhR̯.n~ɰXk r(#*m F#\ u[Xݡpicoocy4Er p3Z%(S%n#s4 DE4I-"0PC
R]]PHP"g:%A|s&#oyx?n)!h<%-yEpXsE&CsPm_)}tԡt8 n;%)|mAFjÝm&T#x9r$EC 7@Y}\-',KI,9kYٽ:W{2/T81G/
{[.MyIF g|$ܛP>) o2܃h|H]RO>y>ތ}g)9r%47 ֭χʃ@RDB{f`Va:η*aqcYy
ӹiVe DmxF
@1XD ;tTU'0H{(:(K(hd` L $oD'SM9[kj2?6)9'hx+!O٪0!W}Lz$QjeaPVɄG|H{^?O
5 &9ͧSjop嗟}O VC1u ?ч?|}YXؖ0E*@S"F# YgJ3JӜ\wF4y ϱ KQ9~Mx1$)Z]5-_>Kh,iW˝q9XEuEYX*H 6В")]QIcV!o9<6+Bȼg'"Z/YA/X^ؽڿ^3:[1=
*`CG3--0%
g8s5 >Wn/dq)\[% JqZN}|uôk eqRS6bQPD ^k\87f]2 d?=}'ϟ$dMAQʖ&I&8cNH|$ wD%g9T?xL1MೲL ֆ"" I9/2
ڝ`L&D r߈8A.tk6.6gG ]kpG`zя7''UzTwvQB8ޤg$HÔ"?;^2ZBpp9T`ˋ]s]7g'f}.A&3)`mC%9]$ݨ Q)/PX@v6ۼl,Q7T%iD[hRA8zn5 \PU6fgWwZ?N|Z ^ɛr+G8}@7@J@cglj"ao5t_GLfdҏ kAIcâ(ŀQ^xx[jvs
мn_n.cڣj ͝.ש?nMR2͓tLwq1mB@
v:.6y8; GAU%
5FM~4h{ ]E|ɿydYpx-aXnrݏ5tOY8acH^7&B M#z֎
flo,Y:IHNכ%U K#(X+v5X nnq䍷 E=B*hup/-D.[fР湻".)uCzrym_^m_/.~c l_|vZy 4אц;17>4oN8s0LA!8J8Nu?Y)P-rҡ(Q'^aS͋,Nf љE-7ja4:^uԠ_MXtY:,G~FzJH!3/2mtcSQv3,ƣ"ܼI!}
\^ |q7=_oGhNmu=|Ս$ 82Z֔C%[ҊOH87/sNm՚jx}<ɢ!>2TS
o!
:GZx9LmZ
v˰U& fXC"R9 Z[DTToh$LOxw˟?~{z̞_ Ň;naV6ꏠ [aw!z6c"o
]l8MEׯ/oC.W]~uvJ!nZJ)pn9jggi5VLc]R$ɢle,uH紿C~yy_>. q!6v.9@7&_F= = ϒ@HIwrXr~Ɖ!NH2/YM*^o_'J2NXa?(^x>Md noYVSJC~ Ӆ#[MR,$$Te =jAJ 2
#r[Oy4xR" w0^zCN@7;#~p7|%:8}ww]'}>ڝQMs mg߇;%$u}x7~3ayrt98>`_aN j+YX'Gq{M !Wo|#94 ЙVA
H@h+b:XD!hxbh;64v{9q9ONN ?7~"}SN}!0^ݸ2t 6> vu "y0yj|}8Z wwׇiRNն/iN0Dx0a҃.O
ww>Z)|Xo/_P,-,i#w Ɨ͋|'h糏S.N#О"B`@Ҫ VhadT#0/>w/>U%IFe:I (f 9㶎 ew S)4p[/@ _0 Gׯ"/dBЩzB(U#A9*fxlęRsxy,&%5mo ܣz(Ek0BD_n"Bs< N7ױ U?'{b7X)bׅԆa5+
`x2nR87K)w՛۫7ӮTLJڧS~s`<*ai Nc_c
hʩRNYX QP^
=3X d\9SwNV뗿8/ϟ ';XqzR5H0 C a%9oq&QF%I \mV,/_jZX͝]9#D=pȺKy+#poׇ1/$w"'Tr>{:"M/+"@! [k?>}9s{ Y۩ј%]=Z 3:2aMU. C tL-[b8wdǃ Ap}ɿETLXwwZnV3_w7W˓ y&`n i}fL{ Z9Rt{ݫ|t77~ 蓟nBR
ա;X
3ڔA=B ܐHsNr=;\S^eDŽ4;M0Xb=!%0c y [`lXݼ?Mw^^{E+"yNFtmR+B!#yo/ )J̯Yh:1H*-ɡC(Q Ym@aܪ^4e=ۚ68__{.ؘ& dׯ]oGh)Ӌ7={͛kÁ.!QCЩȲbVGX
ן bPxۖMA.Չ̽6AuMu,7@dMg"vy=,j)ʰZިF(U mnD|yzoOׁA Xuy4E"!;磻}Ea~gO v$e`q`Sɰŀ 0D/X@z˫>dH!gϞbo cb<y z 7ob9o$Őg1 =D=1)D"KG
6Mk&ߒzۦvnX JNK;=4MVjT~o ?O8*q3``w7~p_.뗗ߖqF?\NH^fqzZyy\n`,
Xxk7
1Cq3ɢq?^o^J. ?Mt_e4 -Xet Yy},e;XJwkATww}fVL(aETR@P(W?lwe)
]{/믝'g:;UBWS-)-5 } Su5 PG EWz/z{ɫ 9jN =}
\wdEJ;{[;R c}!ܕE4tiy^')RV
E. j vb՟?\v uoojh^B0]Ⓩ?oMv{Ytր^!.wZ&MXOVCNjџty$QFm%|DG8:PPbz}WƻۛKŇ?})\SfvwgIDRԚvW.)!ױMwf$tƜ/7g?d 89[v6%2eYyq~xç|pr!]yI$"MVZ7$iˀ{nl's:_zzK%#$ٻUV Ľ [_kp-2\fޘ8#gGDGh>ZyY=췇jln
I o_^W0 '}WFU5OO}@l}aҥ܉h="= $QjiJhim
?ĸWXl2r۪EχǏOh馌qyJs7Fߗft*j8x?=ŲIKj%{Hv9w? RYZpj{{o^ a$e2$dK(Rr{ճO ,nᇑџUJgKn%L.}U/"b)Ξ< )9=|p3cg#{IO'}sCf#>&q$85<*Di-c%в* 6?W訩\U⨩_M1: zl'F߹zoyrW ?뻋#ݰ''yտ:>>XnN5mrH hw%[V=ݛ勮O2x;IXNbwQh >3|iI!KPuV#bUK.3G*OZGֈ~&IBM "Reft@ ,~ ^nfw5Xϟ?~2'Aq * ܻA6VoT _NyT9OXN>ySj[^w> <,Vwe}?Y ld /G5Ymt?,|gC' Ϭyio(m0
(qLQ ^\_<{# 臼:;i,:::Y4gpBÛ/?r7 v>K)ibz1Nfs]gnfm pR秉Vϙ djYv}u1i<.]O'OAE`WoDλNk=Z 9H)OjnelTx_o~u:]wq ^tчw]{ .N)őhh}*] h/teX,~stxxZw oF闿^|m.!nX,V ̩->S;̈́S{wD=_2&u[yyKjw"- J,hvH O?8m/^~W_zw < B`^rw(iSijjx䝏6gRҋW+S7,{=}|=z%B$Ԏ]˻חZ}vnӿyy{q?JFs)NyG â'u:$/ #JÁjy؏.zj;!!zT&T\$!$Sz۫gOۯ>i^v>/V#- cx:ﶇ_-;zwQjO~Slo^aPCV$ y p',dJ|Rm$3䳟zzE¼D8wmȽ WjMXǓ~ cOW Gc{FӀpNw*z6lWBjʂ&p~>+)a* b>Nm S 5M L
1j#p(r*[n6g >:^ݛ[>Xv~^ #fG|8g֭k//jf}uvg 3{>fF|1s {[3 1FEb G8$ Mkns}9]|y}} ܇zY twO`|&"%cyΏ] x4>1a}z7VEq<ڢ~?QZ/@ 7x o.u
bӧgO`1!!*NGDfJ5 $:tW wog>Jʱq/? N~ o_~
g'?.y /,06JntH)ޙR7 V+ Qëaa)-Es;'uF< vחM
Xl]v?աNg'CެƘ|r{8 VuZ}n_7DTzٻXO J0ͬ25;|ۑɡ8)9c{B%=E< [ sg/_}綿RXDC/bJpѤV`g?wxu̒` H5~wqz' oa]椢ZƲ
(nG0_T
g~iXx"0 3@|*VODzN!pQmL6/ J侯w>։*y :] èiyvvݛnjn/Z%yd[2u9"+UбGn0Mu)%_ZM.$ Q"琌d.֖tkl#Tռ.\v9nnƋ>.ޜ , v; `{kcAbW>%F` +tp o, cJE\y19ZmRv HcG~a,y } 7J 1x#m1&A+ͻnb+w^1461D,vW Z
8(!_mZ!nx*nX {v''H_}"k:oX-zWmp S L6ONro6]q
BVnl[(0(SBiM(g\2Ij,-WTYC1Lϟ yڬv륫ݕb/>E߯}7(͛Wׯ_
? l!4 ]5"v{D 1nrծK Kt+UY4Ι-zR[&Ju,FJ|"rWOƝ>K uDcM_|o['
,-&
Uvy tG o}MY(8淴Fw O8{Z]6__7_gNE%Z wF7'"L4Gŧo^y_i ._~^</y;0GH)5ɻ ٧|@Og܋Ic)\Y8`p ݡ|'Op^X=u+t RnlHGTb/vڦF $V7g IEgi: 1; ݤqde.gA&_JpZ Lݸ
kj{ H'ª%&gk+]^(n
+$)t7쁮h۽ 5(e}J^kݍ0 }* T;˶Z2^/ .74 ;{ ϓgE 8Q0'őPwZ]r ~]. | %H_˯>͉S$8N=MeHѡQSlSej,۫WOrq8<~>pP(i*ܟv?O||͟nA/pݽ n'I4,$/!q KI
)gv0,TtGaVbAic qX.Qב@klu>{/W//^^_4_=}nq:oox24lXt] jnZ.\_ƺX]Ξ.>N"C6TClSMyLP @J7pNz8?{vw;-d-Tu/%w]Nq
-KMJ:(4Z}:,gO F`
6є1dtbn]hrX|H{?V 9=6<:z"#c_t? moȝ(1 LnᎡGc="%hG" 3T}G `qmn>{RkIm6Itɮ.PGݬ?N/ptyƮv; cCQ'OEUږ'%v/=L,V,Kg9"ʬʬf7&)2% Hd}c X׆ol-CٔQ&CU<sk-_|̖"p }^cd ڦC߀]ZJDg C9Vy q!84B{7Kr\̢ۤ/{?.մ{/ǚ.Ɯ|fx
_m۪2l*^ )ȶn) 5W BCdǪ6Cj^@JI|0W1|u[XBz(JyUU9mR kGlf ˡn1"uSC +(h\Ok_hn Ub'##z^* :S`>.V|;gO*8ۦһl}ޱ͙0*AG8 dX0
%+Y,{4 eIOќ^h즇zw۶OrVk7!*"62 4=6 Ä~u:}]5V30A.L-'.vKPF\Yzr:7]0(&Kn֫fyyͼjّqqqrޝ7?|r}h4ˏ?z|RNME`L3Sks6oRګz4@]Q\-'V -y W:Y-5)l9=dFqciڞDȜ??;}hL 9]kn;h;% [< #)xXpf⻭}ō|%OEٿ>#v]]+ ԟPҧxq>ߙ\xӾ= ?} v? Q|P^pcl AQc\RQkUn6>*BLjAG2': c|1sM2V]&VM"HvI5rr \D,+iMnfb)bv>xE`OId9/||j#.%6dZy簃6]hy rw(@z&`
Ϭ?oYs*:"ȼw?=Fe}Y?.M Y19Hc4CeJ*
Dߊe իW3$ŨDVT%֙\TdWIҭVM! 0{byN2aӡ,H 7UZMG&Ťo.G[w?__]6.kxDžvr^.ɀt$m'O0J6FͻPbTM_Ưz
Vv{yijٶmLr]
FK (U#Vb $9JI4J|5 v9+wpF_Gn#6>@d3^a d ͳxwx
ޗGscr^rdGc%HH9&<ʾ* *֧vۯWmLqzzVWѭ{u)!f8g&DޣلUw΅@8˿7xʅl\Ξ,/buUbL
x5єomJ5"lCsp\I \U8u٣>DR%HFzH&q<]O Djs uT(!^J[ vϋSM-lI4_NlQ@R
m \Ja_s~zg]H#8(By7 HE.:, p0% BTVTLGϿߟo|z:)gg˥'O϶ۼm49ER a sO~4.n||⼟ ܨoM_)ʊA- G ٢o7Ϟ>{M~WbQ7Ln4YD[S7\Ƈˋ`kpuqD}rڵ.O ƮJ۴0ͫE L](#]fU 3 j
1Ǩ]8'xr n^+ff-+;#"cR clV"e; E@`6}zX7`O%'wϒM*tZ92ma~j&vYqa +
RE,DSH(ͤnΚhTKv؎
kR(I:ϋgҎR?4>/N=y!Yr\^۟̕bJגw{UA<|V8a'Ί>VO1 oN-0F{j hr/Mo vgϦ7s梚fɇ7cqp jsyO<8DTtqvl$~ptTwz?Fdչ'gq؛GlKgȕqszy c7^=7jVxEe_^;|J6m{!f%*iͨ*LD.We >)eM*1
R/ yW^{-Gz 2 ;2MҿsVڐTyw-Urb̀,j=ѐ+gp1T&ч\BbP}
*`9ϒ<٬E͔] o؛ J@ͦ<{kJr1M]u_oj?t>W "=hc^c/-y. %
r^ W̭7'9LGYa'8QRV_`^i;ͭ'U;6}".PioHSvT ]^]\4<ߴmw7md[w^ &a5$!
CTLS텺d`481tD0ll1z&oäB5E@4hSco;ne<ၹ[bDzpΌ$2L6'_x \ j<\aKx%5? i!/^=TC V8& A+h6Q%$C&٪HW߈V=Ihm4>_sTO͢9GTqkӞL).ff: U٨fӽb< hBC}>u ;6
͖ eg0j
5NO6ߛ|8%&S@̬Ӕ0mU#jlV9y鋪֔'* A`9\ @$
L)f$ ^RgVfTx^.F%/q>\ۿ;~_N9v%Τfx7(U*sԬj4M."!2"J v2 /d#λ ^4; Ast%FK=i2P,3 B&ؤa(8Pmo[e]4ȒFSĘs^toV*=fVNHt~$ *ʁev)wDيĔ{xngϟ<jJ,1`Kd@ $cmClF qIwno7\w1˿+hE2_J.kQ٭/obj ;Q/F\\O)r]TU ?~xv~7MߟÖJڠ`ٝ^ރ Ї?k2ΫDLІ ]ج܄!.vYf9 xqʮ,C !Pէ"rWeVoKWDzPFj6X֭0W@ x5
T*s-3
0 D>3 0Hw셧} Dd17
FvpΩf2aAO]^l `ܙlTM.|{Vm[8לMH~yr/) |&gr/(H28DH/cL 71v$ʖ f~~$?"
Pct=xV5`AYns `]hPA[IҧRd/.7nA OfO,?.+wxt岛Le) 8Jfm(zMw*QC
s%F(=wp_FI>1}f"dMKgiK`٦màp ~PwifBGN ݒ$lnhd긘 Ȉ▣Ev=ngA9B2R5gC2H*1y,-w?'zCR]n쾳;< ӎ Q8["EI6M5&G{h"Ё9;@
dSV0DLJ?/5$l Lh_܋*!~y4.@JR15WeuȔP toQN,>v 1 +k A]PG s b bR^^t}9S6BzO-ƶ]퉣.nܶg'M;8{Bv|.Y(k(By/8u??;qQ3+B 3T4o5`j u>PK|Y$xS,;W xQibrqK}4xJr<*h<ƄJwS99&ptxL vT%g`~AAHҸ(B40HHri ͒&%4 ;@ HKT3WF DB֨16NzM;/u@/&?|ӱQdJ0XVG rn=ѲI & L'ᬚI }@
00ZRtV~/|\/d߸vuֵ;EY|}OIUV btt+Ibq|#n79#FFzqZV>mSJ !0B?f%F0#nsM EmB%41 ؇ Syz4Qڷ)g@i[Ř5gFPN:xY] *<FO=]]e|.W J}(ĈP2vdYv 1(U'r찧+?<}Ak}>MchwL@sT?/D;X) r.16-r/F9
adUqѯ.FST#1TLdHU1fRf
ѠOWz1 f:0Grs_|"l,w+ |HKfb< v(T|a"$ -R5_Fݸ`
` ރH()^vA3n ('[9/mR5A.z2r{ۯ}H5J Ądx2Sp٤iESMJain> 眪37 qY aӭWh@;
T(vvGgz 9EDD
2awzJS#X"SI 4PʟCzCN}o)#0c'Spҿ_ y@JFLDFl[ DFtxc7DJ
esdP|@N0(ᇆ*] ٰ:J)Y5 Ea\T%7ˋÛ}jWgf{y֫PۦO}>;=5pQG% Ixi2.vba09W 0IbWė`&p`ҏT3Zʎ.gh5'Yh: s&rx^m§6r4M4=g|C3863K2hͻխhf9.Q :*,&3 N5ZUVW>&9$>h9Ç,2!q1
S % PVR.S+/ -\:22@nJ7 "9F.Ǯ舳w #1H IDATS҅(EͦwE?~-j͖MMro ]>~{{gǯP9TRS\LjҎ C(pOoO>%H'N䣤Qſ6{C#R%2S^ˋo/i1Ǩ僽kýG>Gro_k.zyw6JH
TG l;Q+ވ)cJ Ts32V㺲IdV==z 7EY*|%_'s 6zcmwtt"}Ӧfv#G<}nԧFĞH]
You can also add additional HTML attributes; just separate them from your
keyword args using two dashes:
.. code-block:: html
{% load imagekit %}
{% generateimage 'myapp:thumbnail' source=source_file -- alt="A picture of Me" id="mypicture" %}
Not generating HTML image tags? No problem. The tag also functions as an
assignment tag, providing access to the underlying file object:
.. code-block:: html
{% load imagekit %}
{% generateimage 'myapp:thumbnail' source=source_file as th %}
{% endif %}
{% endblock %}
{% block sidebar1 %}{% endblock %}
{% block sidebar2 %}{% endblock %}
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr_small/static/ 0000775 0000000 0000000 00000000000 15252340250 0025750 5 ustar 00root root 0000000 0000000 matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr_small/static/flasky.css_t 0000775 0000000 0000000 00000011001 15252340250 0030272 0 ustar 00root root 0000000 0000000 /*
* flasky.css_t
* ~~~~~~~~~~~~
*
* Sphinx stylesheet -- flasky theme based on nature theme.
*
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
@import url("basic.css");
/* -- page layout ----------------------------------------------------------- */
body {
font-family: 'Georgia', serif;
font-size: 17px;
color: #000;
background: white;
margin: 0;
padding: 0;
}
div.documentwrapper {
float: left;
width: 100%;
}
div.bodywrapper {
margin: 40px auto 0 auto;
width: 700px;
}
hr {
border: 1px solid #B1B4B6;
}
div.body {
background-color: #ffffff;
color: #3E4349;
padding: 0 30px 30px 30px;
}
img.floatingflask {
padding: 0 0 10px 10px;
float: right;
}
div.footer {
text-align: right;
color: #888;
padding: 10px;
font-size: 14px;
width: 650px;
margin: 0 auto 40px auto;
}
div.footer a {
color: #888;
text-decoration: underline;
}
div.related {
line-height: 32px;
color: #888;
}
div.related ul {
padding: 0 0 0 10px;
}
div.related a {
color: #444;
}
/* -- body styles ----------------------------------------------------------- */
a {
color: #004B6B;
text-decoration: underline;
}
a:hover {
color: #6D4100;
text-decoration: underline;
}
div.body {
padding-bottom: 40px; /* saved for footer */
}
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
font-family: 'Garamond', 'Georgia', serif;
font-weight: normal;
margin: 30px 0px 10px 0px;
padding: 0;
}
{% if theme_index_logo %}
div.indexwrapper h1 {
text-indent: -999999px;
background: url({{ theme_index_logo }}) no-repeat center center;
height: {{ theme_index_logo_height }};
}
{% endif %}
div.body h2 { font-size: 180%; }
div.body h3 { font-size: 150%; }
div.body h4 { font-size: 130%; }
div.body h5 { font-size: 100%; }
div.body h6 { font-size: 100%; }
a.headerlink {
color: white;
padding: 0 4px;
text-decoration: none;
}
a.headerlink:hover {
color: #444;
background: #eaeaea;
}
div.body p, div.body dd, div.body li {
line-height: 1.4em;
}
div.admonition {
background: #fafafa;
margin: 20px -30px;
padding: 10px 30px;
border-top: 1px solid #ccc;
border-bottom: 1px solid #ccc;
}
div.admonition p.admonition-title {
font-family: 'Garamond', 'Georgia', serif;
font-weight: normal;
font-size: 24px;
margin: 0 0 10px 0;
padding: 0;
line-height: 1;
}
div.admonition p.last {
margin-bottom: 0;
}
div.highlight{
background-color: white;
}
dt:target, .highlight {
background: #FAF3E8;
}
div.note {
background-color: #eee;
border: 1px solid #ccc;
}
div.seealso {
background-color: #ffc;
border: 1px solid #ff6;
}
div.topic {
background-color: #eee;
}
div.warning {
background-color: #ffe4e4;
border: 1px solid #f66;
}
p.admonition-title {
display: inline;
}
p.admonition-title:after {
content: ":";
}
pre, tt {
font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
font-size: 0.85em;
}
img.screenshot {
}
tt.descname, tt.descclassname {
font-size: 0.95em;
}
tt.descname {
padding-right: 0.08em;
}
img.screenshot {
-moz-box-shadow: 2px 2px 4px #eee;
-webkit-box-shadow: 2px 2px 4px #eee;
box-shadow: 2px 2px 4px #eee;
}
table.docutils {
border: 1px solid #888;
-moz-box-shadow: 2px 2px 4px #eee;
-webkit-box-shadow: 2px 2px 4px #eee;
box-shadow: 2px 2px 4px #eee;
}
table.docutils td, table.docutils th {
border: 1px solid #888;
padding: 0.25em 0.7em;
}
table.field-list, table.footnote {
border: none;
-moz-box-shadow: none;
-webkit-box-shadow: none;
box-shadow: none;
}
table.footnote {
margin: 15px 0;
width: 100%;
border: 1px solid #eee;
}
table.field-list th {
padding: 0 0.8em 0 0;
}
table.field-list td {
padding: 0;
}
table.footnote td {
padding: 0.5em;
}
dl {
margin: 0;
padding: 0;
}
dl dd {
margin-left: 30px;
}
pre {
padding: 0;
margin: 15px -30px;
padding: 8px;
line-height: 1.3em;
padding: 7px 30px;
background: #eee;
border-radius: 2px;
-moz-border-radius: 2px;
-webkit-border-radius: 2px;
}
dl pre {
margin-left: -60px;
padding-left: 60px;
}
tt {
background-color: #ecf0f3;
color: #222;
/* padding: 1px 2px; */
}
tt.xref, a tt {
background-color: #FBFBFB;
}
a:hover tt {
background: #EEE;
}
matthewwithanm-django-imagekit-26cdc9d/docs/_themes/kr_small/theme.conf 0000775 0000000 0000000 00000000270 15252340250 0026434 0 ustar 00root root 0000000 0000000 [theme]
inherit = basic
stylesheet = flasky.css
nosidebar = true
pygments_style = flask_theme_support.FlaskyStyle
[options]
index_logo = ''
index_logo_height = 120px
github_fork = ''
matthewwithanm-django-imagekit-26cdc9d/docs/advanced_usage.rst 0000664 0000000 0000000 00000016004 15252340250 0024715 0 ustar 00root root 0000000 0000000 Advanced Usage
**************
Models
======
The ``ImageSpecField`` Shorthand Syntax
---------------------------------------
If you've read the README, you already know what an ``ImageSpecField`` is and
the basics of defining one:
.. code-block:: python
from django.db import models
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
processors=[ResizeToFill(100, 50)],
format='JPEG',
options={'quality': 60})
This will create an ``avatar_thumbnail`` field which is a resized version of the
image stored in the ``avatar`` image field. But this is actually just shorthand
for creating an ``ImageSpec``, registering it, and associating it with an
``ImageSpecField``:
.. code-block:: python
from django.db import models
from imagekit import ImageSpec, register
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill
class AvatarThumbnail(ImageSpec):
processors = [ResizeToFill(100, 50)]
format = 'JPEG'
options = {'quality': 60}
register.generator('myapp:profile:avatar_thumbnail', AvatarThumbnail)
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
id='myapp:profile:avatar_thumbnail')
Obviously, the shorthand version is a lot, well…shorter. So why would you ever
want to go through the trouble of using the long form? The answer is that the
long form—creating an image spec class and registering it—gives you a lot more
power over the generated image.
.. _dynamic-specs:
Specs That Change
-----------------
As you'll remember from the README, an image spec is just a type of image
generator that generates a new image from a source image. How does the image
spec get access to the source image? Simple! It's passed to the constructor as
a keyword argument and stored as an attribute of the spec. Normally, we don't
have to concern ourselves with this; the ``ImageSpec`` knows what to do with the
source image and we're happy to let it do its thing. However, having access to
the source image in our spec class can be very useful…
Often, when using an ``ImageSpecField``, you may want the spec to vary based on
properties of a model. (For example, you might want to store image dimensions on
the model and then use them to generate your thumbnail.) Now that we know how to
access the source image from our spec, it's a simple matter to extract its model
and use it to create our processors list. In fact, ImageKit includes a utility
for getting this information.
.. code-block:: python
:emphasize-lines: 11-14
from django.db import models
from imagekit import ImageSpec, register
from imagekit.models import ImageSpecField
from imagekit.processors import ResizeToFill
from imagekit.utils import get_field_info
class AvatarThumbnail(ImageSpec):
format = 'JPEG'
options = {'quality': 60}
@property
def processors(self):
model, field_name = get_field_info(self.source)
return [ResizeToFill(model.thumbnail_width, model.thumbnail_height)]
register.generator('myapp:profile:avatar_thumbnail', AvatarThumbnail)
class Profile(models.Model):
avatar = models.ImageField(upload_to='avatars')
avatar_thumbnail = ImageSpecField(source='avatar',
id='myapp:profile:avatar_thumbnail')
thumbnail_width = models.PositiveIntegerField()
thumbnail_height = models.PositiveIntegerField()
Now each avatar thumbnail will be resized according to the dimensions stored on
the model!
Of course, processors aren't the only thing that can vary based on the model of
the source image; spec behavior can change in any way you want.
.. _source-groups:
Source Groups
=============
When you run the ``generateimages`` management command, how does ImageKit know
which source images to use with which specs? Obviously, when you define an
ImageSpecField, the source image is being connected to a spec, but what's going
on underneath the hood?
The answer is that, when you define an ImageSpecField, ImageKit automatically
creates and registers an object called a *source group*. Source groups are
responsible for two things:
1. They dispatch signals when a source is saved, and
2. They expose a generator method that enumerates source files.
When these objects are registered (using ``imagekit.register.source_group()``),
their signals will trigger callbacks on the cache file strategies associated
with image specs that use the source. (So, for example, you can chose to
generate a file every time the source image changes.) In addition, the generator
method is used (indirectly) to create the list of files to generate with the
``generateimages`` management command.
Currently, there is only one source group class bundled with ImageKit—the one
used by ImageSpecFields. This source group
(``imagekit.specs.sourcegroups.ImageFieldSourceGroup``) represents an ImageField
on every instance of a particular model. In terms of the above description, the
instance ``ImageFieldSourceGroup(Profile, 'avatar')`` 1) dispatches a signal
every time the image in Profile's avatar ImageField changes, and 2) exposes a
generator method that iterates over every Profile's "avatar" image.
Chances are, this is the only source group you will ever need to use, however,
ImageKit lets you define and register custom source groups easily. This may be
useful, for example, if you're using the template tags "generateimage" and
"thumbnail" and the optimistic cache file strategy. Again, the purpose is
to tell ImageKit which specs are used with which sources (so the
"generateimages" management command can generate those files) and when the
source image has been created or changed (so that the strategy has the
opportunity to act on it).
A simple example of a custom source group class is as follows:
.. code-block:: python
import glob
import os
class JpegsInADirectory(object):
def __init__(self, dir):
self.dir = dir
def files(self):
os.chdir(self.dir)
for name in glob.glob('*.jpg'):
yield open(name, 'rb')
Instances of this class could then be registered with one or more spec id:
.. code-block:: python
from imagekit import register
register.source_group('myapp:profile:avatar_thumbnail', JpegsInADirectory('/path/to/some/pics'))
Running the "generateimages" management command would now cause thumbnails to be
generated (using the "myapp:profile:avatar_thumbnail" spec) for each of the
JPEGs in `/path/to/some/pics`.
Note that, since this source group doesnt send the `source_saved` signal, the
corresponding cache file strategy callbacks would not be called for them.
matthewwithanm-django-imagekit-26cdc9d/docs/caching.rst 0000664 0000000 0000000 00000027111 15252340250 0023361 0 ustar 00root root 0000000 0000000 Caching
*******
Default Backend Workflow
========================
``ImageSpec``
-------------
At the heart of ImageKit are image generators. These are classes with a
``generate()`` method which returns an image file. An image spec is a type of
image generator. The thing that makes specs special is that they accept a source
image. So an image spec is just an image generator that makes an image from some
other image.
``ImageCacheFile``
------------------
However, an image spec by itself would be vastly inefficient. Every time an
an image was accessed in some way, it would have be regenerated and saved.
Most of the time, you want to re-use a previously generated image, based on the
input image and spec, instead of generating a new one. That's where
``ImageCacheFile`` comes in. ``ImageCacheFile`` is a File-like object that
wraps an image generator. They look and feel just like regular file
objects, but they've got a little trick up their sleeve: they represent files
that may not actually exist!
.. _cache-file-strategy:
Cache File Strategy
-------------------
Each ``ImageCacheFile`` has a cache file strategy, which abstracts away when
image is actually generated. It can implement the following three methods:
* ``on_content_required`` - called by ``ImageCacheFile`` when it requires the
contents of the generated image. For example, when you call ``read()`` or
try to access information contained in the file.
* ``on_existence_required`` - called by ``ImageCacheFile`` when it requires the
generated image to exist but may not be concerned with its contents. For
example, when you access its ``url`` or ``path`` attribute.
* ``on_source_saved`` - called when the source of a spec is saved
The default strategy only defines the first two of these, as follows:
.. code-block:: python
class JustInTime(object):
def on_content_required(self, file):
file.generate()
def on_existence_required(self, file):
file.generate()
.. _cache-file-backend:
Cache File Backend
------------------
The ``generate`` method on the ``ImageCacheFile`` is further delegated to the
cache file backend, which abstracts away how an image is generated.
The cache file backend defaults to the setting
``IMAGEKIT_DEFAULT_CACHEFILE_BACKEND`` and can be set explicitly on a spec with
the ``cachefile_backend`` attribute.
The default works like this:
* Checks the file storage to see if a file exists
* If not, caches that information for 5 seconds
* If it does, caches that information in the ``IMAGEKIT_CACHE_BACKEND``
If file doesn't exist, generates it immediately and synchronously
That pretty much covers the architecture of the caching layer, and its default
behavior. I like the default behavior. When will an image be regenerated?
Whenever it needs to be! When will your storage backend get hit? Depending on
your ``IMAGEKIT_CACHE_BACKEND`` settings, as little as twice per file (once for the
existence check and once to save the generated file). What if you want to change
a spec? The generated file name (which is used as part of the cache keys) vary
with the source file name and spec attributes, so if you change any of those, a
new file will be generated. The default behavior is easy!
.. note::
Like regular Django ImageFields, IK doesn't currently cache width and height
values, so accessing those will always result in a read. That will probably
change soon though.
Optimizing
==========
There are several ways to improve the performance (reduce I/O operations) of
ImageKit. Each has its own pros and cons.
Caching Data About Generated Files
----------------------------------
Generally, once a file is generated, you will never be removing it, so by
default ImageKit will use default cache to cache the state of generated
files "forever" (or only 5 minutes when ``DEBUG = True``).
The time for which ImageKit will cache state is configured with
``IMAGEKIT_CACHE_TIMEOUT``. If set to ``None`` this means "never expire"
(default when ``DEBUG = False``). You can reduce this timeout if you want
or set it to some numeric value in seconds if your cache backend behaves
differently and for example do not cache values if timeout is ``None``.
If you clear your cache durring deployment or some other reason probably
you do not want to lose the cache for generated images especcialy if you
are using some slow remote storage (like Amazon S3). Then you can configure
separate cache (for example redis) in your ``CACHES`` config and tell ImageKit
to use it instead of the default cache by setting ``IMAGEKIT_CACHE_BACKEND``.
Pre-Generating Images
---------------------
The default cache file backend generates images immediately and synchronously.
If you don't do anything special, that will be when they are first requested—as
part of request-response cycle. This means that the first visitor to your page
will have to wait for the file to be created before they see any HTML.
This can be mitigated, though, by simply generating the images ahead of time, by
running the ``generateimages`` management command.
.. note::
If using with template tags, be sure to read :ref:`source-groups`.
Reducing Cache Backend Round Trips
----------------------------------
When rendering pages with many images, ImageKit performs one cache lookup per image
to check the cachefile state (so a page with 50 images can cause 50 cache round
trips). This can become a major request latency problem, and is highly sensitive to
the network latency to the cache.
To reduce this overhead, ImageKit provides a set of APIs that can be used to prefetch
cache states into a request-local state cache using a single ``cache.get_many()``
call:
.. code-block:: python
from imagekit.cachefiles.state import use_cachefile_state_cache, prefetch_cachefile_states
def gallery(request):
images = list(Image.objects.filter(...)[:50])
# Construct ImageCacheFile objects. (No cache request yet)
thumbs = [img.thumbnail for img in images]
# Create a request-local mapping and prefetch states
state_cache = {}
with use_cachefile_state_cache(state_cache):
prefetch_cachefile_states(thumbs, state_cache=state_cache)
return render(request, "gallery.html", {"images": images})
How it works:
1. ``use_cachefile_state_cache()`` activates a request-local in-memory cache
for the duration of the context (a plain dict is typically used).
2. ``prefetch_cachefile_states()`` fetches all cache file states in a single
``cache.get_many()`` call and stores them in the state cache.
3. During template rendering, ``ImageCacheFile.url`` accesses check the state
cache first before calling ``cache.get()``, so prefetched keys incur no
additional cache round trips.
Deferring Image Generation
--------------------------
As mentioned above, image generation is normally done synchronously. through
the default cache file backend. However, you can also take advantage of
deferred generation. In order to do this, you'll need to do two things:
1) install `celery`__ (or `django-celery`__ if you are bound to Celery<3.1)
2) tell ImageKit to use the async cachefile backend.
To do this for all specs, set the ``IMAGEKIT_DEFAULT_CACHEFILE_BACKEND`` in
your settings
.. code-block:: python
IMAGEKIT_DEFAULT_CACHEFILE_BACKEND = 'imagekit.cachefiles.backends.Async'
Images will now be generated asynchronously. But watch out! Asynchrounous
generation means you'll have to account for images that haven't been generated
yet. You can do this by checking the truthiness of your files; if an image
hasn't been generated, it will be falsy:
.. code-block:: html
{% if not profile.avatar_thumbnail %}
{% else %}
You can add additional attributes to the tag using "--". For example,
this::
{% generateimage 'myapp:thumbnail' source=mymodel.profile_image -- alt="Hello!" %}
will result in the following markup::