============
dj-upload-to
============

.. image:: https://badge.fury.io/py/dj-upload-to.png
    :target: http://badge.fury.io/py/dj-upload-to
    :alt:

.. image:: https://travis-ci.org/marazmiki/dj-upload-to.png?branch=master
    :target: https://travis-ci.org/marazmiki/dj-upload-to
    :alt: Travis CI build status

.. image:: https://coveralls.io/repos/marazmiki/dj-upload-to/badge.png?branch=master
    :target: https://coveralls.io/r/marazmiki/dj-upload-to?branch=master
    :alt: Code coverage percentage

.. image:: https://pypip.in/d/dj-upload-to/badge.png
    :target: https://pypi.python.org/pypi/dj-upload-to
    :alt: Latest version on PyPI

.. image:: https://pypip.in/wheel/dj-upload-to/badge.svg
    :target: https://pypi.python.org/pypi/dj-upload-to/
    :alt: Wheel Status

.. image:: https://pypip.in/py_versions/dj-upload-to/badge.png
    :target: https://pypi.python.org/pypi/dj-upload-to/
    :alt: Supported Python versions

Synopsis
--------
	
Small application that simplifies naming of uploaded files.
License is MIT.


Installation
------------

You can get `dj-upload-to` release version from pypi with `pip`:

.. code:: bash

    $ pip install dj-upload-to

or development one from github:

.. code:: bash

    $ pip install -e git+https://github.com/marazmiki/dj-upload-to#egg=dj-upload-url

You're not need include it into your `INSTALLED_APPS`


Usage
-----

Assumes you have model:

.. code:: python

    from django.db import models
    from dj_upload_to import UploadTo

    upload_to = UploadTo()

    class Model(models.Model):
        file = models.ImageField(upload_to=upload_to)


As you see, `UploadTo` generates callable object (with `__call__` methodfor passing into `upload_to` attribute of FileField (see `django upload_to docs <https://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.FileField.upload_to>`_ for details)

When you save model with image originally named `myphoto.JPG`, file 
will be saved with name such as:

.. code:: bash

    model/ab/cd/abcdabcd-0123-4567-8901-234567890ab.jpg

where:

* `model` is prefix automatically generated from model class. You can override it
* `ab` is the first 2 char segment of filename
* `cd` is the second 2 char segment of filename
* `abcdabcd-0123-4567-8901-234567890ab` autogenerated with `uuid` filename
* `.jpg` is a lower cased extension taken from original file

Customize
---------

You can customize behavior of `UploadTo` with options in constructor:

* `prefix`: prefix of filename. Default is `None`. If `None`, prefix will be generated by model class name
* `num_seg`: number of parts of segmentation. Default is `2`
* `seg_size`: length of segment in chars. Default is `2`
* `save_name`: use original name without autogeneration. Default is `False`

There are some examples:

.. code:: python

    >>> model = Model()

    >>> UploadTo(prefix='my_files')(model_instance, 'file.jpg')
    u'my_files/d9/a4/d9a4ef25-11b0-41bb-a543-baaac6553024.jpg'

    >>> UploadTo(num_seg=4)(model_instance, 'file.jpg')
    u'model/36/52/99/f6/365299f6-8dc5-4ca2-848d-965f002a9b72.jpg'

    >>> UploadTo(seg_size=4)(model_instance, 'file.jpg')
    u'model/3142/f2ef/3142f2ef-2680-4a99-82fc-3c8d9d3179dc.jpg'

    >>> UploadTo(save_name=True)(model_instance, 'file.jpg')
    u'model/file.jpg'


Contributing
------------

Ideas, bugfixes, pull requests are welcome on `GitHub <https://github.com/marazmiki/dj-upload-to>`_

