148 lines
5.2 KiB
Plaintext
148 lines
5.2 KiB
Plaintext
==============
|
|
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`.
|