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.
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.
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.
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
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.