Trax

Provides the base for creating and managing Track objects.

Tracks

class xl.trax.Track(uri=None, scan=True, _unpickles=None)

Represents a single track.

Parameters:
  • uri – The path to the track.
  • scan – Whether to try to read tags from the given uri. Use only if the tags need to be set by a different source.
  • _unpickles – used internally to restore from a pickled state. not for normal use.
exists()

Returns whether the file exists This can be very slow, use with caution!

get_loc_for_io()

Gets the location as a full uri.

Safe for IO operations via gio, not suitable for display to users as it may be in non-utf-8 encodings.

get_rating()

Returns the current track rating as an integer, as determined by the rating/maximum setting.

get_tag_display(tag, join=True, artist_compilations=False, extend_title=True)

Get a tag value in a form suitable for display.

Parameters:
  • tag – The name of the tag to get
  • join – If True, joins lists of values into a single value.
  • artist_compilations – If True, automatically handle albumartist and other compilations detections when tag==”albumartist”.
  • extend_title – If the title tag is unknown, try to add some identifying information to it.
get_tag_raw(tag, join=False)

Get the raw value of a tag. For non-internal tags, the result will always be a list of unicode strings.

Parameters:
  • tag – The name of the tag to get
  • join – If True, joins lists of values into a single value.
get_tag_sort(tag, join=True, artist_compilations=False, extend_title=True)

Get a tag value in a form suitable for sorting.

Parameters:
  • tag – The name of the tag to get
  • join – If True, joins lists of values into a single value.
  • artist_compilations – If True, automatically handle albumartist and other compilations detections when tag==”albumartist”.
  • extend_title – If the title tag is unknown, try to add some identifying information to it.
get_type()

Get the URI schema the file uses, e.g. file, http, smb.

list_tags()

Returns a list of the names of all tags present in this Track.

local_file_name()

If the file is accessible on the local filesystem, returns a standard path to it (e.g. “/home/foo/bar”), otherwise, returns None.

If a path is returned, it is safe to use for IO operations. Existence of a path does not guarantee file existence.

read_tags()

Reads tags from the file for this Track.

Returns False if unsuccessful, and a Format object from xl.metadata otherwise.

set_loc(loc)

Sets the location.

Parameters:loc – the location, as either a uri or a file path.
set_rating(rating)

Sets the current track rating from an integer, on the scale determined by the rating/maximum setting.

Returns the scaled rating

set_tag_raw(tag, values, notify_changed=True)

Set the raw value of a tag.

Parameters:
  • tag – The name of the tag to set.
  • values – The value or values to set the tag to.
  • notify_changed – whether to send a signal to let other parts of Exaile know there has been an update. Only set this to False if you know that no other parts of Exaile need to be updated.
write_tags()

Writes tags to the file for this Track.

Returns False if unsuccessful, and a Format object from xl.metadata otherwise.

xl.trax.is_valid_track(location)

Returns whether the file at the given location is a valid track

Parameters:location (string) – the location to check
Returns:whether the file is a valid track
Return type:boolean
xl.trax.get_uris_from_tracks(tracks)

Returns all URIs for tracks

Parameters:tracks (list of xl.trax.Track) – the tracks to retrieve the URIs from
Returns:the uris
Return type:list of string
xl.trax.get_tracks_from_uri(uri)

Returns all valid tracks located at uri

Parameters:uri (string) – the uri to retrieve the tracks from
Returns:the retrieved tracks
Return type:list of xl.trax.Track
xl.trax.sort_tracks(fields, iter, trackfunc=None, reverse=False, artist_compilations=False)

Sorts tracks.

Parameters:
  • fields (iterable) – tag names to sort by
  • iter (iterable) – the tracks to sort, alternatively use trackfunc
  • trackfunc (function or None) – function to get a Track from an item in the iterable
  • reverse (boolean) – whether to sort in reversed order
xl.trax.sort_result_tracks(fields, trackiter, reverse=False, artist_compilations=False)

Sorts SearchResultTracks, ie. the output from a search.

Same params as sort_tracks.

xl.trax.get_rating_from_tracks(tracks)

Returns the common rating for all tracks or simply 0 if not all tracks have the same rating. Same goes if the amount of tracks is 0 or more than the internal limit.

Parameters:tracks (iterable) – the tracks to retrieve the rating from

Track Database

Track databases are a simple persistence layer to hold collections of Track objects.

class xl.trax.TrackDB(name='', location='', pickle_attrs=[], loadfirst=False)

Manages a track database.

Allows you to add, remove, retrieve, search, save and load Track objects.

Parameters:
  • name – The name of this TrackDB.
  • location – Path to a file where this TrackDB should be stored.
  • pickle_attrs – A list of attributes to store in the pickled representation of this object. All attributes listed must be built-in types, with one exception: If the object contains the phrase ‘tracks’ in its name it may be a list or dict of Track objects.
  • load_first – Set to True if this collection should be loaded before any tracks are created.

Sets up the trackDB.

add(track)

Adds a track to the database of tracks

Parameters:track – The xl.trax.Track to add
add_tracks(*__args, **__kw)

Like add(), but takes a list of xl.trax.Track

load_from_location(*__args, **__kw)

Restores TrackDB state from the pickled representation stored at the specified location.

Parameters:location (string) – the location to load the data from
remove(track)

Removes a track from the database

Parameters:track – the xl.trax.Track to remove
remove_tracks(*__args, **__kw)

Like remove(), but takes a list of xl.trax.Track

save_to_location(*__args, **__kw)

Saves a pickled representation of this TrackDB to the specified location.

Parameters:location (string) – the location to save the data to

Searching

class xl.trax.TracksMatcher(search_string, case_sensitive=True, keyword_tags=None)

Holds criteria and determines whether a given track matches those criteria.

Parameters:
  • search_string – a string describing the match conditions
  • case_sensitive – whether to search in a case-sensitive manner.
  • keyword_tags – a list of tags to match search keywords in.
xl.trax.search_tracks(trackiter, trackmatchers)

Search a set of tracks for those that match specified conditions.

Parameters:
  • trackiter – An iterable object returning Track objects
  • trackmatchers – A list of TrackMatcher objects
xl.trax.search_tracks_from_string(trackiter, search_string, case_sensitive=True, keyword_tags=None)

Convenience wrapper around search_tracks that builds matchers automatically from the search string.

Arguments have the same meaning as the corresponding arguments on on search_tracks and TracksMatcher.