RB.RhythmDB

g GObject.Object GObject.Object RB.RhythmDB RB.RhythmDB GObject.Object->RB.RhythmDB

Subclasses:None

Methods

Inherited:GObject.Object (37)
Structs:GObject.ObjectClass (5)
class compute_status_normal (n_songs, duration, size, singular, plural)
class error_quark ()
class get_error_entry_type ()
class get_ignore_entry_type ()
class get_song_entry_type ()
class query_concatenate (query1, query2)
class query_copy (array)
class query_free (query)
  add_uri (uri)
  add_uri_with_types (uri, type, ignore_type, error_type)
  commit ()
  do_full_query_async_parsed (results, query)
  do_full_query_parsed (results, query)
  emit_entry_added (entry)
  emit_entry_deleted (entry)
  emit_entry_extra_metadata_notify (entry, property_name, metadata)
  entry_count ()
  entry_count_by_type (entry_type)
  entry_delete (entry)
  entry_delete_by_type (type)
  entry_foreach (func, *data)
  entry_foreach_by_type (entry_type, func, *data)
  entry_gather_metadata (entry)
  entry_get (entry, propid, val)
  entry_keyword_add (entry, keyword)
  entry_keyword_has (entry, keyword)
  entry_keyword_remove (entry, keyword)
  entry_keywords_get (entry)
  entry_lookup_by_id (id)
  entry_lookup_by_location (uri)
  entry_lookup_from_string (str, is_id)
  entry_matches_ext_db_key (entry, key)
  entry_move_to_trash (entry)
  entry_request_extra_metadata (entry, property_name)
  entry_set (entry, propid, value)
  entry_type_get_by_name (name)
  entry_write_metadata_changes (entry, changes)
  evaluate_query (query, entry)
  get_property_type (property_id)
  load ()
  nice_elt_name_from_propid (propid)
  propid_from_nice_elt_name (name)
  query_append_params (query, type, prop, value)
  query_append_prop_multiple (query, propid, items)
  query_deserialize (parent)
  query_is_time_relative (query)
  query_preprocess (query)
  query_serialize (query, parent)
  query_to_string (query)
  register_entry_type (entry_type)
  save ()
  save_async ()
  shutdown ()
  start_action_thread ()

Virtual Methods

Inherited:GObject.Object (7)
  do_entry_added (entry)
  do_entry_deleted (entry)
  do_entry_extra_metadata_gather (entry, data)
  do_entry_extra_metadata_notify (entry, field, metadata)
  do_entry_extra_metadata_request (entry)
  do_entry_keyword_added (entry, keyword)
  do_entry_keyword_removed (entry, keyword)
  do_impl_do_full_query (query, results, cancel)
  do_impl_entry_count ()
  do_impl_entry_count_by_type (type)
  do_impl_entry_delete (entry)
  do_impl_entry_delete_by_type (type)
  do_impl_entry_get (entry, propid, value)
  do_impl_entry_keyword_add (entry, keyword)
  do_impl_entry_keyword_has (entry, keyword)
  do_impl_entry_keyword_remove (entry, keyword)
  do_impl_entry_new (entry)
  do_impl_entry_set (entry, propid, value)
  do_impl_entry_type_registered (type)
  do_impl_evaluate_query (query, entry)
  do_impl_load (cancel)
  do_impl_lookup_by_id (id)
  do_impl_lookup_by_location (uri)
  do_impl_save ()
  do_load_complete ()
  do_load_error (uri, msg)
  do_read_only (readonly)
  do_save_complete ()
  do_save_error (uri, error)

Properties

Name Type Flags Short Description
dry-run bool r/w Whether or not changes should be saved
name str r/w name
no-update bool r/w Whether or not to update the database

Signals

