PageRenderTime 102ms CodeModel.GetById 47ms app.highlight 2ms RepoModel.GetById 51ms app.codeStats 1ms

/docs/topics/files.txt

https://code.google.com/p/mango-py/
Plain Text | 145 lines | 107 code | 38 blank | 0 comment | 0 complexity | 118e0ef3ff6cacbc7bf5116080e6d5f2 MD5 | raw file
  1==============
  2Managing files
  3==============
  4
  5This document describes Django's file access APIs.
  6
  7By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
  8:setting:`MEDIA_URL` settings. The examples below assume that you're using these
  9defaults.
 10
 11However, Django provides ways to write custom `file storage systems`_ that
 12allow you to completely customize where and how Django stores files. The
 13second half of this document describes how these storage systems work.
 14
 15.. _file storage systems: `File storage`_
 16
 17Using files in models
 18=====================
 19
 20When you use a :class:`~django.db.models.FileField` or
 21:class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
 22to deal with that file.
 23
 24Consider the following model, using an :class:`~django.db.models.ImageField` to
 25store a photo::
 26
 27    class Car(models.Model):
 28        name = models.CharField(max_length=255)
 29        price = models.DecimalField(max_digits=5, decimal_places=2)
 30        photo = models.ImageField(upload_to='cars')
 31
 32Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
 33the details of the attached photo::
 34
 35    >>> car = Car.objects.get(name="57 Chevy")
 36    >>> car.photo
 37    <ImageFieldFile: chevy.jpg>
 38    >>> car.photo.name
 39    u'cars/chevy.jpg'
 40    >>> car.photo.path
 41    u'/media/cars/chevy.jpg'
 42    >>> car.photo.url
 43    u'http://media.example.com/cars/chevy.jpg'
 44
 45This object -- ``car.photo`` in the example -- is a ``File`` object, which means
 46it has all the methods and attributes described below.
 47
 48The ``File`` object
 49===================
 50
 51Internally, Django uses a :class:`django.core.files.File` instance any time it
 52needs to represent a file. This object is a thin wrapper around Python's
 53`built-in file object`_ with some Django-specific additions.
 54
 55.. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
 56
 57Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
 58file attached to a model as above, or perhaps an uploaded file).
 59
 60If you need to construct a ``File`` yourself, the easiest way is to create one
 61using a Python built-in ``file`` object::
 62
 63    >>> from django.core.files import File
 64
 65    # Create a Python file object using open()
 66    >>> f = open('/tmp/hello.world', 'w')
 67    >>> myfile = File(f)
 68
 69Now you can use any of the documented attributes and methods
 70of the :class:`~django.core.files.File` class.
 71
 72File storage
 73============
 74
 75Behind the scenes, Django delegates decisions about how and where to store files
 76to a file storage system. This is the object that actually understands things
 77like file systems, opening and reading files, etc.
 78
 79Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`
 80setting; if you don't explicitly provide a storage system, this is the one that
 81will be used.
 82
 83See below for details of the built-in default file storage system, and see
 84:doc:`/howto/custom-file-storage` for information on writing your own file
 85storage system.
 86
 87Storage objects
 88---------------
 89
 90Though most of the time you'll want to use a ``File`` object (which delegates to
 91the proper storage for that file), you can use file storage systems directly.
 92You can create an instance of some custom file storage class, or -- often more
 93useful -- you can use the global default storage system::
 94
 95    >>> from django.core.files.storage import default_storage
 96    >>> from django.core.files.base import ContentFile
 97
 98    >>> path = default_storage.save('/path/to/file', ContentFile('new content'))
 99    >>> path
100    u'/path/to/file'
101
102    >>> default_storage.size(path)
103    11
104    >>> default_storage.open(path).read()
105    'new content'
106
107    >>> default_storage.delete(path)
108    >>> default_storage.exists(path)
109    False
110
111See :doc:`/ref/files/storage` for the file storage API.
112
113The built-in filesystem storage class
114-------------------------------------
115
116Django ships with a built-in ``FileSystemStorage`` class (defined in
117``django.core.files.storage``) which implements basic local filesystem file
118storage. Its initializer takes two arguments:
119
120======================  ===================================================
121Argument                Description
122======================  ===================================================
123``location``            Optional. Absolute path to the directory that will
124                        hold the files. If omitted, it will be set to the
125                        value of your :setting:`MEDIA_ROOT` setting.
126``base_url``            Optional. URL that serves the files stored at this
127                        location. If omitted, it will default to the value
128                        of your :setting:`MEDIA_URL` setting.
129======================  ===================================================
130
131For example, the following code will store uploaded files under
132``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
133
134    from django.db import models
135    from django.core.files.storage import FileSystemStorage
136
137    fs = FileSystemStorage(location='/media/photos')
138
139    class Car(models.Model):
140        ...
141        photo = models.ImageField(storage=fs)
142
143:doc:`Custom storage systems </howto/custom-file-storage>` work the same way:
144you can pass them in as the ``storage`` argument to a
145:class:`~django.db.models.FileField`.