| 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) |