Formatter

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

Formatters

class xl.formatter.Formatter(format)[source]

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, Union[bool, str]]]][source]

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)[source]

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)[source]

A text formatter for progress indicators

format(current_time=None, total_time=None)[source]

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)[source]

A formatter for track data

format(track, markup_escape=False)[source]

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)[source]

A formatter provider for a tag of a track

format(track, parameters)[source]

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[source]

Bases: xl.formatter.NumberTagFormatter

A formatter for the tracknumber of a track

class xl.formatter.DiscNumberTagFormatter[source]

Bases: xl.formatter.NumberTagFormatter

A formatter for the discnumber of a track

class xl.formatter.ArtistTagFormatter[source]

Bases: xl.formatter.TagFormatter

A formatter for the artist of a track

format(track, parameters)[source]

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[source]

Bases: xl.formatter.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[source]

Bases: xl.formatter.TagFormatter

A formatter for the rating of a track

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

class xl.formatter.LastPlayedTagFormatter[source]

Bases: xl.formatter.DateTagFormatter

A formatter for the last time a track was played

Templates

class xl.formatter.ParameterTemplate(template)[source]

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}