Submodule functions

This file originates from the file beets/library.py of the beets project.

class tmep.functions.DefaultTemplateFunctions(values: Dict[str, Any] | None = None)

A container class for the default functions provided to path templates. These functions are contained in an object to provide additional context to the functions – specifically, the Item being evaluated.

prefix = 'fn_'

func_names: List[str] = ['fn_alpha', 'fn_alphanum', 'fn_asciify', 'fn_delchars', 'fn_deldupchars', 'fn_first', 'fn_if', 'fn_ifdef', 'fn_ifdefempty', 'fn_ifdefnotempty', 'fn_initial', 'fn_left', 'fn_lower', 'fn_nowhitespace', 'fn_num', 'fn_replchars', 'fn_right', 'fn_sanitize', 'fn_shorten', 'fn_time', 'fn_title', 'fn_upper']

values: Dict[str, Any] | None

get() → Dict[str, Callable[[...], str | int]]

Returns a dictionary containing the functions defined in this object. The keys are function names (as exposed in templates) and the values are Python functions.

fn_alpha(text: str) → str

• synopsis: %alpha{text}

• description: This function first ASCIIfies the given text, then all non alphabet characters are replaced with whitespaces.

• example: %alpha{a1b23c} → a b c

fn_alphanum(text: str) → str

• synopsis: %alphanum{text}

• description: This function first ASCIIfies the given text, then all non alpanumeric characters are replaced with whitespaces.

• example: %alphanum{après-évêque1} → apres eveque1

static fn_asciify(text: str) → str

• synopsis: %asciify{text}

• description: Translate non-ASCII characters to their ASCII equivalents. For example, “café” becomes “cafe”. Uses the mapping provided by the unidecode module.

• example: %asciify{äÄöÖüÜ} → aeAeoeOeueUe

static fn_delchars(text: str, chars: str) → str

• synopsis: %delchars{text,chars}

• description: Delete every single character of “chars“ in “text”.

• example: %delchars{Schubert, ue} → Schbrt

static fn_deldupchars(text: str, chars: str = '-_\\.') → str

• synopsis: %deldupchars{text,chars}

• description: Search for duplicate characters and replace with only one occurrance of this characters.

• example: %deldupchars{a---b___c...d} → a-b_c.d; %deldupchars{a---b___c, -} → a-b___c

static fn_first(text: str, count: int = 1, skip: int = 0, sep: str = '; ', join_str: str = '; ') → str

• synopsis: %first{text} or %first{text,count,skip} or %first{text,count,skip,sep,join}

• description: Returns the first item, separated by ;. You can use %first{text,count,skip}, where count is the number of items (default 1) and skip is number to skip (default 0). You can also use %first{text,count,skip,sep,join} where sep is the separator, like ; or / and join is the text to concatenate the items.

• example: %first{Alice / Bob / Eve,2,0, / , & } → Alice & Bob

Parameters:

• text – the string

• count – The number of items included

• skip – The number of items skipped

• sep – the separator. Usually is ‘; ‘ (default) or ‘/ ‘

• join_str – the string which will join the items, default ‘; ‘.

static fn_if(condition: str, trueval: str, falseval: str = '') → str

If condition is nonempty and nonzero, emit trueval; otherwise, emit falseval (if provided).

• synopsis: %if{condition,trueval} or %if{condition,trueval,falseval}

• description: If condition is nonempty (or nonzero, if it’s a number), then returns the second argument. Otherwise, returns the third argument if specified (or nothing if falseval is left off).

• example: x%if{false,foo} → x

fn_ifdef(field: str, trueval: str = '', falseval: str = '') → str

If field exists return trueval or the field (default) otherwise, emit return falseval (if provided).

• synopsis: %ifdef{field}, %ifdef{field,trueval} or %ifdef{field,trueval,falseval}

• description: If field exists, then return trueval or field (default). Otherwise, returns falseval. The field should be entered without $.

• example: %ifdef{compilation,Compilation}

Parameters:

• field – The name of the field

• trueval – The string if the condition is true

