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)

gets the collection by a location.

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

Manages a persistent track database.

Parameters:args – see xl.trax.trackdb.TrackDB

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)

Add this library to the collection

Parameters:library (Library) – the library to add
close()

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

freeze_libraries()

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

Gets a list of all the Libraries associated with this Collection

Return type:list of Library
remove_library(library)

Remove a library from the collection

Parameters:library (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()

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

Initializes the thread

Parameters:
  • collection – the collection to scan
  • startup_scan – Only scan libraries scanned at startup
  • force_update – Update files regardless whether they’ve changed
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, monitored=False, scan_interval=0, startup_scan=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
>>>

Sets up the Library

Parameters:
  • location (string) – the directory this library will scan
  • monitored (bool) – whether the library should update its collection at changes within the library’s path
  • scan_interval (int) – the interval for automatic rescanning
add(loc, move=False)

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

delete(loc)

Deletes a file from the disk

Warning

This permanently deletes the file from the hard disk.

get_location()

Gets the current location associated with this Library

Returns:the current location
Return type:string
get_monitored()

Whether the library should be monitored for changes

get_rescan_interval()
Returns:the scan interval in seconds
rescan(notify_interval=None, force_update=False)

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

set_location(location)

Changes the location of this Library

Parameters:location (string) – the new location to use
set_monitored(monitored)

Enables or disables monitoring of the library

Parameters:monitored (bool) – Whether to monitor the library
set_rescan_interval(interval)

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

Parameters:interval (int) – scan interval in seconds
update_track(gloc, force_update=False)

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

monitored

Whether the library should be monitored for changes

class xl.collection.LibraryMonitor(library)

Monitors library locations for changes

Parameters:library (Library) – the library to monitor