Classes representing collections and libraries

A collection is a database of tracks. It is based on TrackDB but has the ability to be linked with libraries.

A library finds tracks in a specified directory and adds them to an associated collection.


xl.collection.get_collection_by_loc(loc: str) → Optional[xl.collection.Collection][source]

gets the collection by a location.

Parameters:loc – Location of the collection
Returns:collection at location or None
class xl.collection.Collection(name, location=None, pickle_attrs=[])[source]

Manages a persistent track database.

Simple usage:

>>> from xl.collection import *
>>> from xl.trax import search
>>> collection = Collection("Test Collection")
>>> collection.add_library(Library("./tests/data"))
>>> collection.rescan_libraries()
>>> tracks = [i.track for i in search.search_tracks_from_string(
...     collection, ('artist==TestArtist'))]
>>> print(len(tracks))
add_library(library: xl.collection.Library) → None[source]

Add this library to the collection

Parameters:library – the library to add

close the collection. does any work like saving to disk, closing network connections, etc.

freeze_libraries() → None[source]

Prevents “libraries_modified” events from being sent from individual add and remove library calls.

Call this before making bulk changes to the libraries. Call thaw_libraries when you are done; this sends a single event if the libraries were modified.

get_libraries() → List[xl.collection.Library][source]

Gets a list of all the Libraries associated with this Collection

remove_library(library: xl.collection.Library) → None[source]

Remove a library from the collection

Parameters:library – the library to remove
rescan_libraries(startup_only=False, force_update=False)[source]

Rescans all libraries associated with this Collection


Save information about libraries

Called whenever the library’s settings are changed


Stops the library scan

thaw_libraries() → None[source]

Re-allow “libraries_modified” events from being sent from individual add and remove library calls. Also sends a “libraries_modified” event if the libraries have ben modified since the last call to freeze_libraries.


restores libraries from their serialized state.

Should only be called once, from the constructor.

class xl.collection.CollectionScanThread(collection, startup_scan=False, force_update=False)[source]

Scans the collection

on_scan_progress_update(type, collection, progress)[source]

Notifies about progress changes


Runs the thread


Stops the thread


class xl.collection.Library(location: str, monitored: bool = False, scan_interval: int = 0, startup_scan: bool = False)[source]

Scans and watches a folder for tracks, and adds them to a Collection.

Simple usage:

>>> from xl.collection import *
>>> c = Collection("TestCollection")
>>> l = Library("./tests/data")
>>> c.add_library(l)
>>> l.rescan()
>>> print(c.get_libraries()[0].location)
>>> print(len(list('artist="TestArtist"'))))
add(loc: str, move: bool = False) → None[source]

Copies (or moves) a file into the library and adds it to the collection

delete(loc: str) → None[source]

Deletes a file from the disk


This permanently deletes the file from the hard disk.

get_location() → str[source]

Gets the current location associated with this Library

Returns:the current location
get_monitored() → bool[source]

Whether the library should be monitored for changes

get_rescan_interval() → int[source]
Returns:the scan interval in seconds

Whether the library should be monitored for changes

rescan(notify_interval: Optional[int] = None, force_update: bool = False) → bool[source]

Rescan the associated folder and add the contained files to the Collection

Returns:Whether the caller should reschedule this call, due to the collection not being ready
set_location(location: str) → None[source]

Changes the location of this Library

Parameters:location – the new location to use
set_monitored(monitored: bool) → None[source]

Enables or disables monitoring of the library

Parameters:monitored (bool) – Whether to monitor the library
set_rescan_interval(interval: int) → None[source]

Sets the scan interval in seconds. If the interval is 0 seconds, the scan interval is stopped

Parameters:interval – scan interval in seconds

Rescan the track at a given location

  • gloc (Gio.File) – the location
  • force_update – Force update of file (default only updates file when mtime has changed)

returns: the Track object, None if it could not be updated

class xl.collection.LibraryMonitor(library)[source]

Monitors library locations for changes