Package scapi :: Class Scope
[hide private]
[frames] | no frames]

Class Scope

source code

object --+
         |
        Scope

The basic means to query and create resources. The Scope uses the ApiConnector to create the proper URIs for querying or creating resources.

For accessing resources from the root level, you explcitly create a Scope and pass it an ApiConnector-instance. Then you can query it or create new resources like this:

>>> connector = scapi.ApiConnector(host='host', user='user', password='password') # initialize the API
>>> scope = scapi.Scope(connector) # get the root scope
>>> users = list(scope.users())
[<scapi.User object at 0x12345>, ...]

Please not that all resources that are lists are returned as generator. So you need to either iterate over them, or call list(resources) on them.

When accessing resources that belong to another resource, like contacts of a user, you access the parent's resource scope implicitly through the resource instance like this:

>>> user = scope.users().next()
>>> list(user.contacts())
[<scapi.Contact object at 0x12345>, ...]
Instance Methods [hide private]
 
__init__(self, connector, scope=None, parent=None)
Create the Scope.
source code
 
_get_connector(self) source code
 
oauth_sign_get_request(self, url)
This method will take an arbitrary url, and rewrite it so that the current authenticator's oauth-headers are appended as query-parameters.
source code
urllib2.Request
_create_request(self, url, connector, parameters, queryparams, alternate_http_method=None, use_multipart=False)
This method returnes the urllib2.Request to perform the actual HTTP-request.
source code
str
_create_query_string(self, queryparams)
Small helpermethod to create the querystring from a dict.
source code
 
_call(self, method, *args, **kwargs)
The workhorse.
source code
 
_map(self, res, method, continue_list_fetching)
This method will take the JSON-result of a HTTP-call and return our domain-objects.
source code
 
__getattr__(self, _name)
Retrieve an API-method or a scoped domain-class.
source code
 
__repr__(self)
repr(x)
source code
 
__str__(self)
str(x)
source code

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, connector, scope=None, parent=None)
(Constructor)

source code 

Create the Scope. It can have a resource as scope, and possibly a parent-scope.

Parameters:
  • connector (ApiConnector) - The connector to use.
  • scope (scapi.RESTBase) - the resource to make this scope belong to
  • parent (scapi.Scope) - the parent scope of this scope
Overrides: object.__init__

oauth_sign_get_request(self, url)

source code 

This method will take an arbitrary url, and rewrite it so that the current authenticator's oauth-headers are appended as query-parameters.

This is used in streaming and downloading, because those content isn't served from the SoundCloud servers themselves.

A usage example would look like this:

>>> sca = scapi.Scope(connector)
>>> track = sca.tracks(params={
      "filter" : "downloadable",
      }).next()
>>> download_url = track.download_url
>>> signed_url = track.oauth_sign_get_request(download_url)
>>> data = urllib2.urlopen(signed_url).read()

_create_request(self, url, connector, parameters, queryparams, alternate_http_method=None, use_multipart=False)

source code 

This method returnes the urllib2.Request to perform the actual HTTP-request.

We return a subclass that overload the get_method-method to return a custom method like "PUT". Additionally, the request is enhanced with the current authenticators authorization scheme headers.

Parameters:
  • url - the destination url
  • connector - our connector-instance
  • parameters (None|dict<str, basestring|list<basestring>>) - the POST-parameters to use.
  • queryparams (None|dict<str, basestring|list<basestring>>) - the queryparams to use
  • alternate_http_method (str) - an alternate HTTP-method to use
Returns: urllib2.Request
the fully equipped request

_create_query_string(self, queryparams)

source code 

Small helpermethod to create the querystring from a dict.

Parameters:
  • queryparams (None|dict<str, basestring|list<basestring>>) - the queryparameters.
Returns: str
either the empty string, or a "?" followed by the parameters joined by "&"

_call(self, method, *args, **kwargs)

source code 

The workhorse. It's complicated, convoluted and beyond understanding of a mortal being.

You have been warned.

_map(self, res, method, continue_list_fetching)

source code 

This method will take the JSON-result of a HTTP-call and return our domain-objects.

It's also deep magic, don't look.

__getattr__(self, _name)
(Qualification operator)

source code 

Retrieve an API-method or a scoped domain-class.

If the former, result is a callable that supports the following invocations:

  • calling (...), with possible arguments (positional/keyword), return the resulting resource or list of resources. When calling, you can pass a keyword-argument params. This must be a dict or MultiDict and will be used to add additional query-get-parameters.
  • invoking append(resource) on it will PUT the resource, making it part of the current resource. Makes sense only if it's a collection of course.
  • invoking remove(resource) on it will DELETE the resource from it's container. Also only usable on collections.

    TODO: describe the latter

__repr__(self)
(Representation operator)

source code 

repr(x)

Overrides: object.__repr__
(inherited documentation)

__str__(self)
(Informal representation operator)

source code 

str(x)

Overrides: object.__str__
(inherited documentation)