Inherited:GObject.Object (1)
Name Short Description
create-mount-op Emitted to request creation of a Gio.MountOperation to use to mount a volume.
entry-added Emitted when a new entry is added to the database.
entry-changed Emitted when a database entry is modified.
entry-deleted Emitted when an entry is deleted from the database.
entry-extra-metadata-gather Emitted to gather all available extra metadata for a database entry.
entry-extra-metadata-notify This signal is emitted when an extra metadata value is provided for a specific entry independantly of an extra metadata request.
entry-extra-metadata-request This signal is emitted to allow extra (transient) metadata to be supplied for the given entry.
entry-keyword-added Emitted when a keyword is added to an entry.
entry-keyword-removed Emitted when a keyword is removed from an entry.
load-complete Emitted when the database is fully loaded.
read-only Emitted when the database becomes temporarily read-only, or becomes writeable after being read-only.
save-complete Emitted when the database has been saved.
save-error Emitted when an error occurs while saving the database.

Fields

Inherited:GObject.Object (1)
Name Type Access Description
parent GObject.Object r  

Class Details

class RB.RhythmDB(**kwargs)
Bases:GObject.Object
Abstract:Yes
Structure:RB.RhythmDBClass

RB.RhythmDB is an in-memory database containing RB.RhythmDBEntry items. It runs queries represented as GLib.PtrArray s containing query criteria, feeding the results into RB.RhythmDBQueryResults implementations such as RB.RhythmDBQueryModel. From there, entries are grouped by particular property values to form RB.RhythmDBPropertyModel s.

RB.RhythmDBEntry contains a fixed set of properties, defined by RB.RhythmDBPropType,

classmethod compute_status_normal(n_songs, duration, size, singular, plural)
Parameters:
  • n_songs (int) – the number of tracks.
  • duration (int) – the total duration of the tracks.
  • size (int) – the total size of the tracks.
  • singular (str) – singular form of the format string to use for entries (eg “%d song”)
  • plural (str) – plural form of the format string to use for entries (eg “%d songs”)
Returns:

the string, which should be freed with GLib.free.

Return type:

str

Creates a string containing the “status” information about a list of tracks. The singular and plural strings must be used in a direct ngettext call elsewhere in order for them to be marked for translation correctly.

classmethod error_quark()
Returns:error quark
Return type:int

Returns the #GQuark used for RB.RhythmDBError information

classmethod get_error_entry_type()
Returns:the entry type for import errors
Return type:RB.RhythmDBEntryType

Returns the RB.RhythmDBEntryType for import errors

classmethod get_ignore_entry_type()
Returns:the entry type for ignored files
Return type:RB.RhythmDBEntryType

Returns the RB.RhythmDBEntryType for ignored files

classmethod get_song_entry_type()
Returns:the entry type for normal songs
Return type:RB.RhythmDBEntryType

Returns the RB.RhythmDBEntryType for normal songs.

classmethod query_concatenate(query1, query2)
Parameters:

Appends query2 to query1.

classmethod query_copy(array)
Parameters:array (GLib.PtrArray) – the query to copy.
Returns:a copy of the passed query. It must be freed with RB.RhythmDB.query_free()
Return type:GLib.PtrArray

Creates a copy of a query.

classmethod query_free(query)
Parameters:query (GLib.PtrArray) – a query.

Frees the query query

add_uri(uri)
Parameters:uri (str) – the URI to add an entry/entries for

Adds the file(s) pointed to by uri to the database, as entries of type RHYTHMDB_ENTRY_TYPE_SONG. If the URI is that of a file, it will be added. If the URI is that of a directory, everything under it will be added recursively.

add_uri_with_types(uri, type, ignore_type, error_type)
Parameters:

Adds the file(s) pointed to by uri to the database, as entries of the specified type. If the URI points to a file, it will be added. The the URI identifies a directory, everything under it will be added recursively.

commit()

Apply all database changes, and send notification of changes and new entries. This needs to be called after any changes have been made, such as a group of RB.RhythmDB.entry_set() calls, or a new entry has been added.

do_full_query_async_parsed(results, query)
Parameters:

Asynchronously runs a parsed query across the database, feeding matching entries to results in chunks. This can only be called from the main thread.

Since results is always a RhythmDBQueryModel, use the RB.RhythmDBQueryModel ::complete signal to identify when the query is complete.

do_full_query_parsed(results, query)
Parameters:

Synchronously evaluates the parsed query query, feeding results to results in chunks. Does not return until the query is complete.

