dmcquay / django-irs Goto Github PK

django-irs
Image Rendering Service for Django


DESCRIPTION

Provides on-the-fly image manipulation based on the URL used to access the image. Also provides a utility to generate those URLs for you. The basic use case is that you want to allow images to be uploaded to your website and you want to be able to display those images at various sizes on your site. Manipulation is done using PIL.

The manipulated images are cached (using the cache method you have configured in django) and 304 responses are served appropriately, so the service performs fairly well. However, this is not intended for large-scale use. It is a perfect solution for small to medium websites.


INSTALLATION

    python setup.py install

    You could also just add django-irs directory to your PYTHONPATH, which may
    be better for you if you choose to clone the repository so you always have
    the current code.


USAGE

1) Include the IRS url conf in your url conf.

    urlpatterns = patterns('',
        ...
        (^r'irs/', include('irs.urls')),
        ...
    )

2) Store your images somewhere in MEDIA_ROOT. When you give django-irs an image path, it should be relative to this directory. This is the default behavior of django, so this should be a simple task.

3) Use the ImageURL object to generate your image URL. All the methods of ImageURL can be chained.

    from irs.util import ImageURL
    image_path = 'portraits/dustin.jpg'
    url = ImageURL(image_path).resize(width=100, height=100).url()


IMAGE MANIPULATION METHODS

These are the methods you can call on the ImageURL object to manipulate the image.

resize(small, width, height):

    Resizes the image to the maximum dimensions provided.

        small - the max dimension for the smallest original dimension
        width - the maximum width
        height - the maximum height

    Only one must be specified. small will trump width & height. In all cases the aspect ratio of the image will be preserved.

square_center_crop(size)

    Creates a square image of the given size. It will be taken from the center of the original image. It is often useful to resize the image before doing this to ensure the result is not an incredibly small piece of the image. For example, taking a 200px square center crop out of a 1200px image would probably look bad.


INLINE DOCUMENTATION

This code uses inline documentation which can be viewed by using pydoc. However, for example, if you run

    pydoc irs.views

You will likely get the following error: 

    problem in irs.views - <type 'exceptions.ImportError'>: Settings cannot be imported, because environment variable DJANGO_SETTINGS_MODULE is undefined.

To get around this, use the default django global settings and then run pydoc.

    export DJANGO_SETTINGS_MODULE=django.conf.global_settings
    pydoc irs.views


CONTRIBUTING

The main pieces are in place, but the are very few image manipulation functions currently available. Adding more of these would be an easy way to help. However, I'm sure you can find lots of other ways to improve my code.


TODO (In rough order of priority)

  * There are no unit or integration tests
  * Docs are lacking a bit
  * Add API for storing files, so that this could be used as a standalone service
    * It would be nice if the API could be accessed directly via python (for local usage) as well
      as an HTTP REST API.
    * Might as well also provide a REST Client class to make accessing the API w/
      Python easy.
  * Add more image manipulation options


SEE ALSO

    PIL