--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/topics/files.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,147 @@
+==============
+Managing files
+==============
+
+.. versionadded:: 1.0
+
+This document describes Django's file access APIs.
+
+By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
+:setting:`MEDIA_URL` settings. The examples below assume that you're using these
+defaults.
+
+However, Django provides ways to write custom `file storage systems`_ that
+allow you to completely customize where and how Django stores files. The
+second half of this document describes how these storage systems work.
+
+.. _file storage systems: `File storage`_
+
+Using files in models
+=====================
+
+When you use a :class:`~django.db.models.FileField` or
+:class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
+to deal with that file.
+
+Consider the following model, using an :class:`~django.db.models.ImageField` to
+store a photo::
+
+ class Car(models.Model):
+ name = models.CharField(max_length=255)
+ price = models.DecimalField(max_digits=5, decimal_places=2)
+ photo = models.ImageField(upload_to='cars')
+
+Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
+the details of the attached photo::
+
+ >>> car = Car.objects.get(name="57 Chevy")
+ >>> car.photo
+ <ImageFieldFile: chevy.jpg>
+ >>> car.photo.name
+ u'cars/chevy.jpg'
+ >>> car.photo.path
+ u'/media/cars/chevy.jpg'
+ >>> car.photo.url
+ u'http://media.example.com/cars/chevy.jpg'
+
+This object -- ``car.photo`` in the example -- is a ``File`` object, which means
+it has all the methods and attributes described below.
+
+The ``File`` object
+===================
+
+Internally, Django uses a :class:`django.core.files.File` instance any time it
+needs to represent a file. This object is a thin wrapper around Python's
+`built-in file object`_ with some Django-specific additions.
+
+.. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
+
+Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
+file attached to a model as above, or perhaps an uploaded file).
+
+If you need to construct a ``File`` yourself, the easiest way is to create one
+using a Python built-in ``file`` object::
+
+ >>> from django.core.files import File
+
+ # Create a Python file object using open()
+ >>> f = open('/tmp/hello.world', 'w')
+ >>> myfile = File(f)
+
+Now you can use any of the documented attributes and methods
+of the :class:`~django.core.files.File` class.
+
+File storage
+============
+
+Behind the scenes, Django delegates decisions about how and where to store files
+to a file storage system. This is the object that actually understands things
+like file systems, opening and reading files, etc.
+
+Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`
+setting; if you don't explicitly provide a storage system, this is the one that
+will be used.
+
+See below for details of the built-in default file storage system, and see
+:doc:`/howto/custom-file-storage` for information on writing your own file
+storage system.
+
+Storage objects
+---------------
+
+Though most of the time you'll want to use a ``File`` object (which delegates to
+the proper storage for that file), you can use file storage systems directly.
+You can create an instance of some custom file storage class, or -- often more
+useful -- you can use the global default storage system::
+
+ >>> from django.core.files.storage import default_storage
+ >>> from django.core.files.base import ContentFile
+
+ >>> path = default_storage.save('/path/to/file', ContentFile('new content'))
+ >>> path
+ u'/path/to/file'
+
+ >>> default_storage.size(path)
+ 11
+ >>> default_storage.open(path).read()
+ 'new content'
+
+ >>> default_storage.delete(path)
+ >>> default_storage.exists(path)
+ False
+
+See :doc:`/ref/files/storage` for the file storage API.
+
+The built-in filesystem storage class
+-------------------------------------
+
+Django ships with a built-in ``FileSystemStorage`` class (defined in
+``django.core.files.storage``) which implements basic local filesystem file
+storage. Its initializer takes two arguments:
+
+====================== ===================================================
+Argument Description
+====================== ===================================================
+``location`` Optional. Absolute path to the directory that will
+ hold the files. If omitted, it will be set to the
+ value of your :setting:`MEDIA_ROOT` setting.
+``base_url`` Optional. URL that serves the files stored at this
+ location. If omitted, it will default to the value
+ of your :setting:`MEDIA_URL` setting.
+====================== ===================================================
+
+For example, the following code will store uploaded files under
+``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
+
+ from django.db import models
+ from django.core.files.storage import FileSystemStorage
+
+ fs = FileSystemStorage(location='/media/photos')
+
+ class Car(models.Model):
+ ...
+ photo = models.ImageField(storage=fs)
+
+:doc:`Custom storage systems </howto/custom-file-storage>` work the same way:
+you can pass them in as the ``storage`` argument to a
+:class:`~django.db.models.FileField`.