emit_entry_added(entry)
Parameters:entry (RB.RhythmDBEntry) –
emit_entry_deleted(entry)
Parameters:entry (RB.RhythmDBEntry) –
emit_entry_extra_metadata_notify(entry, property_name, metadata)
Parameters:

Emits a signal describing extra metadata for the entry. The property_name argument is emitted as the ::detail part of the “entry_extra_metadata_notify” signal and as the ‘field’ parameter. Handlers can ensure they only get metadata they are interested in by supplying an appropriate ::detail part when connecting to the signal. If handlers are interested in the metadata they should ref or copy the contents of metadata and unref or free it when they are finished with it.

entry_count()
Returns:number of entries
Return type:int

Returns the number of entries in the database.

entry_count_by_type(entry_type)
Parameters:entry_type (RB.RhythmDBEntryType) – a RB.RhythmDBEntryType.
Returns:entry count
Return type:int

Returns the number of entries in the database of a particular type.

entry_delete(entry)
Parameters:entry (RB.RhythmDBEntry) – a RB.RhythmDBEntry.

Delete entry entry from the database, sending notification of its deletion. This is usually used by sources where entries can disappear randomly, such as a network source.

entry_delete_by_type(type)
Parameters:type (RB.RhythmDBEntryType) – type of entried to delete.

Delete all entries from the database of the given type. This is usually used by non-permanent sources when they disappear, such as removable media being removed, or a network share becoming unavailable.

entry_foreach(func, *data)
Parameters:

Calls the given function for each of the entries in the database.

entry_foreach_by_type(entry_type, func, *data)
Parameters:

Calls the given function for each of the entries in the database of a given type.

entry_gather_metadata(entry)
Parameters:entry (RB.RhythmDBEntry) – a RB.RhythmDBEntry
Returns:a RB.StringValueMap containing metadata for the entry. This must be freed using GObject.Object.unref.
Return type:RB.StringValueMap

Gathers all metadata for the entry. The returned GLib.HashTable maps property names and extra metadata names (described under rhythmdb_entry_request_extra_metadata) to GValues. Anything wanting to provide extra metadata should connect to the “entry_extra_metadata_gather” signal.

entry_get(entry, propid, val)
Parameters:

Gets a property of an entry, storing it in the given GObject.Value.

entry_keyword_add(entry, keyword)
Parameters:
Returns:

whether the keyword was already on the entry

Return type:

bool

Adds a keyword to an entry.

entry_keyword_has(entry, keyword)
Parameters:
Returns:

whether the keyword had been added to the entry.

Return type:

bool

Checks whether a keyword is has been added to an entry.

entry_keyword_remove(entry, keyword)
Parameters:
Returns:

whether the keyword had previously been added to the entry.

Return type:

bool

Removed a keyword from an entry.

entry_keywords_get(entry)
Parameters:entry (RB.RhythmDBEntry) – a RB.RhythmDBEntry.
Returns:the list of keywords that have been added to the entry.
Return type:[RB.RefString]

Gets the list ofkeywords that have been added to an entry.

entry_lookup_by_id(id)
Parameters:id (int) – entry ID
Returns:the entry with id id, or None if no such entry exists.
Return type:RB.RhythmDBEntry

Looks up the entry with id id.

entry_lookup_by_location(uri)
Parameters:uri (str) – the URI of the entry to lookup.
Returns:the entry with location uri, or None if no such entry exists.
Return type:RB.RhythmDBEntry

Looks up the entry with location uri.

entry_lookup_from_string(str, is_id)
Parameters:
  • str (str) – string
  • is_id (bool) – whether the string is an entry ID or a location.
Returns:

the entry matching the string, or None if no such entry exists.

Return type:

RB.RhythmDBEntry

Locates an entry using a string containing either an entry ID or a location.

entry_matches_ext_db_key(entry, key)
Parameters:
Returns:

True if the key matches the entry

Return type:

bool

Checks whether key matches entry.

entry_move_to_trash(entry)
Parameters:entry (RB.RhythmDBEntry) – RB.RhythmDBEntry to trash

Trashes the file represented by #entry. If possible, the file is moved to the user’s trash directory and the entry is set to hidden, otherwise the error will be stored as the playback error for the entry.

