Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 32 additions & 65 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,19 @@
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/codingjoe/django-dynamic-filenames/raw/main/images/logo-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://github.com/codingjoe/django-dynamic-filenames/raw/main/images/logo-light.svg">
<img alt="Django DynFN: Advanced filename patterns using f-Strings" src="https://github.com/codingjoe/django-dynamic-filenames/raw/main/images/logo-light.svg">
</picture>
<br>
<a href="https://github.com/codingjoe/django-dynamic-filenames?tab=readme-ov-file">Documentation</a> |
<a href="https://github.com/codingjoe/django-dynamic-filenames/issues/new/choose">Issues</a> |
<a href="https://github.com/codingjoe/django-dynamic-filenames/releases">Changelog</a> |
<a href="https://github.com/sponsors/codingjoe">Funding</a> 💚
</p>

# Django Dynamic Filenames

Write advanced filename patterns using the [Format String
Syntax](https://docs.python.org/3/library/string.html#format-string-syntax).
Write advanced filename patterns using the [Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax).

## Getting Started

Expand Down Expand Up @@ -35,77 +47,32 @@ Auto slug example:

### Field names

`ext`

: File extension including the dot.

`name`

: Filename excluding the folders.

`model_name`

: Name of the Django model.

`app_label`
- `ext`: File extension including the dot.
- `name`: Filename excluding the folders.
- `model_name`: Name of the Django model.
- `app_label`: App label of the Django model.
- `instance`: Instance of the model before it has been saved. You may not have a primary key at this point.
- `uuid`: UUID version 4 that supports multiple type specifiers.
The UUID will be the same should you use it twice in the same string,
but different on each invocation of the `upload_to` callable.

: App label of the Django model.

`instance`

: Instance of the model before it has been saved. You may not have a
primary key at this point.

`uuid`

: UUID version 4 that supports multiple type specifiers. The UUID will
be the same should you use it twice in the same string, but
different on each invocation of the `upload_to` callable.

```
The type specifiers allow you to format the UUID in different ways,
e.g. `{uuid:x}` will give you a with a hexadecimal UUID.

The supported type specifiers are:

`s`
- `s`: String representation of a UUID including dashes.
- `i`: Integer representation of a UUID. Like to `UUID.int`.
- `x`: Hexadecimal (Base16) representation of a UUID. Like to `UUID.hex`.
- `X`: Upper case hexadecimal representation of a UUID. Like to `UUID.hex`.
- `base32`: Base32 representation of a UUID without padding.
- `base64`: Base64 representation of a UUID without padding.

: String representation of a UUID including dashes.
> [!WARNING]
> Not all file systems support Base64 file names.

`i`

: Integer representation of a UUID. Like to `UUID.int`.

`x`

: Hexadecimal (Base16) representation of a UUID. Like to
`UUID.hex`.

`X`

: Upper case hexadecimal representation of a UUID. Like to
`UUID.hex`.

`base32`

: Base32 representation of a UUID without padding.

`base64`

: Base64 representation of a UUID without padding.

:::: warning
::: title
Warning
:::

Not all file systems support Base64 file names.
::::

All type specifiers also support precisions to cut the string, e.g.
`{{uuid:.2base32}}` would only return the first 2 characters of a
Base32 encoded UUID.
```
All type specifiers also support precisions to cut the string,
e.g. `{{uuid:.2base32}}` would only return the first 2 characters of a Base32 encoded UUID.

### Type specifiers

Expand Down
16 changes: 16 additions & 0 deletions images/logo-dark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions images/logo-light.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.