Session is the main entrance to using libmunin.
It implements a caching layer around the lower level API, being able to save a usage-Session for later re-use. The session data will be saved packed on disk as a .gzip archive.
Apart from this it holds the Mask - in simple words: the part where you tell libmunin what data you have to offer and how you want to configure the processing of it.
Main API to libmunin and caching layer.
Create a new session:
Parameters: |
|
---|
Return the song with a certain uid.
Raises KeyError: | |
---|---|
On invalid uid. | |
Returns: | a song object which has the same uid attribute. |
Create a new session:
Parameters: |
|
---|
list of weak references to the object (if defined)
Add a song with the values in the value_mapping.
This function should be always called like this to trigger a rebuild:
>>> with session.transaction():
... session.add({'genre': 'death metal', ...})
Parameters: | value_mapping (dict) – A mapping Attribute : Value. |
---|---|
Raises KeyError: | |
If an unknown Attribute was used. | |
Returns: | The UID of the newly added song. |
yield the associated munin.database.Database
Get the munin.distance.DistanceFunction for key
Explain the recommendation you got.
Usage Example:
>>> explain_recommendation(seed_song, recommendation)
(~0.4, [
('genre', 0.1), # Very similar common attribute
('moodbar', 0.2), # Quite similar
('lyrics', 0.5) # Well, that's okay.
])
Parameters: |
|
---|---|
Retruns: | Tuple of the total distance to each other and a list of pairs that consist of (attribute_name: subdistance_float) |
Feed a single song to the history.
If the feeded song is not yet in the database, it will be added automatically.
Parameters: | song – The song to feed in the history. |
---|
Search the database for a subset of the attributes/values in subset.
Example:
>>> find_matching_attributes({'genre': 'metal', 'artist': 'Debauchery'})
# yields songs from Debauchery with that have the exact genre 'metal'
Numeric example:
>>> find_matching_attributes({'rating': 5}, max_numeric_offset=1)
# yield songs with rating 4-5
Warning
If max_numeric_offset is used, you may only use attributes that support the __sub__ operator, otherwise a TypeError will be raised.
Raises: | |
---|---|
Parameters: |
|
Returns: | A lazy iterator over the matching songs. |
Fix the previosuly rebuild graph.
This means checking if unsorted distances can be found (which should not happend) and checking if unidirectional edges can be found (which get deleted).
You should this contextmanager when calling insert() or remove().
Load a cached session from a file on the disk.
Example usage:
>>> Session.from_archive_path('/tmp/test.gz')
<Session object at 0x2343424>
Note
If you prefer to save the sessions in XDG_CACHE_HOME anyway, just use Session.from_name().
Parameters: | full_path (str) – a path to a packed session. |
---|---|
Returns: | A cached session. |
Return type: | Session |
Like from_archive_path(), but be clever and load it from ${XDG_CACHE_HOME}/libmunin/<session_name>/session.pickle
Parameters: | session_name (str) – The name of a session. |
---|---|
Returns: | A cached session. |
Return type: | Session |
Insert a song without triggering a rebuild.
This function should be always called like this to trigger a cleanup of the graph:
>>> with session.fix_graph():
... session.insert({'genre': 'death metal', ...})
The rest is the same as with add().
Modify an existing and known song by the attributes mentioned in sub_value_mapping.
This should be run during the fix_graph contextmanager.
Usage example:
>>> with session.fix_graph():
... session.modify(some_song, {'rating': 5})
One usecase is shown in the example, the adjustment of the rating.
Note
This is not a cheap function. The song is removed and all distances to it are recalculated under the hood.
See also
Warning
Attention! The returned uid is the same as before, but the underlying song is different. Do not compare by reference!
Parameters: |
|
---|---|
Returns: | song.uid |
Get the playcount of a song.
If no playcount is known for it, 0 will be returned.
Returns: | Number of times this song was played. |
---|---|
Return type: | int |
Get all playcounts, or the most common.
Parameters: | n – The number of most common plays to select. Might be less. |
---|---|
Returns: | A list of tuples if n > 0, or a Mapping. |
Find n recommendations solely from intelligent guessing.
This will try to find a good rule, that indicates a user’s favourite song, and will call recommendations_from_seed() on it. If no rules are known, the most played song will be chosen. If there is none, a random song is picked.
The first song in the recommendations yielded is the seed song.
Parameters: |
|
---|
Give ‘n’ recommendations based on ‘song’.
The first song in the recommendations yielded is the seed song.
Parameters: |
|
---|---|
Returns: | An iterator that yields recommend songs. |
Recommend songs based on a certain attribute.
For example you can search by a certain genre by calling it like this:
>>> recommend_from_attributes({'genre', 'death metal'}, ...)
The value passed must match fully, no fuzzy matching is performed.
Returns: | Recommendations like the others or None if no suitable song found. |
---|
Remove a single song (or UID) from the Graph.
This function will try to close the hole. If insert() is called afterwards the UID of the deleted song will be re-used.
Returns: | The UID of the deleted song. |
---|
Class managing Database concerns.
Usually you access this as .database attribute of munin.session.Session.
You can do the following tasks with it:
Note
The division of munin.session.Session and Database is purely cosmetical. Both classes cannot exist on its own.
Lookup a certain song by it’s uid.
Parameters: | uid – A uid previously given by |
---|---|
Returns: | a munin.song.Song, which is a read-only mapping of normalized attributes. |
Plot the current graph for debugging purpose.
Will try to open an installed image viewer - does not return an image.
Parameters: |
|
---|
Example:
>>> from munin.session import DefaultConfig as default
>>> default.max_neighbors
100
Alternatively without DefautltConfig:
>>> from munin.session import DEFAULT_CONFIG
>>> DEFAULT_CONFIG['max_neighbors']
100
The sole purpose of this class is to save a bit of typing.
Note
It is possible to mutate the DEFAULT_CONFIG dict to have the same defaults for every session.