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