Make a clear distinction between the transport timeout and the total method time timeout

[plamut]

It turned out that the concern from #406 was valid, unfortunately:

A downstream library that is timeout-sensitive might still be affected by the change, because the new explicit timeout parameter changes the semantics of AuthorizedSession.request() . The timeout represents the total allowed time for all requests made behind the scenes (e.g. credentials refresh attempts), as opposed to a previous per-request timeout.

The changed semantics of timeout caused an issue in the storage library. A user reported that if a large file upload takes, say, minutes and succeeds, a Timeout error is still raised, because the total execution time takes more than ~60 seconds, which the default transport timeout configured here in this library here.

Proposed solution

Leave the timeout parameter as is and still pass it to the transport, but introduce and expose a new optional parameter max_allowed_time that can be used instead to configure the "total timeout".

NOTE: The method itself might still take longer than max_allowed_time, because the underlying request might take longer, which is the nature of the requests library's timeout (docs).

Alternatives

Modifying the library code so that it supports "absolute total timeouts", but that would require interrupting requests in-flight, which does not seem to be a straightforward task -https://stackoverflow.com/q/21965484/5040035