diff --git a/docs/advanced_usage/optimizing.rst b/docs/advanced_usage/optimizing.rst index ca5ef85..d1f847b 100644 --- a/docs/advanced_usage/optimizing.rst +++ b/docs/advanced_usage/optimizing.rst @@ -41,8 +41,58 @@ called *generated file strategies*. The default strategy can be set using the ``IMAGEKIT_DEFAULT_GENERATEDFILE_STRATEGY`` setting, and its default value is `'imagekit.generatedfiles.strategies.JustInTime'`. As we've already seen above, the "just in time" strategy determines whether a file needs to be generated each -time it's accessed and, if it does, generates it synchronously. +time it's accessed and, if it does, generates it synchronously (that is, as part +of the request-response cycle). + +Another strategy is to simply assume the file exists. This requires the fewest +number of checks (zero!), so we don't have to worry about expensive IO. The +strategy that takes this approach is +``imagekit.generatedfiles.strategies.Optimistic``. In order to use this +strategy, either set the ``IMAGEKIT_DEFAULT_GENERATEDFILE_STRATEGY`` setting or, +to use it on a per-generator basis, set the ``generatedfile_strategy`` attribute +of your spec or generator. Avoiding checking for file existence can be a real +boon to performance, but it also means that ImageKit has no way to know when a +file needs to be generated—well, at least not all the time. + +With image specs, we can know at least some of the times that a new file needs +to be generated: whenever the source image is created or changed. For this +reason, the optimistic strategy defines callbacks for these events. Every +`source registered with ImageKit`__ will automatically cause its specs' files to +be generated when it is created or changed. + +.. note:: + + In order to understand source registration, read :ref:`source-groups` + +If you have specs that `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.generatedfiles import LazyGeneratedImageFile + + file = LazyGeneratedImageFile('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. __ https://docs.djangoproject.com/en/dev/ref/files/storage/ +__ +__ diff --git a/docs/advanced_usage/source_groups.rst b/docs/advanced_usage/source_groups.rst new file mode 100644 index 0000000..36fff33 --- /dev/null +++ b/docs/advanced_usage/source_groups.rst @@ -0,0 +1,24 @@ +.. _source-groups: + +ImageKit allows you to register objects—called *source groups*—which do two +things: 1) dispatch signals when a source is created, changed, or deleted, and +2) 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 generated file strategies associated with image specs +that use the source. 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, +``imagekit.specs.sourcegroups.ImageFieldSourceGroup``, which represents an +ImageField on every instance of a particular model. In terms of the above +description, ``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. + +ImageKit automatically creates and registers an instance of +ImageFieldSourceGroup every time you create an ImageSpecField; that's how the +field is connected (internally) to the spec you're defining, and therefore to +the generated file strategy responsible for generating the file. It's also how +the ``generateimages`` management command is able to know which sources to +generate files for.