Module Reference

aiomixcloud.auth module

API access authorization

This module contains the class for Mixcloud API OAuth authorization. Specifically:

• MixcloudOAuth, producing authorization URLs and trading OAuth codes for access tokens.

class aiomixcloud.auth.MixcloudOAuth(oauth_root='https://www.mixcloud.com/oauth', *, client_id=None, client_secret=None, redirect_uri=None, raise_exceptions=None, mixcloud=None)

Bases: object

Mixcloud OAuth authorization

By having client_id and redirect_uri set, a MixcloudOAuth object provides authorization_url, a URL to forward the end user to, where they will be able to “allow the application access to their data”. It also provides the access_token() method, which trades an OAuth code for an access token (requiring client_secret as well as the previously mentionted attributes).

async access_token(code)

Send OAuth code to server and get an access token. If fail raise MixcloudOAuthError in case this is the setting (self._raise_exceptions or self.mixcloud._raise_exceptions), otherwise return None.

property authorization_url

Return authorization URL.

client_id

Client ID, provided by Mixcloud

client_secret

Client secret, provided by Mixcloud

mixcloud

The Mixcloud object whose session will be used to make the request from. If None, a new session will be created for the access token request.

oauth_root = 'https://www.mixcloud.com/oauth'

Default Mixcloud OAuth root URL

redirect_uri

Redirect URI, chosen by the developer

aiomixcloud.constants module

Constant values

This module includes constant, hard-coded values used throughout the package.

aiomixcloud.constants.API_ROOT = 'https://api.mixcloud.com'

Mixcloud API root URL

aiomixcloud.constants.DESCRIPTION_MAX_SIZE = 1000

Uploaded description maximum allowed size, in characters

aiomixcloud.constants.MIXCLOUD_ROOT = 'https://www.mixcloud.com'

Mixcloud root URL

aiomixcloud.constants.MP3_MAX_SIZE = 4294967296

Uploaded mp3 maximum allowed size, in bytes

aiomixcloud.constants.OAUTH_ROOT = 'https://www.mixcloud.com/oauth'

Mixcloud OAuth root URL

aiomixcloud.constants.OEMBED_ROOT = 'https://www.mixcloud.com/oembed'

Mixcloud oEmbed root URL

aiomixcloud.constants.PICTURE_MAX_SIZE = 10485760

Uploaded picture maximum allowed size, in bytes

aiomixcloud.constants.TAG_MAX_COUNT = 5

Tag maximum allowed count per upload

aiomixcloud.core module

Main functionality coordination

This module contains the class responsible for aggregating and organizing the main functionality and usage of the package. Specifically:

• Mixcloud, providing the interface of the package. Stores the basic configuration and preferences, holds the session which API calls are made from and has all the methods necessary to reach every endpoint of the API, as well as take advantage of its capabilities.

class aiomixcloud.core.Mixcloud(api_root='https://api.mixcloud.com', *, access_token=None, mixcloud_root='https://www.mixcloud.com', oembed_root='https://www.mixcloud.com/oembed', json_decoder_class=<class 'aiomixcloud.json.MixcloudJSONDecoder'>, resource_class=<class 'aiomixcloud.models.Resource'>, resource_list_class=<class 'aiomixcloud.models.ResourceList'>, raise_exceptions=False, session=None)

Bases: object

Asynchronous Mixcloud API handler

This class orchestrates the interaction of the package’s user with the Mixcloud API. Being ready for use with no explicit configuration at all, as well as being capable of customized operation, it provides the methods to hit the API. A common to use method and base for many of the rest, is the get() method, which takes a “key”, a URL segment corresponding to a unique API resource and returns a native, yet familiar and handy data structure representing that resource. There, also, exist a family of methods, like popular(), which receive pagination arguments and return a list of resources. The class provides some personalized methods, that is methods which require authorization to run, through an access token. These are methods like follow() and unfollow(). In this category belong the methods about uploading data to the server, upload() and edit(). Finally, there are methods about getting embedding information for some resource, like embed_html(). The class can be used as an asynchronous context manager to avoid having to call close() explicitly, which closes the session.

access_token

OAuth Access token

api_root = 'https://api.mixcloud.com'

Default Mixcloud API root URL

async close()

Close _session.

async discover(tag)

Get information about tag.

async edit(key, params, *, name=None)

Edit upload identified by key, as described by specified parameters.

async embed_html(*args, **kwargs)

Get embed data for given cloudcast, in HTML format using specified display options.

async embed_json(*args, **kwargs)