entry_request_extra_metadata(entry, property_name)
Parameters:
Returns:

an allocated, initialised, set GObject.Value, or None

Return type:

GObject.Value

Emits a request for extra metadata for the entry. The property_name argument is emitted as the ::detail part of the “entry_extra_metadata_request” signal. It should be a namespaced RDF predicate e.g. from Dublin Core, MusicBrainz, or internal to Rhythmbox (namespace “rb:”). Suitable predicates would be those that are expensive to acquire or only apply to a limited range of entries. Handlers capable of providing a particular predicate may ensure they only see appropriate requests by supplying an appropriate ::detail part when connecting to the signal. Upon a handler returning a non-None value, emission will be stopped and the value returned to the caller; if no handlers return a non-None value, the caller will receive None. Priority is determined by signal connection order, with GObject.ConnectFlags.AFTER providing a second, lower rank of priority. A handler returning a value should do so in a GObject.Value allocated on the heap; the accumulator will take ownership. The caller should unset and free the GObject.Value if non-None when finished with it.

entry_set(entry, propid, value)
Parameters:

This function can be called by any code which wishes to change a song property and send a notification. It may be called when the database is read-only; in this case the change will be queued for an unspecified time in the future. The implication of this is that RB.RhythmDB.entry_get() may not reflect the changes immediately. However, if this property is exposed in the user interface, you should still make the change in the widget. Then when the database returns to a writable state, your change will take effect in the database too, and a notification will be sent at that point.

Note that you must call RB.RhythmDB.commit() at some point after invoking this function, and that even after the commit, your change may not have taken effect.

entry_type_get_by_name(name)
Parameters:name (str) – name of the type to look for
Returns:the RB.RhythmDBEntryType
Return type:RB.RhythmDBEntryType

Locates a RB.RhythmDBEntryType by name. Returns None if no entry type is registered with the specified name.

entry_write_metadata_changes(entry, changes)
Parameters:
Raises:

GLib.Error

This can be called from a RB.RhythmDBEntryType sync_metadata function when the appropriate action is to write the metadata changes to the file at the entry’s location.

evaluate_query(query, entry)
Parameters:
Returns:

whether the given entry matches the criteria of the given query.

Return type:

bool

Evaluates the given entry against the given query.

get_property_type(property_id)
Parameters:property_id (int) – a property ID (RB.RhythmDBPropType)
Returns:property value type
Return type:GObject.GType

Returns the GObject.GType for the value of the property.

load()

Load the database from disk.

nice_elt_name_from_propid(propid)
Parameters:propid (RB.RhythmDBPropType) – property ID
Returns:property ID name, must not be freed
Return type:libxml2.Char

Returns a short non-translated name for the property #propid. This name is suitable for use as an XML tag name, for example.

propid_from_nice_elt_name(name)
Parameters:name (libxml2.Char) – a property ID name
Returns:a RB.RhythmDBPropType, or -1
Return type:int

Converts a property name returned by rhythmdb_propid_from_nice_elt_name back to a RB.RhythmDBPropType. If the name does not match a property ID, -1 will be returned instead.

query_append_params(query, type, prop, value)
Parameters:

Appends a new query term to query.

query_append_prop_multiple(query, propid, items)
Parameters:

Appends a set of criteria to a query to match against any of the values listed in items.

query_deserialize(parent)
Parameters:parent (libxml2.NodePtr) – parent XML node of serialized query
Returns:deserialized query.
Return type:GLib.PtrArray

Converts a serialized query back into a GPtrArray query.

query_is_time_relative(query)
Parameters:query (GLib.PtrArray) – the query to check
Returns:True if time-relative criteria found
Return type:bool

Checks if a query contains any time-relative criteria.

query_preprocess(query)
Parameters:query (GLib.PtrArray) – query to preprocess

Preprocesses a query to prepare it for execution. This has two main roles: to perform expensive data transformations once per query, rather than once per entry, and converting criteria to lower-level forms that are implemented by the database backend.

For RB.RhythmDBPropType.SEARCH_MATCH, this converts the search terms into an array of case-folded words.

