diff -r 5ff1fc726848 -r c6bca38c1cbf parts/django/docs/topics/files.txt
--- /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`.