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
Parameters:format (string) – the initial format, see the documentation of string.Template for details
extract()

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
Return type:dict
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

Parameters:format (string) – the initial format, see the documentation of string.Template for details
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

Parameters:name (string) – the name of the tag
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: xl.formatter.NumberTagFormatter

A formatter for the tracknumber of a track

class xl.formatter.DiscNumberTagFormatter

Bases: xl.formatter.NumberTagFormatter

A formatter for the discnumber of a track

class xl.formatter.ArtistTagFormatter

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

Bases: xl.formatter.TagFormatter

A formatter for the rating of a track

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

class xl.formatter.LastPlayedTagFormatter

Bases: xl.formatter.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}
Parameters:template – the template string