When matching against case-folded properties such as RB.RhythmDBPropType.TITLE_FOLDED, this case-folds the query value.

When performing year-based criteria such as RB.RhythmDBQueryType.YEAR_LESS_THAN, it converts the year into the Julian date such that a simple numeric comparison will work.

query_serialize(query, parent)
Parameters:

Converts query into XML form as a child of parent. It can be converted back into a query by passing parent to rhythmdb_query_deserialize.

query_to_string(query)
Parameters:query (GLib.PtrArray) – a query.
Returns:allocated string form of the query
Return type:str

Returns a supposedly human-readable form of the query. This is only intended for debug usage.

register_entry_type(entry_type)
Parameters:entry_type (RB.RhythmDBEntryType) – the new entry type to register

Registers a new entry type. An entry type must be registered before any entries can be created for it.

save()

Save the database to disk, not returning until it has been saved.

save_async()

Save the database to disk, asynchronously.

shutdown()

Ceases all RB.RhythmDB operations, including stopping all directory monitoring, and removing all actions and events currently queued.

start_action_thread()

Starts the RB.RhythmDB processing thread. Needs to be called during startup.

do_entry_added(entry) virtual
Parameters:entry (RB.RhythmDBEntry) –
do_entry_deleted(entry) virtual
Parameters:entry (RB.RhythmDBEntry) –
do_entry_extra_metadata_gather(entry, data) virtual
Parameters:
do_entry_extra_metadata_notify(entry, field, metadata) virtual
Parameters:
do_entry_extra_metadata_request(entry) virtual
Parameters:entry (RB.RhythmDBEntry) –
Return type:GObject.Value
do_entry_keyword_added(entry, keyword) virtual
Parameters:
do_entry_keyword_removed(entry, keyword) virtual
Parameters:
do_impl_do_full_query(query, results, cancel) virtual
Parameters:
do_impl_entry_count() virtual
Return type:int
do_impl_entry_count_by_type(type) virtual
Parameters:type (RB.RhythmDBEntryType) –
Return type:int
do_impl_entry_delete(entry) virtual
Parameters:entry (RB.RhythmDBEntry) –
do_impl_entry_delete_by_type(type) virtual
Parameters:type (RB.RhythmDBEntryType) –
do_impl_entry_get(entry, propid, value) virtual
Parameters:
do_impl_entry_keyword_add(entry, keyword) virtual
Parameters:
Return type:

bool

do_impl_entry_keyword_has(entry, keyword) virtual
Parameters:
Return type:

bool

do_impl_entry_keyword_remove(entry, keyword) virtual
Parameters:
Return type:

bool

do_impl_entry_new(entry) virtual
Parameters:entry (RB.RhythmDBEntry) –
do_impl_entry_set(entry, propid, value) virtual
Parameters:
Return type:

bool

do_impl_entry_type_registered(type) virtual
Parameters:type (RB.RhythmDBEntryType) –
do_impl_evaluate_query(query, entry) virtual
Parameters:
Return type:

bool

do_impl_load(cancel) virtual
Parameters:cancel (Gio.Cancellable or None) –
Return type:bool
do_impl_lookup_by_id(id) virtual
Parameters:id (int) –
Return type:RB.RhythmDBEntry
do_impl_lookup_by_location(uri) virtual
Parameters:uri (RB.RefString) –
Return type:RB.RhythmDBEntry
do_impl_save() virtual
do_load_complete() virtual
do_load_error(uri, msg) virtual
Parameters:
do_read_only(readonly) virtual
Parameters:readonly (bool) –
do_save_complete() virtual
do_save_error(uri, error) virtual
Parameters:

Signal Details

RB.RhythmDB.signals.create_mount_op(rhythm_d_b)
Signal Name:create-mount-op
Flags:RUN_LAST
Parameters:rhythm_d_b (RB.RhythmDB) – The object which received the signal
Returns:a Gio.MountOperation (usually actually a Gtk.MountOperation)
Return type:Gio.MountOperation

Emitted to request creation of a Gio.MountOperation to use to mount a volume.

RB.RhythmDB.signals.entry_added(rhythm_d_b, entry)
Signal Name:

