Whenever you want to retrieve some metadata you use a Query:
# one import for everything
import plyr
# A query understands lots of options, they can be either passed
# on __init__ as keywords, or can be set afterwards as properties
qry = plyr.Query(artist='Tenacious D', title='Deth Starr', get_type='lyrics')
# Once a query is readily configured you can commit it
# (you can even commit it more than once)
items = qry.commit()
# Well, great. Now we have one songtext.
# Since libglyr may return more than one item,
# commit() always returns a list. The default value is 1 item though.
# The list contains ,,Caches'', which are basically any sort of metadata.
print(items[0].data)
Default Values for any option can be accessed by instantiating an empty Query, and using the provided properties.
A Query is an object defining a search term for libglyr. As a minimum the ,,get_type’’ and ,,artist’’ and/or the ,,album’’ or ,,title’’ properties shall be set.
The constructor takes a list of keywords, these keywords are the same as the propertynames below.
A Query can be committed with commit(), which blocks till execution is done. On the way a callback method may be called as set by the equally named property. One may cancel a Query from another thread by calling cancel() on it, or returning a value other than 0 from the callback.
Set the album to search for.
| Album : | Any valid string. |
|---|
For image-fetchers only: limit image formats to a list of formats.
Default:
['png', 'jpg', 'gif', 'jpeg']
| Allowed_formats : | |
|---|---|
| a list of image format endings | |
Set the artist to search for.
| Artist : | Any valid string. |
|---|
Set a function that is called when an item is readily downloaded.
The function must take two arguments:
def funny_smelling_callback(cache, query):
# query is the Query you used to search this.
# cache is the actual item.
# One may return:
# - 'ok' -> continue search
# - 'post_stop' -> append item to results, and stop
# - 'pre_stop' -> stop immediately, return all results before
#
# Returning nothing is the same as 'ok'
return 'ok'
| Py_func : | a method, function or any object that implements __call__() |
|---|
Stop an already started query from another thread.
This does not make commit() return immediately, it’s rather a soft shutdown that finishes already running parsers, but do not download any new data.
Commit a configured Query. This function blocks until execution is done.
| Returns: | a list of byteblobs or [] on error, use error to find out what happened. |
|---|
Set a local database to be used by this query.
| Database : | An instance of plyr.Database |
|---|
A boolean, if set to True a local cache is queried first.
If the database property is not set, this option has no effect at all. Defaults to True.
| Db_autoread : | True or False |
|---|
Auto-write downloaded items to database. Defaults to True.
If the database property is not set, this option has no effect at all.
| Db_autowrite : | True or False |
|---|
Download images or just return links to them?
String representation of internally happened error (might be “No Error”)
For textitems only: try to convert input to utf-8 always, throw away if invalidly encoded.
| Force_utf8 : | True or False |
|---|
Max levenshtein distance difference for fuzzy matching.
libglyr features fuzzy matching to enhance search results. Look at the string “Equilibrium” and the accidentally mistyped version “Aquillibriu”: Those strings will be compares using the “Levenshtein distance” (http://en.wikipedia.org/wiki/Levenshtein_distance) which basically counts the number of insert, substitute and delete operations to transform Equilibrium”” into “Aquillibriu”. The distance in this case is 3 since three edit-operations are needed (one insert, substitute and deletion) The fuzziness parameter is the maximum distance two strings may have to match. A high distance (like about 10) matches even badly mistyped strings, but also introduces bad results. Low settings however will omit some good results. The default values is currently 4. To be more secure some correction is applied:
Example:
| Fuzzyness : | a positive integer |
|---|
The type of metadata you want to retrieve.
For a complete list use:
print(list(plyr.PROVIDERS.keys()))
| Get_type_value : | |
|---|---|
| Any of the above strings, may do nothing with a bad type! | |
Limits min. and max. size of images in pixel.
Please note: This is used by glyr only as a hint. There is no guarantee that the actual image is between this limits.
| Size_tuple : | A tuple of a min. and max. in pixel (e.g. (100, 500)) |
|---|
The language you want the items in, as ISO 639-1 language code (e.g. ‘de’, ‘en’...)
Note: There are only a few localized providers, and stuff like lyrics is localized anyway, but for example artist biographies are available in different languages.
When lang_aware_only is not set, all other providers are used too.
| Language : | Any of “en;de;fr;es;it;jp;pl;pt;ru;sv;tr;zh” |
|---|
Only query providers that have localized content
| Language_aware_only : | |
|---|---|
| True or False | |
How many items a single provider may retrieve (not very useful normally)
| Max_per_plugins : | |
|---|---|
| Any number, < 0 will be clamped to a high number. | |
Set the path to a audiofile, where a folder.jpg or similar may be near.
libglyr supports searching through the filesystem beginning with a certain file, or a directory containing e.g. folder.jpeg and some audio files.
See a more detailed description here: http://sahib.github.com/glyr/doc/html/libglyr-Glyr.html#glyr-opt-musictree-path
| Musictree_path : | |
|---|---|
| Something like ~/HD/Musik/DevilDriver/Beast/BlackSoulChoir.mp3 | |
Define how much input artist/album/title is normalized.
Normalization can be enabled for artist and album only with e.g.:
('artist', 'album', 'moderate')
| Norm : | A tuple containg one, or many of “artist”, “album”, “title”, “aggressive”, “moderate”, “none” |
|---|
The number of items you want to retrieve, 0 for infinite, by default 1
| Number : | Any number, < 0 will be clamped to 0. |
|---|
Max parallel downloads handles that glyr may open
| Parallel : | A positive integer, do not try 0 |
|---|
Pass a list of provider names to forbid glyr to search other providers.
‘all’ can be used to enable all providers, other providers can be prepended with a ‘-‘ to exclude them from the list,
To find out providernames programmatically use the PROVIDERS dict.
Examples:
['lastfm', 'google']
['all', '-lastfm']
See also: http://sahib.github.com/glyr/doc/html/libglyr-Glyr.html#glyr-opt-from
If you need to a proxy set, use it here.
| Proxy_string : | Passed in the form: [protocol://][user:pass@]yourproxy.domain[:port] |
|---|
A float between 0.0 and 1.0 that influences in which way providers are triggered.
0.0 means best speed, i.e. querying google for covers at first, 1.0 will query the little bit slower last.fm, which will deliver almost always HQ items.
| Qsratio : | Any number between 0.0 and 1.0, do not except magic improvements. |
|---|
Max redirects to allow for download handles.
| Redirects : | A positive integer, do not try 0 |
|---|
Max timeout in seconds to wait before a download handle is canceled.
| Timeout : | A timeout in seconds |
|---|
Set the title to search for.
| Title : | Any valid string. |
|---|
Set a certain user-agent on your own
Note: Some providers like discogs need a proper useragent set. Use with care therefore.
| Useragent : | A string like “libglyr/0.9.9 (Catholic Cat) +https://www.github.com/sahib/glyr” |
|---|
How verbose the library will print status messages.
0 -> no messages except fatal errors 1 -> warnings only 2 -> basic info 3 -> more info 4 -> very detailed debug messages
| Verbosity : | an integer in [0..4] |
|---|