boxsdk.network package

Submodules

boxsdk.network.default_network module

class boxsdk.network.default_network.DefaultNetwork

Bases: boxsdk.network.network_interface.Network

Implementats the network interface using the requests library.

EXCEPTION_FORMAT = u'\x1b[31mRequest "%(method)s %(url)s" failed with %(exc_type_name)s exception: %(exc_value)r\x1b[0m'

LOGGER_NAME = u'boxsdk.network'

REQUEST_FORMAT = u'\x1b[36m%(method)s %(url)s %(request_kwargs)s\x1b[0m'

network_response_constructor

Baseclass override.

A callable that accepts request_response and access_token_used keyword arguments for the DefaultNetworkResponse constructor, and returns an instance of DefaultNetworkResponse.

request(method, url, access_token, **kwargs)

Base class override.

Make a network request using a requests.Session. Logs information about an API request and response.

Also logs exceptions before re-raising them.

The logging of the response is deferred to DefaultNetworkResponse. See that class’s docstring for more info.

retry_after(delay, request_method, *args, **kwargs)

Base class override. Retry after sleeping for delay seconds.

class boxsdk.network.default_network.DefaultNetworkResponse(request_response, access_token_used)

Bases: boxsdk.network.network_interface.NetworkResponse

Implementation of the network interface using the requests library.

requests.Response has a few mutually-exclusive ways to read the content of the response:

• With the Response.raw attribute, an io.IOBase instance returned from the urllib3 library, that can be read once in chunks from beginning to end.
• With Response.iter_content() and other iter_* generators, which also can only be read once and advance the Response.raw IO stream.
• With the Response.content property (and other attributes such as Response.text and Response.json()), which reads and caches the remaining response content in memory. Can be accessed multiple times, but cannot be safely accessed if any of the previous mechanisms have been used at all. And if this property has already been accessed, then the other mechanisms will have been exhausted, and attempting to read from them will make it appear like the response content is empty.

Any of these mechanisms may be used to read any response, regardless of whether stream=True or stream=False on the request.

If the caller uses Response.content, then it is safe for DefaultNetwork to also access it. But if the caller uses any of the streaming mechanisms, then it is not safe for DefaultNetwork to ever read any of the content. Thus, the options available are:

• Never log the content of a response.
• Make logging part of the Network interface, and add an optional keyword argument that callers can use to specify when it is unsafe to log the content of a response.
• Defer logging until it is possible to auto-detect which mechanism is being used.

This class implements the latter option. Instead of response logging taking place in DefaultNetwork.request(), it takes place in this DefaultNetworkResponse class, as soon as the caller starts reading the content. If content or json() are accessed, then the response will be logged with its content. Whereas if response_as_stream or request_response are accessed, then the response will be logged with a placeholder for the actual content.

Because most SDK methods immediately read the content on success, but not on errors (the SDK may retry the request based on just the status code), this class will log its content if it represents a failed request.

ERROR_RESPONSE_FORMAT = u'\x1b[31m"%(method)s %(url)s" %(status_code)s %(content_length)s\n%(headers)s\n%(content)s\n\x1b[0m'

STREAM_CONTENT_NOT_LOGGED = u'<File download contents unavailable for logging>'

SUCCESSFUL_RESPONSE_FORMAT = u'\x1b[32m"%(method)s %(url)s" %(status_code)s %(content_length)s\n%(headers)s\n%(content)s\n\x1b[0m'

access_token_used

Base class override.

content

Base class override.

headers

Base class override.

json()

Base class override.

log(can_safely_log_content=False)

Logs information about the Box API response.

Will only execute once. Subsequent calls will be no-ops. This is partially because we only want to log responses once, and partially because this is necessary to prevent this method from infinite recursing with its use of the content property.

Parameters:can_safely_log_content (bool) –

(optional) True if the caller is accessing the content property, False otherwise.

As stated in the class docstring, it is unsafe for this logging method to access content unless the caller is also accessing it.

Defaults to False.

ok

Base class override.

request_response

The response returned from the Requests library.

Return type:Response

response_as_stream

Base class override.

status_code

Base class override.

boxsdk.network.network_interface module

class boxsdk.network.network_interface.Network

Bases: object

Abstract base class specifying the interface of the network layer.

network_response_constructor

The constructor to use for creating NetworkResponse instances.

This is not implemented by default, and is not a required part of the interface.

It is recommended that implementations of request() call this to construct their responses, rather than hard-coding the construction. That way, subclasses of the implementation can easily extend the construction of NetworkResponse instances, by overriding this property, instead of needing to override request().

Returns:A callable that returns an instance of NetworkResponse. Most commonly, this will be a subclass of NetworkResponse. Return type:type or callable

request(method, url, access_token, **kwargs)

Make a network request to the given url with the given method.

Parameters:

• method (unicode) – The HTTP verb that should be used to make the request.
• url (unicode) – The URL for the request.
• access_token (unicode) – The OAuth2 access token used to authorize the request.

Return type:

NetworkResponse

retry_after(delay, request_method, *args, **kwargs)

Make a network request after a given delay.

Parameters:

• delay (float) – How long until the request should be executed.
• request_method (callable) – A callable that will execute the request.

Return type:

NetworkResponse

class boxsdk.network.network_interface.NetworkResponse

Bases: object

Abstract base class specifying the interface for a network response.

access_token_used

Return the access token used to make the request.

Return type:unicode

content

Return the content of the response body.

Return type:varies

headers

Return the response headers.

Return type:dict

json()

Return the parsed JSON response.

Return type:dict or list or str or int or float

ok

Return whether or not the request was successful.

Return type:bool

response_as_stream

Return a stream containing the raw network response.

Return type:stream

status_code

Return the HTTP status code of the response.

Return type:int

Module contents