Examples

Most Simple

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import plyr

if __name__ == '__main__':
    # Create a Query, so plyr knows what you want to search
    qry = plyr.Query(get_type='lyrics', artist='Tenacious D', title='Deth Starr')

    # Now let it search all the providers
    items = qry.commit()

    # Convert lyrics (bytestring) to a proper UTF-8 text
    try:
        if len(items) > 0:
            print(str(items[0].data, 'UTF-8'))
    except UnicodeError as err:
        print('Cannot display lyrics, conversion failed:', err)

Callbacks (also with Database)

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import plyr


def on_item_received(cache, query):
    cache.print_cache()
    return 'post_stop'


if __name__ == '__main__':
    # Use a local db
    db = plyr.Database('/tmp')

    # Create a Query, so plyr knows what you want to search
    qry = plyr.Query(
            get_type='lyrics',
            artist='Tenacious D',
            title='Deth Starr',
            callback=on_item_received,
            verbosity=3,
            database=db)

    # Now let it search all the providers
    # Even with callback, it will return a list of caches
    qry.commit()

Threads and Cancellation

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import plyr
import random
from time import sleep
from threading import Thread

"""
Example on how to use the cancel() function of the Query.

If a Query has been started it wil block the calling thread.
This may be bad, when you want to do something
different in the meantime. You can safely run qry.commit()
in a seperate thread and do some data-sharing. But sometimes
(e.g. on application exit) you may want to stop all running queries.
This can be done via the cancel() function - it will stop
all running downloads associated with this query.

There is no cancel_all() function.
You gonna need a pool with all Queries you're running.

Note: cancel() will not stop __imediately__,
      since some provider may do some
      stuff that is hard to interrupt,
      but at least you do not need to care about cleanup.
"""

if __name__ == '__main__':
    # Some real query, that may take a bit longer
    # Notice this nice unicode support :-)
    qry = plyr.Query(artist='Аркона', title='Гой Роде Гой!', get_type='lyrics')

    # Our worker thread
    def cancel_worker():
        sleep(random.randrange(1, 4))
        print('cancel()')
        qry.cancel()

    # Spawn the thread.
    Thread(target=cancel_worker).start()

    # Start the query, and let's see.
    print('commit() started')
    items = qry.commit()
    print('commit() finished')
    print('Number of results:', len(items))

    # Print if any item was there, there shouldn't be any.
    if len(items) > 0:
        print(str(items[0].data, 'UTF-8'))

Database II

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import plyr


# This is called on each item found in the db
# The query is the search-query used to search this
# item, with artist, album and title filled.
# The query is useful to do delete or insert operations
# cache is the actual item, with all data filled.
def foreach_callback(query, cache):
    print(query)
    cache.print_cache()


if __name__ == '__main__':
    db = plyr.Database('/tmp')

    # Insert at least one dummy item, just in case the db is empty et
    # This will grow on each execution by one item.
    dummy_qry = plyr.Query(artist='Derp', album='Derpson', get_type='cover')
    dummy_itm = db.make_dummy()
    db.insert(dummy_qry, dummy_itm)

    # Now iterate over all items in the db
    # and exit afterwards
    db.foreach(foreach_callback)