Collection

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.

Collections

xl.collection.get_collection_by_loc(loc: str) → Collection | None

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=[])

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))
5

add_library(library: Library) → None

Add this library to the collection

Parameters:

library – the library to add

close()

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

freeze_libraries() → None

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[Library]

Gets a list of all the Libraries associated with this Collection

remove_library(library: Library) → None

Remove a library from the collection

Parameters:

library – the library to remove

rescan_libraries(startup_only=False, force_update=False)

Rescans all libraries associated with this Collection

serialize_libraries()

Save information about libraries

Called whenever the library’s settings are changed

stop_scan()

Stops the library scan

thaw_libraries() → None

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.

unserialize_libraries(_serial_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)

Scans the collection

on_scan_progress_update(type, collection, progress)

Notifies about progress changes

run()

Runs the thread

stop()

Stops the thread

Libraries

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

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()
True
>>> print(c.get_libraries()[0].location)
./tests/data
>>> print(len(list(c.search('artist="TestArtist"'))))
5
>>>

add(loc: str, move: bool = False) → None

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

delete(loc: str) → None

Deletes a file from the disk

Warning

This permanently deletes the file from the hard disk.

get_location() → str

Gets the current location associated with this Library

Returns:

the current location

get_monitored() → bool

Whether the library should be monitored for changes

get_rescan_interval() → int

Returns:

the scan interval in seconds

property monitored: bool

Whether the library should be monitored for changes

rescan(notify_interval: int | None = None, force_update: bool = False) → bool

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

Changes the location of this Library

Parameters:

location – the new location to use

set_monitored(monitored: bool) → None

Enables or disables monitoring of the library

Parameters:

monitored (bool) – Whether to monitor the library

set_rescan_interval(interval: int) → None

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

Parameters:

interval – scan interval in seconds

update_track(gloc: <mocks.MockGiModule object at 0x7f7210273a90>, force_update: bool = False) → Track | None

Rescan the track at a given location

Parameters:

• 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)

Monitors library locations for changes