Get embed data for given cloudcast, in JSON format using specified display options.

async favorite(cloudcast)

Favorite cloudcast and return results of the request.

async follow(user)

Follow user and return results of the request.

async get(url, *, relative=True, create_connections=True, **params)

Send a GET request to API and return JSON-decoded data. If relative is True, url is considered relative to the API root, otherwise it is considered as an absolute URL.

async hot(params)

Get information about hot cloudcasts.

json_decoder_class

Default JSON decoder class

alias of MixcloudJSONDecoder

async listen_later(cloudcast)

Add cloudcast to “listen later” list and return results of the request.

async me()

Get information about user authorized by used access token.

mixcloud_root = 'https://www.mixcloud.com'

Default Mixcloud root URL

async new(params)

Get information about new cloudcasts.

async oembed(key, params)

Get oEmbed data for resource identified by key, in desirable format using specified display options.

oembed_root = 'https://www.mixcloud.com/oembed'

Default Mixcloud oEmbed root URL

async popular(params)

Get information about popular cloudcasts.

async repost(cloudcast)

Repost cloudcast and return results of the request.

resource_class

Resource model class

alias of Resource

resource_list_class

Resource model list class

alias of ResourceList

async search(query, params, *, type='cloudcast')

Search resources of type by query and return found information.

async unfavorite(cloudcast)

Unfavorite cloudcast and return results of the request.

async unfollow(user)

Unfollow user and return results of the request.

async unlisten_later(cloudcast)

Remove cloudcast from “listen later” list and return results of the request.

async unrepost(cloudcast)

Unrepost cloudcast and return results of the request.

async upload(mp3, name, params)

Upload file with filename indicated by mp3, named name and described by specified parameters.

aiomixcloud.datetime module

Datetime formatting

This module contains functions about presenting datetimes in various formats. Specifically:

• format_datetime(), returning a “YYYY-MM-DDTHH:MM:SSZ”-formatted datetime string out of a datetime-like value.

• to_timestamp(), returning a UNIX timestamp out of a datetime-like value.

The datetime-like argument of those functions can be a datetime object, a human-readable datetime string or a timestamp. Timezone-naive values will be treated as being in the local timezone. Result will be converted in UTC, if not already there.

aiomixcloud.datetime.format_datetime(value)

Return a datetime string in the “YYYY-MM-DDTHH:MM:SSZ” format, out of a datetime-like value.

aiomixcloud.datetime.to_timestamp(value)

Return a UNIX timestamp out of a datetime-like value.

aiomixcloud.decorators module

Function decorators

This module contains decorators for functions of the package. Specifically:

• displayed(), handling requests with varying response format and HTML display information by defining the proper arguments and passing a dict produced out of them to the decorated coroutine.

• paginated(), handling pagination of resource lists by defining the proper arguments, checking their validity and passing a dict produced out of them to the decorated coroutine.

• personal(), checking that access_token is set on the object which owns the decorated coroutine method, before awaiting it.

• targeting(), marking the decorated coroutine as one that targets a specific resource identified by a key, making said coroutine available as a Resource method.

• uploading(), handling requests that upload data to the server by defining the proper arguments and passing a dict produced out of them to the decorated coroutine.

aiomixcloud.decorators.displayed(coroutine)

Return a coroutine that takes arguments about desired response format and HTML display and makes a parameters dictionary out of them. Then, it passes that dictionary to the original coroutine, while awaiting it.

aiomixcloud.decorators.paginated(coroutine)

Return a coroutine that takes pagination arguments, runs checks on them and makes a parameters dictionary out of them. Then, it passes that dictionary to the original coroutine, while awaiting it.

aiomixcloud.decorators.personal(coroutine)

Return a coroutine method that checks if access_token is set on self.

aiomixcloud.decorators.targeting(coroutine)

Mark coroutine as one that targets a specific resource, so it can be used as a Resource method.

aiomixcloud.decorators.uploading(coroutine)

Return a coroutine that takes arguments about uploading cloudcast-related data, runs checks on them and makes a parameters dictionary out of them. Then, it passes that dictionary to the original coroutine, while awaiting it.

aiomixcloud.exceptions module

Exception types

This module contains custom exceptions raised during use of the package. Specifically:

• MixcloudError, indicating that API returned an error response.

• MixcloudOAuthError, indicating that something went wrong with the OAuth authorization process.

exception aiomixcloud.exceptions.MixcloudError(data)

Bases: Exception

Raised when API responds with error message.

extra

