docs/formatting.md
Format strings in gallery-dl follow the general rules of str.format() (PEP 3101) plus several extras.
The syntax for replacement fields is
{<field-name>!<conversion>:<format-specifiers>}
where
<field-name>
selects a value
and the optional
!<conversion>
&
:<format-specifiers>
specify how to transform it.
Examples:
{title}{content!W}{date:Olocal/%Y%m%d %H%M}Field names select the metadata value to use in a replacement field.
While simple names are usually enough, more complex forms like accessing values by attribute, element index, or slicing are also supported.
<table> <thead> <tr> <th></th> <th>Example</th> <th>Result</th> </tr> </thead> <tbody> <tr> <td>Name</td> <td><code>{title}</code></td> <td><code>Hello World</code></td> </tr> <tr> <td>Element Index</td> <td><code>{title[6]}</code></td> <td><code>W</code></td> </tr> <tr> <td>Slicing</td> <td><code>{title[3:8]}</code></td> <td><code>lo Wo</code></td> </tr> <tr> <td>Slicing (Bytes)</td> <td><code>{title_ja[b3:18]}</code></td> <td><code>ロー・ワー</code></td> </tr> <tr> <td>Alternatives</td> <td><code>{empty|title}</code></td> <td><code>Hello World</code></td> </tr> <tr> <td>Attribute Access</td> <td><code>{extractor.url}</code></td> <td><code>https://example.org/</code></td> </tr> <tr> <td rowspan="2">Element Access</td> <td><code>{user[name]}</code></td> <td><code>John Doe</code></td> </tr> <tr> <td><code>{user['name']}</code></td> <td><code>John Doe</code></td> </tr> </tbody> </table>All of these methods can be combined.
For example {title[24]|empty|extractor.url[15:-1]} would result in .org.
Conversion specifiers allow to convert the value to a different form or type. Such a specifier must only consist of 1 character. gallery-dl supports the default three (s, r, a) as well as several others:
Format specifiers can be used for advanced formatting by using the options provided by Python (see Format Specification Mini-Language) like zero-filling a number ({num:>03}) or formatting a datetime object ({date:%Y%m%d}), or with gallery-dl's extra formatting specifiers:
All special format specifiers (?, L, J, R, D, O, etc)
can be chained and combined with one another,
but must always appear before any standard format specifiers:
For example {foo:?//RF/B/Ro/e/> 10} -> Bee Bar
?// - Tests if foo has a valueRF/B/ - Replaces F with BRo/e/ - Replaces o with e> 10 - Left-fills the string with spaces until it is 10 characters longReplacement field names that are available in all format strings.
<table> <thead> <tr> <th>Field Name</th> <th>Description</th> <th>Example</th> <th>Result</th> </tr> </thead> <tbody> <tr> <td><code>_env</code></td> <td>Environment variables</td> <td><code>{_env[HOME]}</code></td> <td><code>/home/john</code></td> </tr> <tr> <td><code>_now</code></td> <td>Current local date and time</td> <td><code>{_now:%Y-%m}</code></td> <td><code>2022-08</code></td> </tr> <tr> <td><code>_nul</code></td> <td>Universal <code>null</code> value</td> <td><code>{date|_nul:%Y-%m}</code></td> <td><code>None</code></td> </tr> <tr> <td rowspan="2"><code>_lit</code></td> <td rowspan="2">String literals</td> <td><code>{_lit[foo]}</code></td> <td><code>foo</code></td> </tr> <tr> <td><code>{'bar'}</code></td> <td><code>bar</code></td> </tr> </tbody> </table>Starting a format string with \f<Type> allows to set a different format string type than the default. Available ones are: