Formatter

Provides an extensible framework for processing and preparation of data for display in various contexts.

Formatters

class xl.formatter.Formatter(format)

A generic text formatter based on a format string

By default the following parameters are provided to each identifier:

• prefix, suffix: a string to put before or after the formatted string if that string is not empty

  • Whitespace will be not be touched and transferred as is

  • The characters ,, } and = need to be escaped like \,, \} and \= respectively

• pad: desired length the formatted string should have, will be achieved using the padstring

• padstring: a string to use for padding, will be repeated as often as possible to achieve the desired length specified by pad

  • Example: ${identifier:pad=4, padstring=XY} for identifier having the value a will become XYXa

extract() → Dict[str, Tuple[str, Dict[str, bool | str]]]

Retrieves the identifiers and their optional parameters

Example of the returned dictionary:

extractions = {
    'identifier1': (
        'identifier1', {}),
    'identifier2:parameter': (
        'identifier2', {'parameter': True}),
    'identifier3:parameter=argument': (
        'identifier3', {'parameter': 'argument'})
}

Returns:

the extractions

format(*args)

Returns a string by formatting the passed data

Parameters:

args – data to base the formatting on

Returns:

the formatted text

Return type:

string

class xl.formatter.ProgressTextFormatter(format, player)

A text formatter for progress indicators

format(current_time=None, total_time=None)

Returns a string suitable for progress indicators

Parameters:

• current_time (float) – the current progress, taken from the current playback if not set

• total_time (float) – the total length of a track, taken from the current playback if not set

Returns:

The formatted text

Return type:

string

class xl.formatter.TrackFormatter(format)

A formatter for track data

format(track, markup_escape=False)

Returns a string for places where track data is presented to the user

Parameters:

• track (xl.trax.Track) – a single track to take data from

• markup_escape (bool) – whether to escape markup-like characters in tag values

Returns:

the formatted text

Return type:

string

class xl.formatter.TagFormatter(name)

A formatter provider for a tag of a track

format(track, parameters)

Formats a raw tag value. Accepts optional parameters to manipulate the formatting process.

Parameters:

• track (xl.trax.Track) – the track to get the tag from

• parameters (dictionary) – optionally passed parameters

Returns:

the formatted value

Return type:

string

class xl.formatter.TrackNumberTagFormatter

Bases: NumberTagFormatter

A formatter for the tracknumber of a track

class xl.formatter.DiscNumberTagFormatter

Bases: NumberTagFormatter

A formatter for the discnumber of a track

class xl.formatter.ArtistTagFormatter

Bases: TagFormatter

A formatter for the artist of a track

format(track, parameters)

Formats a raw tag value

Parameters:

• track (xl.trax.Track) – the track to get the tag from

• parameters –

  optionally passed parameters Possible values are:

  • compilate: Allows for proper handling of compilations, either via albumartist tag, a fallback value, or simply all artists

Returns:

the formatted value

Return type:

string

class xl.formatter.LengthTagFormatter

Bases: TimeTagFormatter

A formatter for the length of a track

format(track, parameters)

Formats a raw tag value

Parameters:

• track (xl.trax.Track) – the track to get the tag from

• parameters (dictionary) –

  Verbosity of the output, possible values for “format” are:

  • short: “1:02:42”

  • long: “1h, 2m, 42s”

  • verbose: “1 hour, 2 minutes, 42 seconds”

Returns:

the formatted value

Return type:

string

static format_value(value, format='short')

Formats a length value

Parameters:

• value (float) – the length in seconds

• format (string) –

  verbosity of the output, possible values are:

  • short: “1:02:42”

  • long: “1h, 2m, 42s”

  • verbose: “1 hour, 2 minutes, 42 seconds”

Returns:

the formatted value

Return type:

string

class xl.formatter.RatingTagFormatter

Bases: TagFormatter

A formatter for the rating of a track

Will return glyphs representing the rating like ★★★☆☆

class xl.formatter.LastPlayedTagFormatter

Bases: DateTagFormatter

A formatter for the last time a track was played

Templates

class xl.formatter.ParameterTemplate(template)

An extended template class which additionally accepts parameters assigned to identifiers.

This introduces another pattern group named “parameters” in addition to the groups created by string.Template

Examples:

• ${foo:parameter1}

• ${bar:parameter1, parameter2}

• ${qux:parameter1=argument1, parameter2}