• falseval – The string if the condition is false

Returns:

The string, based on condition

fn_ifdefempty(field: str, trueval: str = '', falseval: str = '')

If field exists and is emtpy return trueval otherwise, emit return falseval (if provided).

• synopsis: %ifdefempty{field,text} or %ifdefempty{field,text,falsetext}

• description: If field exists and is empty, then return truetext. Otherwise, returns falsetext. The field should be entered without $.

• example: %ifdefempty{compilation,Album,Compilation}

Parameters:

• field – The name of the field

• trueval – The string if the condition is true

• falseval – The string if the condition is false

Returns:

The string, based on condition

fn_ifdefnotempty(field: str, trueval: str = '', falseval: str = '') → str

If field is not emtpy return trueval or the field (default) otherwise, emit return falseval (if provided).

• synopsis: %ifdefnotempty{field,text} or %ifdefnotempty{field,text,falsetext}

• description: If field is not empty, then return truetext. Otherwise, returns falsetext. The field should be entered without $.

• example: %ifdefnotempty{compilation,Compilation,Album}

Parameters:

• field – The name of the field

• trueval – The string if the condition is true

• falseval – The string if the condition is false

Returns:

The string, based on condition

static fn_initial(text: str) → str

• synopsis: %initial{text}

• description: Get the first character of a text in lowercase. The text is converted to ASCII. All non word characters are erased.

  Only letters and numbers are preserved. If the first character is a number, then the result is ‘0’.

• example: %initial{Schubert} → s

Parameters:

text (string) – Input text to build initial from.

Returns:

A single character

static fn_left(text: str, n: str) → str

Get the leftmost characters of a string.

• synopsis: %left{text,n}

• description: Return the first “n” characters of “text”.

• example: %left{Schubert, 3} → Sch

static fn_lower(text: str) → str

Convert a string to lower case

• synopsis: %lower{text}

• description: Convert “text” to lowercase.

• example: %lower{SCHUBERT} → schubert

static fn_nowhitespace(text: str, replace: str = '-') → str

• synopsis: %nowhitespace{text,replace}

• description: Replace all whitespace characters with replace. By default: a dash (-)

• example: %nowhitespace{a b} → a-b; %nowhitespace{a b, _} → a_b

static fn_num(number: int, count: int = 2) → str

Pad decimal number with leading zeros

• synopsis: %num{number,count}

• description: Pad decimal number with leading zeros.

• example: %num{7,3} → 007

static fn_replchars(text: str, replace: str, chars: str) → str

• synopsis: %replchars{text,chars,replace}

• description: Replace the characters “chars” in “text” with “replace”.

• example: %replchars{Schubert,-,ue} → Sch-b-rt

static fn_right(text: str, n: str) → str

Get the rightmost characters of a string.

• synopsis: %right{text,n}

• description: Return the last “n” characters of “text”.

• example: %right{Schubert,3} → ert

static fn_sanitize(text: str) → str

• synopsis: %sanitize{text}

• description: Delete characters that are not allowed in most file systems.

• example: %sanitize{x:*?<>|/~&x} → xx

static fn_shorten(text: str, max_size: int = 32) → str

Shorten the given text to max_size

• synopsis: %shorten{text} or %shorten{text,max_size}

• description: Shorten “text” on word boundarys.

• example: %shorten{Lorem ipsum dolor sit, 10} → Lorem

static fn_time(text: str, fmt: str, cur_fmt: str) → str

Format a time value using strftime.

• synopsis: %time{date_time,format,curformat}

• description: Return the date and time in any format accepted by strftime. For example, to get the year, use %time{$added,%Y}.

• example: %time{30 Nov 2024,%Y,%d %b %Y} → 2024

static fn_title(text: str) → str

Convert a string to title case

• synopsis: %title{text}

• description: Convert “text” to Title Case.

• example: %title{franz schubert} → Franz Schubert

static fn_upper(text: str) → str

Covert a string to upper case

• synopsis: %upper{text}

• description: Convert “text” to UPPERCASE.

• example: %upper{foo} → FOO