Debian Codegraph @

django/core/management/templates.py

raw
1 import argparse
2 import mimetypes
3 import os
4 import posixpath
5 import shutil
6 import stat
7 import tempfile
8 from importlib.util import find_spec
9 from urllib.request import build_opener
10
11 import django
12 from django.conf import settings
13 from django.core.management.base import BaseCommand, CommandError
14 from django.core.management.utils import (
15 find_formatters,
16 handle_extensions,
17 run_formatters,
18 )
19 from django.template import Context, Engine
20 from django.utils import archive
21 from django.utils.http import parse_header_parameters
22 from django.utils.version import get_docs_version
23
24
25 class TemplateCommand(BaseCommand):
26 """
27 Copy either a Django application layout template or a Django project
28 layout template into the specified directory.
29
30 :param style: A color style object (see django.core.management.color).
31 :param app_or_project: The string 'app' or 'project'.
32 :param name: The name of the application or project.
33 :param directory: The directory to which the template should be copied.
34 :param options: The additional variables passed to project or app templates
35 """
36
37 requires_system_checks = []
38 # The supported URL schemes
39 url_schemes = ["http", "https", "ftp"]
40 # Rewrite the following suffixes when determining the target filename.
41 rewrite_template_suffixes = (
42 # Allow shipping invalid .py files without byte-compilation.
43 (".py-tpl", ".py"),
44 )
45
46 def add_arguments(self, parser):
47 parser.add_argument("name", help="Name of the application or project.")
48 parser.add_argument(
49 "directory", nargs="?", help="Optional destination directory"
50 )
51 parser.add_argument(
52 "--template", help="The path or URL to load the template from."
53 )
54 parser.add_argument(
55 "--extension",
56 "-e",
57 dest="extensions",
58 action="append",
59 default=["py"],
60 help='The file extension(s) to render (default: "py"). '
61 "Separate multiple extensions with commas, or use "
62 "-e multiple times.",
63 )
64 parser.add_argument(
65 "--name",
66 "-n",
67 dest="files",
68 action="append",
69 default=[],
70 help="The file name(s) to render. Separate multiple file names "
71 "with commas, or use -n multiple times.",
72 )
73 parser.add_argument(
74 "--exclude",
75 "-x",
76 action="append",
77 default=argparse.SUPPRESS,
78 nargs="?",
79 const="",
80 help=(
81 "The directory name(s) to exclude, in addition to .git and "
82 "__pycache__. Can be used multiple times."
83 ),
84 )
85
86 def handle(self, app_or_project, name, target=None, **options):
87 self.app_or_project = app_or_project
88 self.a_or_an = "an" if app_or_project == "app" else "a"
89 self.paths_to_remove = []
90 self.verbosity = options["verbosity"]
91
92 self.validate_name(name)
93
94 # if some directory is given, make sure it's nicely expanded
95 if target is None:
96 top_dir = os.path.join(os.getcwd(), name)
97 try:
98 os.makedirs(top_dir)
99 except FileExistsError:
100 raise CommandError("'%s' already exists" % top_dir)
101 except OSError as e:
102 raise CommandError(e)
103 else:
104 top_dir = os.path.abspath(os.path.expanduser(target))
105 if app_or_project == "app":
106 self.validate_name(os.path.basename(top_dir), "directory")
107 if not os.path.exists(top_dir):
108 raise CommandError(
109 "Destination directory '%s' does not "
110 "exist, please create it first." % top_dir
111 )
112
113 # Find formatters, which are external executables, before input
114 # from the templates can sneak into the path.
115 formatter_paths = find_formatters()
116
117 extensions = tuple(handle_extensions(options["extensions"]))
118 extra_files = []
119 excluded_directories = [".git", "__pycache__"]
120 for file in options["files"]:
121 extra_files.extend(map(lambda x: x.strip(), file.split(",")))
122 if exclude := options.get("exclude"):
123 for directory in exclude:
124 excluded_directories.append(directory.strip())
125 if self.verbosity >= 2:
126 self.stdout.write(
127 "Rendering %s template files with extensions: %s"
128 % (app_or_project, ", ".join(extensions))
129 )
130 self.stdout.write(
131 "Rendering %s template files with filenames: %s"
132 % (app_or_project, ", ".join(extra_files))
133 )
134 base_name = "%s_name" % app_or_project
135 base_subdir = "%s_template" % app_or_project
136 base_directory = "%s_directory" % app_or_project
137 camel_case_name = "camel_case_%s_name" % app_or_project
138 camel_case_value = "".join(x for x in name.title() if x != "_")
139
140 context = Context(
141 {
142 **options,
143 base_name: name,
144 base_directory: top_dir,
145 camel_case_name: camel_case_value,
146 "docs_version": get_docs_version(),
147 "django_version": django.__version__,
148 },
149 autoescape=False,
150 )
151
152 # Setup a stub settings environment for template rendering
153 if not settings.configured:
154 settings.configure()
155 django.setup()
156
157 template_dir = self.handle_template(options["template"], base_subdir)
158 prefix_length = len(template_dir) + 1
159
160 for root, dirs, files in os.walk(template_dir):
161 path_rest = root[prefix_length:]
162 relative_dir = path_rest.replace(base_name, name)
163 if relative_dir:
164 target_dir = os.path.join(top_dir, relative_dir)
165 os.makedirs(target_dir, exist_ok=True)
166
167 for dirname in dirs[:]:
168 if "exclude" not in options:
169 if dirname.startswith(".") or dirname == "__pycache__":
170 dirs.remove(dirname)
171 elif dirname in excluded_directories:
172 dirs.remove(dirname)
173
174 for filename in files:
175 if filename.endswith((".pyo", ".pyc", ".py.class")):
176 # Ignore some files as they cause various breakages.
177 continue
178 old_path = os.path.join(root, filename)
179 new_path = os.path.join(
180 top_dir, relative_dir, filename.replace(base_name, name)
181 )
182 for old_suffix, new_suffix in self.rewrite_template_suffixes:
183 if new_path.endswith(old_suffix):
184 new_path = new_path.removesuffix(old_suffix) + new_suffix
185 break # Only rewrite once
186
187 if os.path.exists(new_path):
188 raise CommandError(
189 "%s already exists. Overlaying %s %s into an existing "
190 "directory won't replace conflicting files."
191 % (
192 new_path,
193 self.a_or_an,
194 app_or_project,
195 )
196 )
197
198 # Only render the Python files, as we don't want to
199 # accidentally render Django templates files
200 if new_path.endswith(extensions) or filename in extra_files:
201 with open(old_path, encoding="utf-8") as template_file:
202 content = template_file.read()
203 template = Engine().from_string(content)
204 content = template.render(context)
205 with open(new_path, "w", encoding="utf-8") as new_file:
206 new_file.write(content)
207 else:
208 shutil.copyfile(old_path, new_path)
209
210 if self.verbosity >= 2:
211 self.stdout.write("Creating %s" % new_path)
212 try:
213 self.apply_umask(old_path, new_path)
214 self.make_writeable(new_path)
215 except OSError:
216 self.stderr.write(
217 "Notice: Couldn't set permission bits on %s. You're "
218 "probably using an uncommon filesystem setup. No "
219 "problem." % new_path,
220 self.style.NOTICE,
221 )
222
223 if self.paths_to_remove:
224 if self.verbosity >= 2:
225 self.stdout.write("Cleaning up temporary files.")
226 for path_to_remove in self.paths_to_remove:
227 if os.path.isfile(path_to_remove):
228 os.remove(path_to_remove)
229 else:
230 shutil.rmtree(path_to_remove)
231
232 run_formatters([top_dir], **formatter_paths, stderr=self.stderr)
233
234 def handle_template(self, template, subdir):
235 """
236 Determine where the app or project templates are.
237 Use django.__path__[0] as the default because the Django install
238 directory isn't known.
239 """
240 if template is None:
241 return os.path.join(django.__path__[0], "conf", subdir)
242 else:
243 template = template.removeprefix("file://")
244 expanded_template = os.path.expanduser(template)
245 expanded_template = os.path.normpath(expanded_template)
246 if os.path.isdir(expanded_template):
247 return expanded_template
248 if self.is_url(template):
249 # downloads the file and returns the path
250 absolute_path = self.download(template)
251 else:
252 absolute_path = os.path.abspath(expanded_template)
253 if os.path.exists(absolute_path):
254 return self.extract(absolute_path)
255
256 raise CommandError(
257 "couldn't handle %s template %s." % (self.app_or_project, template)
258 )
259
260 def validate_name(self, name, name_or_dir="name"):
261 if name is None:
262 raise CommandError(
263 "you must provide {an} {app} name".format(
264 an=self.a_or_an,
265 app=self.app_or_project,
266 )
267 )
268 # Check it's a valid directory name.
269 if not name.isidentifier():
270 raise CommandError(
271 "'{name}' is not a valid {app} {type}. Please make sure the "
272 "{type} is a valid identifier.".format(
273 name=name,
274 app=self.app_or_project,
275 type=name_or_dir,
276 )
277 )
278 # Check that __spec__ doesn't exist.
279 if find_spec(name) is not None:
280 raise CommandError(
281 "'{name}' conflicts with the name of an existing Python "
282 "module and cannot be used as {an} {app} {type}. Please try "
283 "another {type}.".format(
284 name=name,
285 an=self.a_or_an,
286 app=self.app_or_project,
287 type=name_or_dir,
288 )
289 )
290
291 def download(self, url):
292 """
293 Download the given URL and return the file name.
294 """
295
296 def cleanup_url(url):
297 tmp = url.rstrip("/")
298 filename = tmp.split("/")[-1]
299 if url.endswith("/"):
300 display_url = tmp + "/"
301 else:
302 display_url = url
303 return filename, display_url
304
305 prefix = "django_%s_template_" % self.app_or_project
306 tempdir = tempfile.mkdtemp(prefix=prefix, suffix="_download")
307 self.paths_to_remove.append(tempdir)
308 filename, display_url = cleanup_url(url)
309
310 if self.verbosity >= 2:
311 self.stdout.write("Downloading %s" % display_url)
312
313 the_path = os.path.join(tempdir, filename)
314 opener = build_opener()
315 opener.addheaders = [("User-Agent", f"Django/{django.__version__}")]
316 try:
317 with opener.open(url) as source, open(the_path, "wb") as target:
318 headers = source.info()
319 target.write(source.read())
320 except OSError as e:
321 raise CommandError(
322 "couldn't download URL %s to %s: %s" % (url, filename, e)
323 )
324
325 used_name = the_path.split("/")[-1]
326
327 # Trying to get better name from response headers
328 content_disposition = headers["content-disposition"]
329 if content_disposition:
330 _, params = parse_header_parameters(content_disposition)
331 guessed_filename = params.get("filename") or used_name
332 else:
333 guessed_filename = used_name
334
335 # Falling back to content type guessing
336 ext = self.splitext(guessed_filename)[1]
337 content_type = headers["content-type"]
338 if not ext and content_type:
339 ext = mimetypes.guess_extension(content_type)
340 if ext:
341 guessed_filename += ext
342
343 # Move the temporary file to a filename that has better
344 # chances of being recognized by the archive utils
345 if used_name != guessed_filename:
346 guessed_path = os.path.join(tempdir, guessed_filename)
347 shutil.move(the_path, guessed_path)
348 return guessed_path
349
350 # Giving up
351 return the_path
352
353 def splitext(self, the_path):
354 """
355 Like os.path.splitext, but takes off .tar, too
356 """
357 base, ext = posixpath.splitext(the_path)
358 if base.lower().endswith(".tar"):
359 ext = base[-4:] + ext
360 base = base[:-4]
361 return base, ext
362
363 def extract(self, filename):
364 """
365 Extract the given file to a temporary directory and return
366 the path of the directory with the extracted content.
367 """
368 prefix = "django_%s_template_" % self.app_or_project
369 tempdir = tempfile.mkdtemp(prefix=prefix, suffix="_extract")
370 self.paths_to_remove.append(tempdir)
371 if self.verbosity >= 2:
372 self.stdout.write("Extracting %s" % filename)
373 try:
374 archive.extract(filename, tempdir)
375 return tempdir
376 except (archive.ArchiveException, OSError) as e:
377 raise CommandError(
378 "couldn't extract file %s to %s: %s" % (filename, tempdir, e)
379 )
380
381 def is_url(self, template):
382 """Return True if the name looks like a URL."""
383 if ":" not in template:
384 return False
385 scheme = template.split(":", 1)[0].lower()
386 return scheme in self.url_schemes
387
388 def apply_umask(self, old_path, new_path):
389 current_umask = os.umask(0)
390 os.umask(current_umask)
391 current_mode = stat.S_IMODE(os.stat(old_path).st_mode)
392 os.chmod(new_path, current_mode & ~current_umask)
393
394 def make_writeable(self, filename):
395 """
396 Make sure that the file is writeable.
397 Useful if our source is read-only.
398 """
399 if not os.access(filename, os.W_OK):
400 st = os.stat(filename)
401 new_permissions = stat.S_IMODE(st.st_mode) | stat.S_IWUSR
402 os.chmod(filename, new_permissions)