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 thepadstring
padstring
: a string to use for padding, will be repeated as often as possible to achieve the desired length specified bypad
- Example:
${identifier:pad=4, padstring=XY}
for identifier having the value a will become XYXa
- Example:
-
extract
()[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 Return type: dict
-
class
xl.formatter.
ProgressTextFormatter
(format, player)[source]¶ A text formatter for progress indicators
-
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
- track (
-
-
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
- track (
-
-
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
- track (
-
-
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
- track (
-
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 ★★★☆☆
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}