Debian Codegraph @

django/contrib/staticfiles/finders.py

raw
1 import functools
2 import os
3 import warnings
4
5 from django.apps import apps
6 from django.conf import settings
7 from django.contrib.staticfiles import utils
8 from django.core.checks import Error, Warning
9 from django.core.exceptions import ImproperlyConfigured
10 from django.core.files.storage import FileSystemStorage, Storage, default_storage
11 from django.utils._os import safe_join
12 from django.utils.deprecation import RemovedInDjango61Warning
13 from django.utils.functional import LazyObject, empty
14 from django.utils.module_loading import import_string
15
16 # To keep track on which directories the finder has searched the static files.
17 searched_locations = []
18
19
20 # RemovedInDjango61Warning: When the deprecation ends, remove completely.
21 def _check_deprecated_find_param(class_name="", find_all=False, stacklevel=3, **kwargs):
22 method_name = "find" if not class_name else f"{class_name}.find"
23 if "all" in kwargs:
24 legacy_all = kwargs.pop("all")
25 msg = (
26 "Passing the `all` argument to find() is deprecated. Use `find_all` "
27 "instead."
28 )
29 warnings.warn(msg, RemovedInDjango61Warning, stacklevel=stacklevel)
30
31 # If both `find_all` and `all` were given, raise TypeError.
32 if find_all is not False:
33 raise TypeError(
34 f"{method_name}() got multiple values for argument 'find_all'"
35 )
36
37 find_all = legacy_all
38
39 if kwargs: # any remaining kwargs must be a TypeError
40 first = list(kwargs.keys()).pop()
41 raise TypeError(f"{method_name}() got an unexpected keyword argument '{first}'")
42
43 return find_all
44
45
46 class BaseFinder:
47 """
48 A base file finder to be used for custom staticfiles finder classes.
49 """
50
51 def check(self, **kwargs):
52 raise NotImplementedError(
53 "subclasses may provide a check() method to verify the finder is "
54 "configured correctly."
55 )
56
57 # RemovedInDjango61Warning: When the deprecation ends, remove completely.
58 def _check_deprecated_find_param(self, **kwargs):
59 return _check_deprecated_find_param(
60 class_name=self.__class__.__qualname__, stacklevel=4, **kwargs
61 )
62
63 # RemovedInDjango61Warning: When the deprecation ends, replace with:
64 # def find(self, path, find_all=False):
65 def find(self, path, find_all=False, **kwargs):
66 """
67 Given a relative file path, find an absolute file path.
68
69 If the ``find_all`` parameter is False (default) return only the first
70 found file path; if True, return a list of all found files paths.
71 """
72 raise NotImplementedError(
73 "subclasses of BaseFinder must provide a find() method"
74 )
75
76 def list(self, ignore_patterns):
77 """
78 Given an optional list of paths to ignore, return a two item iterable
79 consisting of the relative path and storage instance.
80 """
81 raise NotImplementedError(
82 "subclasses of BaseFinder must provide a list() method"
83 )
84
85
86 class FileSystemFinder(BaseFinder):
87 """
88 A static files finder that uses the ``STATICFILES_DIRS`` setting
89 to locate files.
90 """
91
92 def __init__(self, app_names=None, *args, **kwargs):
93 # List of locations with static files
94 self.locations = []
95 # Maps dir paths to an appropriate storage instance
96 self.storages = {}
97 for root in settings.STATICFILES_DIRS:
98 if isinstance(root, (list, tuple)):
99 prefix, root = root
100 else:
101 prefix = ""
102 if (prefix, root) not in self.locations:
103 self.locations.append((prefix, root))
104 for prefix, root in self.locations:
105 filesystem_storage = FileSystemStorage(location=root)
106 filesystem_storage.prefix = prefix
107 self.storages[root] = filesystem_storage
108 super().__init__(*args, **kwargs)
109
110 def check(self, **kwargs):
111 errors = []
112 if not isinstance(settings.STATICFILES_DIRS, (list, tuple)):
113 errors.append(
114 Error(
115 "The STATICFILES_DIRS setting is not a tuple or list.",
116 hint="Perhaps you forgot a trailing comma?",
117 id="staticfiles.E001",
118 )
119 )
120 return errors
121 for root in settings.STATICFILES_DIRS:
122 if isinstance(root, (list, tuple)):
123 prefix, root = root
124 if prefix.endswith("/"):
125 errors.append(
126 Error(
127 "The prefix %r in the STATICFILES_DIRS setting must "
128 "not end with a slash." % prefix,
129 id="staticfiles.E003",
130 )
131 )
132 if settings.STATIC_ROOT and os.path.abspath(
133 settings.STATIC_ROOT
134 ) == os.path.abspath(root):
135 errors.append(
136 Error(
137 "The STATICFILES_DIRS setting should not contain the "
138 "STATIC_ROOT setting.",
139 id="staticfiles.E002",
140 )
141 )
142 if not os.path.isdir(root):
143 errors.append(
144 Warning(
145 f"The directory '{root}' in the STATICFILES_DIRS setting "
146 f"does not exist.",
147 id="staticfiles.W004",
148 )
149 )
150 return errors
151
152 # RemovedInDjango61Warning: When the deprecation ends, replace with:
153 # def find(self, path, find_all=False):
154 def find(self, path, find_all=False, **kwargs):
155 """
156 Look for files in the extra locations as defined in STATICFILES_DIRS.
157 """
158 # RemovedInDjango61Warning.
159 if kwargs:
160 find_all = self._check_deprecated_find_param(find_all=find_all, **kwargs)
161 matches = []
162 for prefix, root in self.locations:
163 if root not in searched_locations:
164 searched_locations.append(root)
165 matched_path = self.find_location(root, path, prefix)
166 if matched_path:
167 if not find_all:
168 return matched_path
169 matches.append(matched_path)
170 return matches
171
172 def find_location(self, root, path, prefix=None):
173 """
174 Find a requested static file in a location and return the found
175 absolute path (or ``None`` if no match).
176 """
177 if prefix:
178 prefix = "%s%s" % (prefix, os.sep)
179 if not path.startswith(prefix):
180 return None
181 path = path.removeprefix(prefix)
182 path = safe_join(root, path)
183 if os.path.exists(path):
184 return path
185
186 def list(self, ignore_patterns):
187 """
188 List all files in all locations.
189 """
190 for prefix, root in self.locations:
191 # Skip nonexistent directories.
192 if os.path.isdir(root):
193 storage = self.storages[root]
194 for path in utils.get_files(storage, ignore_patterns):
195 yield path, storage
196
197
198 class AppDirectoriesFinder(BaseFinder):
199 """
200 A static files finder that looks in the directory of each app as
201 specified in the source_dir attribute.
202 """
203
204 storage_class = FileSystemStorage
205 source_dir = "static"
206
207 def __init__(self, app_names=None, *args, **kwargs):
208 # The list of apps that are handled
209 self.apps = []
210 # Mapping of app names to storage instances
211 self.storages = {}
212 app_configs = apps.get_app_configs()
213 if app_names:
214 app_names = set(app_names)
215 app_configs = [ac for ac in app_configs if ac.name in app_names]
216 for app_config in app_configs:
217 app_storage = self.storage_class(
218 os.path.join(app_config.path, self.source_dir)
219 )
220 if os.path.isdir(app_storage.location):
221 self.storages[app_config.name] = app_storage
222 if app_config.name not in self.apps:
223 self.apps.append(app_config.name)
224 super().__init__(*args, **kwargs)
225
226 def list(self, ignore_patterns):
227 """
228 List all files in all app storages.
229 """
230 for storage in self.storages.values():
231 if storage.exists(""): # check if storage location exists
232 for path in utils.get_files(storage, ignore_patterns):
233 yield path, storage
234
235 # RemovedInDjango61Warning: When the deprecation ends, replace with:
236 # def find(self, path, find_all=False):
237 def find(self, path, find_all=False, **kwargs):
238 """
239 Look for files in the app directories.
240 """
241 # RemovedInDjango61Warning.
242 if kwargs:
243 find_all = self._check_deprecated_find_param(find_all=find_all, **kwargs)
244 matches = []
245 for app in self.apps:
246 app_location = self.storages[app].location
247 if app_location not in searched_locations:
248 searched_locations.append(app_location)
249 match = self.find_in_app(app, path)
250 if match:
251 if not find_all:
252 return match
253 matches.append(match)
254 return matches
255
256 def find_in_app(self, app, path):
257 """
258 Find a requested static file in an app's static locations.
259 """
260 storage = self.storages.get(app)
261 # Only try to find a file if the source dir actually exists.
262 if storage and storage.exists(path):
263 matched_path = storage.path(path)
264 if matched_path:
265 return matched_path
266
267
268 class BaseStorageFinder(BaseFinder):
269 """
270 A base static files finder to be used to extended
271 with an own storage class.
272 """
273
274 storage = None
275
276 def __init__(self, storage=None, *args, **kwargs):
277 if storage is not None:
278 self.storage = storage
279 if self.storage is None:
280 raise ImproperlyConfigured(
281 "The staticfiles storage finder %r "
282 "doesn't have a storage class "
283 "assigned." % self.__class__
284 )
285 # Make sure we have a storage instance here.
286 if not isinstance(self.storage, (Storage, LazyObject)):
287 self.storage = self.storage()
288 super().__init__(*args, **kwargs)
289
290 # RemovedInDjango61Warning: When the deprecation ends, replace with:
291 # def find(self, path, find_all=False):
292 def find(self, path, find_all=False, **kwargs):
293 """
294 Look for files in the default file storage, if it's local.
295 """
296 # RemovedInDjango61Warning.
297 if kwargs:
298 find_all = self._check_deprecated_find_param(find_all=find_all, **kwargs)
299 try:
300 self.storage.path("")
301 except NotImplementedError:
302 pass
303 else:
304 if self.storage.location not in searched_locations:
305 searched_locations.append(self.storage.location)
306 if self.storage.exists(path):
307 match = self.storage.path(path)
308 if find_all:
309 match = [match]
310 return match
311 return []
312
313 def list(self, ignore_patterns):
314 """
315 List all files of the storage.
316 """
317 for path in utils.get_files(self.storage, ignore_patterns):
318 yield path, self.storage
319
320
321 class DefaultStorageFinder(BaseStorageFinder):
322 """
323 A static files finder that uses the default storage backend.
324 """
325
326 storage = default_storage
327
328 def __init__(self, *args, **kwargs):
329 super().__init__(*args, **kwargs)
330 base_location = getattr(self.storage, "base_location", empty)
331 if not base_location:
332 raise ImproperlyConfigured(
333 "The storage backend of the "
334 "staticfiles finder %r doesn't have "
335 "a valid location." % self.__class__
336 )
337
338
339 # RemovedInDjango61Warning: When the deprecation ends, replace with:
340 # def find(path, find_all=False):
341 def find(path, find_all=False, **kwargs):
342 """
343 Find a static file with the given path using all enabled finders.
344
345 If ``find_all`` is ``False`` (default), return the first matching
346 absolute path (or ``None`` if no match). Otherwise return a list.
347 """
348 # RemovedInDjango61Warning.
349 if kwargs:
350 find_all = _check_deprecated_find_param(find_all=find_all, **kwargs)
351 searched_locations[:] = []
352 matches = []
353 for finder in get_finders():
354 result = finder.find(path, find_all=find_all)
355 if not find_all and result:
356 return result
357 if not isinstance(result, (list, tuple)):
358 result = [result]
359 matches.extend(result)
360 if matches:
361 return matches
362 # No match.
363 return [] if find_all else None
364
365
366 def get_finders():
367 for finder_path in settings.STATICFILES_FINDERS:
368 yield get_finder(finder_path)
369
370
371 @functools.cache
372 def get_finder(import_path):
373 """
374 Import the staticfiles finder class described by import_path, where
375 import_path is the full Python path to the class.
376 """
377 Finder = import_string(import_path)
378 if not issubclass(Finder, BaseFinder):
379 raise ImproperlyConfigured(
380 'Finder "%s" is not a subclass of "%s"' % (Finder, BaseFinder)
381 )
382 return Finder()