|
| 1 | +======================== |
| 2 | +Django Dynamic Filenames |
| 3 | +======================== |
| 4 | + |
| 5 | +Write advanced filename patterns using the `Format String Syntax`__. |
| 6 | + |
| 7 | +__ https://docs.python.org/3/library/string.html#format-string-syntax |
| 8 | + |
| 9 | +Getting Started |
| 10 | +--------------- |
| 11 | + |
| 12 | +Installation |
| 13 | +~~~~~~~~~~~~ |
| 14 | + |
| 15 | +.. code-block:: bash |
| 16 | +
|
| 17 | + pip install django-dynamic-filenames |
| 18 | +
|
| 19 | +Samples |
| 20 | +~~~~~~~ |
| 21 | + |
| 22 | +Basic example: |
| 23 | + |
| 24 | +.. code-block:: python |
| 25 | +
|
| 26 | + from django.db import models |
| 27 | + from dynamic_names import FilePattern |
| 28 | +
|
| 29 | + upload_to_pattern = FilePattern( |
| 30 | + filename_pattern='{app_name:.25}/{model_name:.30}/{uuid:base32}{ext}' |
| 31 | + ) |
| 32 | +
|
| 33 | + class FileModel(models.Model): |
| 34 | + my_file = models.FileField(upload_to=upload_to_pattern) |
| 35 | +
|
| 36 | +
|
| 37 | +Auto slug example: |
| 38 | + |
| 39 | + |
| 40 | +Features |
| 41 | +-------- |
| 42 | + |
| 43 | +Field names |
| 44 | +~~~~~~~~~~~ |
| 45 | + |
| 46 | +``ext`` |
| 47 | + File extension including the dot. |
| 48 | + |
| 49 | +``name`` |
| 50 | + Filename excluding the folders. |
| 51 | + |
| 52 | +``model_name`` |
| 53 | + Name of the Django model. |
| 54 | + |
| 55 | +``app_label`` |
| 56 | + App label of the Django model. |
| 57 | + |
| 58 | +``instance`` |
| 59 | + Instance of the model before it has been saved. You may not have a primary |
| 60 | + key at this point. |
| 61 | + |
| 62 | +``uuid`` |
| 63 | + UUID version 4 that supports multiple type specifiers. The UUID will be |
| 64 | + the same should you use it twice in the same string, but different on each |
| 65 | + invocation of the ``upload_to`` callable. |
| 66 | + |
| 67 | + The type specifiers allow you to format the UUID in different ways, e.g. |
| 68 | + ``{uuid:x}`` will give you a with a hexadecimal UUID. |
| 69 | + |
| 70 | + The supported type specifiers are: |
| 71 | + |
| 72 | + ``s`` |
| 73 | + String representation of a UUID including dashes. |
| 74 | + |
| 75 | + ``i`` |
| 76 | + Integer representation of a UUID. Like to ``UUID.int``. |
| 77 | + |
| 78 | + ``x`` |
| 79 | + Hexadecimal (Base16) representation of a UUID. Like to ``UUID.hex``. |
| 80 | + |
| 81 | + ``X`` |
| 82 | + Upper case hexadecimal representation of a UUID. Like to |
| 83 | + ``UUID.hex``. |
| 84 | + |
| 85 | + ``base32`` |
| 86 | + Base32 representation of a UUID without padding. |
| 87 | + |
| 88 | + ``base64`` |
| 89 | + Base64 representation of a UUID without padding. |
| 90 | + |
| 91 | + .. warning:: Not all file systems support Base64 file names. |
| 92 | + |
| 93 | + All type specifiers also support precisions to cut the string, |
| 94 | + e.g. ``{{uuid:.2base32}}`` would only return the first 2 characters of a |
| 95 | + Base32 encoded UUID. |
| 96 | + |
| 97 | +Type specifiers |
| 98 | +~~~~~~~~~~~~~~~ |
| 99 | + |
| 100 | +You can also use a special slug type specifier, that slugifies strings. |
| 101 | + |
| 102 | +Example: |
| 103 | + |
| 104 | +.. code-block:: python |
| 105 | +
|
| 106 | + from django.db import models |
| 107 | + from dynamic_names import FilePattern |
| 108 | +
|
| 109 | + upload_to_pattern = FilePattern( |
| 110 | + filename_pattern='{app_name:.25}/{model_name:.30}/{instance.title:.40slug}{ext}' |
| 111 | + ) |
| 112 | +
|
| 113 | + class FileModel(models.Model): |
| 114 | + title = models.CharField(max_length=100) |
| 115 | + my_file = models.FileField(upload_to=upload_to_pattern) |
| 116 | +
|
| 117 | +Slug type specifiers also support precisions to cut the string. In the example |
| 118 | +above the slug of the instance title will be cut at 40 characters. |
0 commit comments