Internal API

Warning

This page documents pyspotify’s internal APIs. Its intended audience is developers working on pyspotify itself. You should not use anything you find on this page in your own applications.

libspotify CFFI interface

The CFFI wrapper for the full libspotify API is available as spotify.ffi and spotify.lib.

spotify.ffi

cffi.FFI instance which knows about libspotify types.

>>> import spotify
>>> spotify.ffi.new('sp_audioformat *')
<cdata 'struct sp_audioformat *' owning 12 bytes>

spotify.lib

Dynamic wrapper around the full libspotify C API.

>>> import spotify
>>> msg = spotify.lib.sp_error_message(spotify.lib.SP_ERROR_OK)
>>> msg
<cdata 'char *' 0x7f29fd922cb5>
>>> spotify.ffi.string(msg)
'No error'

spotify.lib will always reflect the contents of the spotify/api.processed.h file in the pyspotify distribution. To update the API:

1. Update the file spotify/api.h with the latest header file from libspotify.

2. Run the Invoke task preprocess_header defined in tasks.py by running:

   invoke preprocess_header
   

   The task will update the spotify/api.processed.h file.

3. Commit both header files so that they are distributed with pyspotify.

Thread safety utils

spotify.serialized(f)

Decorator that serializes access to all decorated functions.

The decorator acquires pyspotify’s single global lock while calling any wrapped function. It is used to serialize access to:

• All calls to functions on spotify.lib.

• All code blocks working on pointers returned from functions on spotify.lib.

• All code blocks working on other internal data structures in pyspotify.

Together this is what makes pyspotify safe to use from multiple threads and enables convenient features like the EventLoop.

Internal function.

Event emitter utils

class spotify.utils.EventEmitter

Mixin for adding event emitter functionality to a class.

Enumeration utils

class spotify.utils.IntEnum(value)

An enum type for values mapping to integers.

Tries to stay as close as possible to the enum type specified in PEP 435 and introduced in Python 3.4.

spotify.utils.make_enum(lib_prefix, enum_prefix='')

Class decorator for automatically adding enum values.

The values are read directly from the spotify.lib CFFI wrapper around libspotify. All values starting with lib_prefix are added. The lib_prefix is stripped from the name. Optionally, enum_prefix can be specified to add a prefix to all the names.

Object loading utils

spotify.utils.load(session, obj, timeout=None)

Block until the object’s data is loaded.

If the session isn’t logged in, a spotify.Error is raised as Spotify objects cannot be loaded without being online and logged in.

The obj must at least have the is_loaded attribute. If it also has an error() method, it will be checked for errors to raise.

After timeout seconds with no results Timeout is raised.

If unspecified, the timeout defaults to 10s. Any timeout is better than no timeout, since no timeout would cause programs to potentially hang forever without any information to help debug the issue.

The method returns self to allow for chaining of calls.

Sequence utils

class spotify.utils.Sequence(sp_obj, add_ref_func, release_func, len_func, getitem_func)

Helper class for making sequences from a length and getitem function.

The sp_obj is assumed to already have gotten an extra reference through sp_*_add_ref and to be automatically released through sp_*_release when the sp_obj object is GC-ed.

String conversion utils

spotify.utils.get_with_fixed_buffer(buffer_length, func, *args)

Get a unicode string from a C function that takes a fixed-size buffer.

The C function func is called with any arguments given in args, a buffer of the given buffer_length, and buffer_length.

Returns the buffer’s value decoded from UTF-8 to a unicode string.

spotify.utils.get_with_growing_buffer(func, *args)

Get a unicode string from a C function that returns the buffer size needed to return the full string.

The C function func is called with any arguments given in args, a buffer of fixed size, and the buffer size. If the C function returns a size that is larger than the buffer already filled, the C function is called again with a buffer large enough to get the full string from the C function.

Returns the buffer’s value decoded from UTF-8 to a unicode string.

spotify.utils.to_bytes(value)

Converts bytes, unicode, and C char arrays to bytes.

Unicode strings are encoded to UTF-8.

spotify.utils.to_bytes_or_none(value)

Converts C char arrays to bytes and C NULL values to None.

spotify.utils.to_unicode(value)

Converts bytes, unicode, and C char arrays to unicode strings.

Bytes and C char arrays are decoded from UTF-8.

spotify.utils.to_unicode_or_none(value)

Converts C char arrays to unicode and C NULL values to None.

C char arrays are decoded from UTF-8.

spotify.utils.to_char(value)

Converts bytes, unicode, and C char arrays to C char arrays.

spotify.utils.to_char_or_null(value)

Converts bytes, unicode, and C char arrays to C char arrays, and None to C NULL values.

Country code utils

spotify.utils.to_country(code)

Converts a numeric libspotify country code to an ISO 3166-1 two-letter country code in a unicode string.

spotify.utils.to_country_code(country)

Converts an ISO 3166-1 two-letter country code in a unicode string to a numeric libspotify country code.