|
1 import os |
|
2 import errno |
|
3 import urlparse |
|
4 import itertools |
|
5 |
|
6 from django.conf import settings |
|
7 from django.core.exceptions import ImproperlyConfigured, SuspiciousOperation |
|
8 from django.core.files import locks, File |
|
9 from django.core.files.move import file_move_safe |
|
10 from django.utils.encoding import force_unicode |
|
11 from django.utils.functional import LazyObject |
|
12 from django.utils.importlib import import_module |
|
13 from django.utils.text import get_valid_filename |
|
14 from django.utils._os import safe_join |
|
15 |
|
16 __all__ = ('Storage', 'FileSystemStorage', 'DefaultStorage', 'default_storage') |
|
17 |
|
18 class Storage(object): |
|
19 """ |
|
20 A base storage class, providing some default behaviors that all other |
|
21 storage systems can inherit or override, as necessary. |
|
22 """ |
|
23 |
|
24 # The following methods represent a public interface to private methods. |
|
25 # These shouldn't be overridden by subclasses unless absolutely necessary. |
|
26 |
|
27 def open(self, name, mode='rb', mixin=None): |
|
28 """ |
|
29 Retrieves the specified file from storage, using the optional mixin |
|
30 class to customize what features are available on the File returned. |
|
31 """ |
|
32 file = self._open(name, mode) |
|
33 if mixin: |
|
34 # Add the mixin as a parent class of the File returned from storage. |
|
35 file.__class__ = type(mixin.__name__, (mixin, file.__class__), {}) |
|
36 return file |
|
37 |
|
38 def save(self, name, content): |
|
39 """ |
|
40 Saves new content to the file specified by name. The content should be a |
|
41 proper File object, ready to be read from the beginning. |
|
42 """ |
|
43 # Get the proper name for the file, as it will actually be saved. |
|
44 if name is None: |
|
45 name = content.name |
|
46 |
|
47 name = self.get_available_name(name) |
|
48 name = self._save(name, content) |
|
49 |
|
50 # Store filenames with forward slashes, even on Windows |
|
51 return force_unicode(name.replace('\\', '/')) |
|
52 |
|
53 # These methods are part of the public API, with default implementations. |
|
54 |
|
55 def get_valid_name(self, name): |
|
56 """ |
|
57 Returns a filename, based on the provided filename, that's suitable for |
|
58 use in the target storage system. |
|
59 """ |
|
60 return get_valid_filename(name) |
|
61 |
|
62 def get_available_name(self, name): |
|
63 """ |
|
64 Returns a filename that's free on the target storage system, and |
|
65 available for new content to be written to. |
|
66 """ |
|
67 dir_name, file_name = os.path.split(name) |
|
68 file_root, file_ext = os.path.splitext(file_name) |
|
69 # If the filename already exists, add an underscore and a number (before |
|
70 # the file extension, if one exists) to the filename until the generated |
|
71 # filename doesn't exist. |
|
72 count = itertools.count(1) |
|
73 while self.exists(name): |
|
74 # file_ext includes the dot. |
|
75 name = os.path.join(dir_name, "%s_%s%s" % (file_root, count.next(), file_ext)) |
|
76 |
|
77 return name |
|
78 |
|
79 def path(self, name): |
|
80 """ |
|
81 Returns a local filesystem path where the file can be retrieved using |
|
82 Python's built-in open() function. Storage systems that can't be |
|
83 accessed using open() should *not* implement this method. |
|
84 """ |
|
85 raise NotImplementedError("This backend doesn't support absolute paths.") |
|
86 |
|
87 # The following methods form the public API for storage systems, but with |
|
88 # no default implementations. Subclasses must implement *all* of these. |
|
89 |
|
90 def delete(self, name): |
|
91 """ |
|
92 Deletes the specified file from the storage system. |
|
93 """ |
|
94 raise NotImplementedError() |
|
95 |
|
96 def exists(self, name): |
|
97 """ |
|
98 Returns True if a file referened by the given name already exists in the |
|
99 storage system, or False if the name is available for a new file. |
|
100 """ |
|
101 raise NotImplementedError() |
|
102 |
|
103 def listdir(self, path): |
|
104 """ |
|
105 Lists the contents of the specified path, returning a 2-tuple of lists; |
|
106 the first item being directories, the second item being files. |
|
107 """ |
|
108 raise NotImplementedError() |
|
109 |
|
110 def size(self, name): |
|
111 """ |
|
112 Returns the total size, in bytes, of the file specified by name. |
|
113 """ |
|
114 raise NotImplementedError() |
|
115 |
|
116 def url(self, name): |
|
117 """ |
|
118 Returns an absolute URL where the file's contents can be accessed |
|
119 directly by a web browser. |
|
120 """ |
|
121 raise NotImplementedError() |
|
122 |
|
123 class FileSystemStorage(Storage): |
|
124 """ |
|
125 Standard filesystem storage |
|
126 """ |
|
127 |
|
128 def __init__(self, location=None, base_url=None): |
|
129 if location is None: |
|
130 location = settings.MEDIA_ROOT |
|
131 if base_url is None: |
|
132 base_url = settings.MEDIA_URL |
|
133 self.location = os.path.abspath(location) |
|
134 self.base_url = base_url |
|
135 |
|
136 def _open(self, name, mode='rb'): |
|
137 return File(open(self.path(name), mode)) |
|
138 |
|
139 def _save(self, name, content): |
|
140 full_path = self.path(name) |
|
141 |
|
142 directory = os.path.dirname(full_path) |
|
143 if not os.path.exists(directory): |
|
144 os.makedirs(directory) |
|
145 elif not os.path.isdir(directory): |
|
146 raise IOError("%s exists and is not a directory." % directory) |
|
147 |
|
148 # There's a potential race condition between get_available_name and |
|
149 # saving the file; it's possible that two threads might return the |
|
150 # same name, at which point all sorts of fun happens. So we need to |
|
151 # try to create the file, but if it already exists we have to go back |
|
152 # to get_available_name() and try again. |
|
153 |
|
154 while True: |
|
155 try: |
|
156 # This file has a file path that we can move. |
|
157 if hasattr(content, 'temporary_file_path'): |
|
158 file_move_safe(content.temporary_file_path(), full_path) |
|
159 content.close() |
|
160 |
|
161 # This is a normal uploadedfile that we can stream. |
|
162 else: |
|
163 # This fun binary flag incantation makes os.open throw an |
|
164 # OSError if the file already exists before we open it. |
|
165 fd = os.open(full_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, 'O_BINARY', 0)) |
|
166 try: |
|
167 locks.lock(fd, locks.LOCK_EX) |
|
168 for chunk in content.chunks(): |
|
169 os.write(fd, chunk) |
|
170 finally: |
|
171 locks.unlock(fd) |
|
172 os.close(fd) |
|
173 except OSError, e: |
|
174 if e.errno == errno.EEXIST: |
|
175 # Ooops, the file exists. We need a new file name. |
|
176 name = self.get_available_name(name) |
|
177 full_path = self.path(name) |
|
178 else: |
|
179 raise |
|
180 else: |
|
181 # OK, the file save worked. Break out of the loop. |
|
182 break |
|
183 |
|
184 if settings.FILE_UPLOAD_PERMISSIONS is not None: |
|
185 os.chmod(full_path, settings.FILE_UPLOAD_PERMISSIONS) |
|
186 |
|
187 return name |
|
188 |
|
189 def delete(self, name): |
|
190 name = self.path(name) |
|
191 # If the file exists, delete it from the filesystem. |
|
192 if os.path.exists(name): |
|
193 os.remove(name) |
|
194 |
|
195 def exists(self, name): |
|
196 return os.path.exists(self.path(name)) |
|
197 |
|
198 def listdir(self, path): |
|
199 path = self.path(path) |
|
200 directories, files = [], [] |
|
201 for entry in os.listdir(path): |
|
202 if os.path.isdir(os.path.join(path, entry)): |
|
203 directories.append(entry) |
|
204 else: |
|
205 files.append(entry) |
|
206 return directories, files |
|
207 |
|
208 def path(self, name): |
|
209 try: |
|
210 path = safe_join(self.location, name) |
|
211 except ValueError: |
|
212 raise SuspiciousOperation("Attempted access to '%s' denied." % name) |
|
213 return os.path.normpath(path) |
|
214 |
|
215 def size(self, name): |
|
216 return os.path.getsize(self.path(name)) |
|
217 |
|
218 def url(self, name): |
|
219 if self.base_url is None: |
|
220 raise ValueError("This file is not accessible via a URL.") |
|
221 return urlparse.urljoin(self.base_url, name).replace('\\', '/') |
|
222 |
|
223 def get_storage_class(import_path=None): |
|
224 if import_path is None: |
|
225 import_path = settings.DEFAULT_FILE_STORAGE |
|
226 try: |
|
227 dot = import_path.rindex('.') |
|
228 except ValueError: |
|
229 raise ImproperlyConfigured("%s isn't a storage module." % import_path) |
|
230 module, classname = import_path[:dot], import_path[dot+1:] |
|
231 try: |
|
232 mod = import_module(module) |
|
233 except ImportError, e: |
|
234 raise ImproperlyConfigured('Error importing storage module %s: "%s"' % (module, e)) |
|
235 try: |
|
236 return getattr(mod, classname) |
|
237 except AttributeError: |
|
238 raise ImproperlyConfigured('Storage module "%s" does not define a "%s" class.' % (module, classname)) |
|
239 |
|
240 class DefaultStorage(LazyObject): |
|
241 def _setup(self): |
|
242 self._wrapped = get_storage_class()() |
|
243 |
|
244 default_storage = DefaultStorage() |