Dictionary with additional information

message

Error message

type

Error type, as described by the API

exception aiomixcloud.exceptions.MixcloudOAuthError(data)

Bases: Exception

Raised when OAuth authorization fails.

message

Error message

aiomixcloud.json module

JSON decoder

This module contains the class responsible for decoding the JSON data retrieved from the API requests. Specifically:

• MixcloudJSONDecoder, turning datetime-like strings to datetime objects.

class aiomixcloud.json.MixcloudJSONDecoder(*args, **kwargs)

Bases: JSONDecoder

Handles datetime values.

static object_hook(obj)

Turn eligible values to datetime objects and leave the rest unchanged.

aiomixcloud.models module

Basic data structures

This module contains the basic data structures used throughout the package. Specifically:

• _WrapMixin, a mixin providing type casting of accessed items.

• AccessDict, dict-like, supports accessing items by attribute. Accessed items are properly wrapped.

• AccessList, list-like, supports accessing Resource items by their “key” key. Accessed items are properly wrapped.

• Resource, like an AccessDict which has a “type” key. Gets methods for downloading its “connections”, that is the sub-entities “owned” by the resource. Mirrors methods of Mixcloud marked as “targeted” with their first argument as its key. Also provides a Resource.load() method to download full resource information in case it is partly loaded as an element of another API response.

• ResourceList, like an AccessDict which delegates string indexing and iterating over, to its “data” item. Supports pagination through the ResourceList.previous() and ResourceList.next() methods, which return a new object with the respective data.

class aiomixcloud.models.AccessDict(data, *, mixcloud)

Bases: _WrapMixin, UserDict

Dict-like model which supports accessing items using keys as attributes. Items are wrapped with a proper model, depending on their type. Original dict is stored in self.data.

class aiomixcloud.models.AccessList(data, *, mixcloud)

Bases: _WrapMixin, UserList

List-like model which supports accessing Resource-like items by matching their “key” item. Items are wrapped with a proper model, depending on their type. Original list is stored in self.data.

class aiomixcloud.models.Resource(data, *, full=False, create_connections=True, mixcloud)

Bases: AccessDict

Mixcloud API resource

A resource is like an AccessDict object which has a “type” key. When a “type” key is present in an API (sub)object, suggesting it has a unique URL, it is considered an API resource, that is an individual entity (a user, a cloudcast, a tag, etc). A Resource object has appropriately named methods for downloading information about its sub-entities (“connections”). It also mirrors “targeted” methods of its Mixcloud instance, passing them its key as a first argument. Targeted methods include “actions” (e.g follow() or unfavorite()), embed-related methods and edit().

async load(*, force=False)

Load full resource information from detail page. Do nothing in case _full is True, unless force is set. Return self, so this can be used in chained calls.

class aiomixcloud.models.ResourceList(data, *, mixcloud)

Bases: AccessDict

Contains a list of resources, with paging capabilities. Main data is stored in the 'data' item, while a 'paging' item may be present indicating URLs of the previous and next pages of the resource list, as well as a ‘name’ item describing the collection. Indexing falls back to self['data'] on failure, while iterating over and length concern “data” straight up.

async next()

Return next page of current resource list, or None if it is not found.

async previous()

Return previous page of current resource list, or None if it is not found.

aiomixcloud.sync module

Synchronous operation mode

This module contains synchronous (i.e blocking) versions of the package classes. Specifically:

• MixcloudOAuthSync, synchronous version of MixcloudOAuth, handling OAuth authorization.

• MixcloudSync, synchronous version of Mixcloud, handling main functionality coordination.

class aiomixcloud.sync.MixcloudOAuthSync(*args, **kwargs)

Bases: object

Synchronous version of MixcloudOAuth.

method(*args, method_name='__repr__')

Mirror original object’s method with given method_name.

method_name = '__repr__'

name = 'repr'

class aiomixcloud.sync.MixcloudSync(*args, **kwargs)

Bases: MixcloudSync

Synchronous version of Mixcloud with synchronous context management capabilities.

class aiomixcloud.sync.ResourceListSync(*args, **kwargs)

Bases: object

Synchronous version of ResourceList.

method(*args, method_name='__repr__')

Mirror original object’s method with given method_name.

method_name = '__repr__'

name = 'repr'

class aiomixcloud.sync.ResourceSync(*args, **kwargs)

Bases: object

Synchronous version of Resource.

method(*args, method_name='__repr__')

Mirror original object’s method with given method_name.

method_name = '__repr__'

name = 'repr'