SDK assumes requests library is being used

[jmoldow]

We introduced the network_interface ABCs because we wanted to allow users to use any network layer that they pleased. We created the DefaultNetwork, backed by the requests library, so that the average user would have an out-of-the-box implementation that worked, but allowed advanced users to pass a custom Network implementation to OAuth2 and BoxSession, in case they wanted to use a different http library or otherwise customize the behavior of the network layer.

But right now it is not possible to use anything other than requests, because the Network ABC is not well specified enough:

@add_metaclass(ABCMeta)
class Network(object):
    @abstractmethod
    def request(self, method, url, access_token, **kwargs):  raise NotImplementedError

    ...

Because we don't have a complete method signature here, it isn't possible to know what to implement. Furthermore, kwargs actually ends up being keyword-arguments to requests.Session.request(), since that is how we use it throughout the SDK. request kwargs that we use include:

• params
• data
• files
• headers
• timeout
• expect_json_response
• stream

Relatedly, NetworkResponse.response_as_stream() says that it is supposed to return a "stream" (which I interpret to mean file, or io.IOBase, or some other file-like object). But DefaultNetworkResponse.response_as_stream() returns a urllib3.HTTPResponse, and File.download_to() uses its stream() method, which is not part of the interface of file or io.IOBase, but instead is specific to the urllib3.HTTPResponse interface.

We should discuss this, and I propose that we do one of the following two things:

1. Nail down these holes/inconsistencies so that the interface is 100% well-defined.
2. Throw away the ability to implement the interface your own way, make the SDK require requests, get rid of the network_interface ABCs, and rename default_network to network.
3. Keep the ability to specify the network_layer, but make all custom implementations subclass the concrete requests-based class DefaultNetwork (which would just be called Network).

A benefit of (1) is that we retain the ability to customize the network layer. A downside is that we hinder the ability of the SDK to make use of additional request arguments. If we ever want to use more arguments, or change the semantics of an argument (e.g. if we wanted to use the tuple form of timeout), we wouldn't be able to without making a breaking change, which is bad for us and our users.

A negative of (2) is that it is a breaking change. On the other hand, this issue shows that it is impossible (or at least impractical) currently to use a different implementation, so it would probably affect 0 users. A benefit is that it would allow us to do more with the requests library.

[stale]

This issue has been automatically marked as stale because it has not been updated in the last 30 days. It will be closed if no further activity occurs within the next 7 days. Feel free to reach out or mention Box SDK team member for further help and resources if they are needed.

[stale]

This issue has been automatically closed due to maximum period of being stale. Thank you for your contribution to Box Python SDK and feel free to open another PR/issue at any time.