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