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:
Update the file
spotify/api.h
with the latest header file from libspotify.Run the Invoke task
preprocess_header
defined intasks.py
by running:invoke preprocess_header
The task will update the
spotify/api.processed.h
file.Commit both header files so that they are distributed with pyspotify.
Thread safety utils¶
- spotify.serialized(f)[source]¶
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¶
Enumeration utils¶
- class spotify.utils.IntEnum(value)[source]¶
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='')[source]¶
Class decorator for automatically adding enum values.
The values are read directly from the
spotify.lib
CFFI wrapper around libspotify. All values starting withlib_prefix
are added. Thelib_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)[source]¶
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 theis_loaded
attribute. If it also has anerror()
method, it will be checked for errors to raise.After
timeout
seconds with no resultsTimeout
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)[source]¶
Helper class for making sequences from a length and getitem function.
The
sp_obj
is assumed to already have gotten an extra reference throughsp_*_add_ref
and to be automatically released throughsp_*_release
when thesp_obj
object is GC-ed.
String conversion utils¶
- spotify.utils.get_with_fixed_buffer(buffer_length, func, *args)[source]¶
Get a unicode string from a C function that takes a fixed-size buffer.
The C function
func
is called with any arguments given inargs
, a buffer of the givenbuffer_length
, andbuffer_length
.Returns the buffer’s value decoded from UTF-8 to a unicode string.
- spotify.utils.get_with_growing_buffer(func, *args)[source]¶
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 inargs
, 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)[source]¶
Converts bytes, unicode, and C char arrays to bytes.
Unicode strings are encoded to UTF-8.
- spotify.utils.to_bytes_or_none(value)[source]¶
Converts C char arrays to bytes and C NULL values to None.
- spotify.utils.to_unicode(value)[source]¶
Converts bytes, unicode, and C char arrays to unicode strings.
Bytes and C char arrays are decoded from UTF-8.