boxsdk.network package¶
Submodules¶
boxsdk.network.default_network module¶
-
class
boxsdk.network.default_network.
DefaultNetwork
[source]¶ 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 ofDefaultNetworkResponse
.
-
request
(method, url, access_token, **kwargs)[source]¶ 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.
-
-
class
boxsdk.network.default_network.
DefaultNetworkResponse
(request_response, access_token_used)[source]¶ 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 forDefaultNetwork
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.
-
log
(can_safely_log_content=False)[source]¶ 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
[source]¶ 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 ofNetworkResponse
.Return type: type or callable
-
request
(method, url, access_token, **kwargs)[source]¶ 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:
-
-
class
boxsdk.network.network_interface.
NetworkResponse
[source]¶ 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
-
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
-