entry-added

Flags:

RUN_LAST

Parameters:

Emitted when a new entry is added to the database.

RB.RhythmDB.signals.entry_changed(rhythm_d_b, entry, changes)
Signal Name:

entry-changed

Flags:

RUN_LAST

Parameters:

Emitted when a database entry is modified. The changes list contains a structure for each entry property that has been modified.

RB.RhythmDB.signals.entry_deleted(rhythm_d_b, entry)
Signal Name:

entry-deleted

Flags:

RUN_LAST

Parameters:

Emitted when an entry is deleted from the database.

RB.RhythmDB.signals.entry_extra_metadata_gather(rhythm_d_b, entry, data)
Signal Name:

entry-extra-metadata-gather

Flags:

RUN_LAST

Parameters:

Emitted to gather all available extra metadata for a database entry. Handlers for this signal should insert any metadata they can provide into the string-value map. Only immediately available metadata items should be returned. If one or more metadata items is not immediately available, the handler should not initiate an attempt to retrieve them.

RB.RhythmDB.signals.entry_extra_metadata_notify(rhythm_d_b, entry, field, metadata)
Signal Name:

entry-extra-metadata-notify

Flags:

RUN_LAST, DETAILED

Parameters:

This signal is emitted when an extra metadata value is provided for a specific entry independantly of an extra metadata request.

RB.RhythmDB.signals.entry_extra_metadata_request(rhythm_d_b, entry)
Signal Name:

entry-extra-metadata-request

Flags:

RUN_LAST, DETAILED

Parameters:
Returns:

the extra metadata value

Return type:

GObject.Value

This signal is emitted to allow extra (transient) metadata to be supplied for the given entry. The detail of the signal invocation describes the specific metadata value being requested. If the object handling the signal can provide the requested item, but it isn’t immediately available, it can initiate an attempt to retrieve it. If successful, it would call rhythmdb_emit_entry_extra_metadata_notify when the metadata is available.

RB.RhythmDB.signals.entry_keyword_added(rhythm_d_b, entry, keyword)
Signal Name:

entry-keyword-added

Flags:

RUN_LAST

Parameters:

Emitted when a keyword is added to an entry.

RB.RhythmDB.signals.entry_keyword_removed(rhythm_d_b, entry, keyword)
Signal Name:

entry-keyword-removed

Flags:

RUN_LAST

Parameters:

Emitted when a keyword is removed from an entry.

RB.RhythmDB.signals.load_complete(rhythm_d_b)
Signal Name:load-complete
Flags:RUN_LAST
Parameters:rhythm_d_b (RB.RhythmDB) – The object which received the signal

Emitted when the database is fully loaded.

RB.RhythmDB.signals.read_only(rhythm_d_b, readonly)
Signal Name:

read-only

Flags:

RUN_LAST

Parameters:
  • rhythm_d_b (RB.RhythmDB) – The object which received the signal
  • readonly (bool) – True if the database is read-only

Emitted when the database becomes temporarily read-only, or becomes writeable after being read-only.

RB.RhythmDB.signals.save_complete(rhythm_d_b)
Signal Name:save-complete
Flags:RUN_LAST
Parameters:rhythm_d_b (RB.RhythmDB) – The object which received the signal

Emitted when the database has been saved.

RB.RhythmDB.signals.save_error(rhythm_d_b, uri, error)
Signal Name:

save-error

Flags:

RUN_LAST

Parameters:
  • rhythm_d_b (RB.RhythmDB) – The object which received the signal
  • uri (str) – URI of the database file
  • error (object or None) – the error that occurred

Emitted when an error occurs while saving the database.

Property Details

RB.RhythmDB.props.dry_run
Name:dry-run
Type:bool
Default Value:False
Flags:READABLE, WRITABLE

If True, no metadata changes will be written back to media fies.

RB.RhythmDB.props.name
Name:name
Type:str
Default Value:None
Flags:READABLE, WRITABLE

Database name. Not sure whta this is used for.

RB.RhythmDB.props.no_update
Name:no-update
Type:bool
Default Value:False
Flags:READABLE, WRITABLE

If True, the database will not be updated.