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)[source]¶ Bases:
object
Mixcloud OAuth authorization
By having
client_id
andredirect_uri
set, aMixcloudOAuth
object providesauthorization_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 theaccess_token()
method, which trades an OAuth code for an access token (requiringclient_secret
as well as the previously mentionted attributes).-
_build_url
(segment)[source]¶ Return a
URL
consisting ofOAuth root
, followed by segment.
-
_check
()[source]¶ Check that
client ID
andredirect URI
have been set.
-
_oauth_root
= None¶ Base URL for OAuth-related requests
-
_raise_exceptions
= None¶ Whether to raise an exception when API responds with an error message. If not specified, use the respective setting of the
mixcloud
attribute. If that attribute is not specified, default toFalse
.
-
access_token
(code)[source]¶ Send OAuth code to server and get an access token. If fail raise
MixcloudOAuthError
in case this is the setting (self._raise_exceptions
orself.mixcloud._raise_exceptions
), otherwise returnNone
.
Return authorization URL.
-
client_id
= None¶ Client ID, provided by Mixcloud
-
client_secret
= None¶ Client secret, provided by Mixcloud
-
mixcloud
= None¶ The
Mixcloud
object whose session will be used to make the request from. IfNone
, 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
= None¶ 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)[source]¶ 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, likepopular()
, 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 likefollow()
andunfollow()
. In this category belong the methods about uploading data to the server,upload()
andedit()
. Finally, there are methods about getting embedding information for some resource, likeembed_html()
. The class can be used as an asynchronous context manager to avoid having to callclose()
explicitly, which closes the session.-
_api_root
= None¶ Base URL for all API requests
-
_delete_action
(url, action)[source]¶ Make HTTP DELETE request about action, to resource specified by url and return results.
-
_do_action
(url, action, method)[source]¶ Make HTTP method request about action, to resource specified by url and return results.
-
_embed
(cloudcast, params)[source]¶ Get embed data for cloudcast, in desirable format using specified display options.
-
_json_decode
= None¶ JSON decode function
-
_mixcloud_root
= None¶ Base Mixcloud URL
-
_native_result
(response)[source]¶ Wrap
_process_response()
and return appropriateAccessDict
object.
-
_oembed_root
= None¶ Base URL for all oEmbed requests
-
_post_action
(url, action)[source]¶ Make HTTP POST request about action, to resource specified by url and return results.
-
_process_response
(response)[source]¶ Return JSON-decoded data out of response. If fail to decode, let
JSONDecodeError
pass through in case_raise_exceptions
is set, otherwise returnNone
.
-
_proper_result
(response)[source]¶ Return the proper kind of result, based on Content-Type of response.
-
_raise_exceptions
= None¶ Whether to raise an exception when API responds with error message
-
_resource_class
= None¶ Class for resource model
-
_resource_list_class
= None¶ Class for resource model list
-
_session
= None¶ The
ClientSession
object to make requests from
-
_upload
(params, data, url)[source]¶ Add multipart fields from params to possibly half-filled data, POST it to url and return results.
-
static
_url_join
(url, segment)[source]¶ Return a
URL
consisting of url, followed by segment. Strip possibly existing leading slash of segment, for joining to work.
-
access_token
= None¶ OAuth Access token
-
api_root
= 'https://api.mixcloud.com'¶ Default Mixcloud API root URL
-
edit
(key, params, *, name=None)[source]¶ Edit upload identified by key, as described by specified parameters.
-
embed_html
(*args, **kwargs)[source]¶ Get embed data for given cloudcast, in HTML format using specified display options.
-
embed_json
(*args, **kwargs)[source]¶ Get embed data for given cloudcast, in JSON format using specified display options.
-
get
(url, *, relative=True, create_connections=True, **params)[source]¶ 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.
-
json_decoder_class
¶ alias of
aiomixcloud.json.MixcloudJSONDecoder
-
listen_later
(cloudcast)[source]¶ Add cloudcast to “listen later” list and return results of the request.
-
mixcloud_root
= 'https://www.mixcloud.com'¶ Default Mixcloud root URL
-
oembed
(key, params)[source]¶ 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
-
resource_class
¶ alias of
aiomixcloud.models.Resource
-
resource_list_class
¶ alias of
aiomixcloud.models.ResourceList
-
search
(query, params, *, type='cloudcast')[source]¶ Search resources of type by query and return found information.
-
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.
_as_utc
(dt)[source]¶ Convert and return given dt in UTC. If it is timezone-naive, treat it as being in the local timezone.
-
aiomixcloud.datetime.
_to_datetime
(value)[source]¶ Return a
datetime
object out of a datetime-like value. RaiseTypeError
on invalid argument.
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 aResource
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)[source]¶ 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)[source]¶ 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)[source]¶ Return a coroutine method that checks if access_token is set on self.
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.
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 todatetime
objects.
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 accessingResource
items by their “key” key. Accessed items are properly wrapped.Resource
, like anAccessDict
which has a “type” key. Gets methods for downloading its “connections”, that is the sub-entities “owned” by the resource. Mirrors methods ofMixcloud
marked as “targeted” with their first argument as its key. Also provides aResource.load()
method to download full resource information in case it is partly loaded as an element of another API response.ResourceList
, like anAccessDict
which delegates string indexing and iterating over, to its “data” item. Supports pagination through theResourceList.previous()
andResourceList.next()
methods, which return a new object with the respective data.
-
class
aiomixcloud.models.
AccessDict
(data, *, mixcloud)[source]¶ Bases:
aiomixcloud.models._WrapMixin
,collections.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.
-
_abc_impl
= <_abc_data object>¶
-
-
class
aiomixcloud.models.
AccessList
(data, *, mixcloud)[source]¶ Bases:
aiomixcloud.models._WrapMixin
,collections.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.-
_abc_impl
= <_abc_data object>¶
-
-
class
aiomixcloud.models.
Resource
(data, *, full=False, create_connections=True, mixcloud)[source]¶ Bases:
aiomixcloud.models.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). AResource
object has appropriately named methods for downloading information about its sub-entities (“connections”). It also mirrors “targeted” methods of itsMixcloud
instance, passing them its key as a first argument. Targeted methods include “actions” (e.gfollow()
orunfavorite()
), embed-related methods andedit()
.-
_abc_impl
= <_abc_data object>¶
-
_create_connections
()[source]¶ In case there is an item with a
['metadata']['connections']
key, create a method for each of its items (resource “connections”) that fetches information about sub-entities associated with the resource (eg comments, followers etc). Each of these methods is named after the respective connection.
-
_full
= None¶ Whether all of resource data has been downloaded (by having accessed the detail page).
-
-
class
aiomixcloud.models.
ResourceList
(data, *, mixcloud)[source]¶ Bases:
aiomixcloud.models.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 toself['data']
on failure, while iterating over and length concern “data” straight up.-
_abc_impl
= <_abc_data object>¶
Return an adjacent page of current resource list (another
ResourceList
object) specified by where, orNone
if it is not found.
-
-
class
aiomixcloud.models.
_WrapMixin
(data, *, mixcloud)[source]¶ Bases:
object
Enables returning the proper kind of object, when indexed and iterated over. Produces aiomixcloud models out of dictionaries and lists, leaving the rest of the types intact.
-
_wrap
(item)[source]¶ Wrap item with proper class. dict becomes
AccessDict
, orResource
-like if it has"type"
as a key. list becomesAccessList
. The rest remain unchanged.
-
mixcloud
= None¶ Mixcloud
instance to pass along to contained items
-
aiomixcloud.sync module¶
Synchronous operation mode¶
This module contains synchronous (i.e blocking) versions of the package classes. Specifically:
MixcloudOAuthSync
, synchronous version ofMixcloudOAuth
, handling OAuth authorization.MixcloudSync
, synchronous version ofMixcloud
, 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)[source]¶ Bases:
aiomixcloud.sync.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'¶
-
-
aiomixcloud.sync.
_MixcloudSync
¶ Synchronous version of
Mixcloud
without synchronous context management capabilities.alias of
aiomixcloud.sync.MixcloudSync