From e94c321bf8f59638d7c4850db8663757b9de4564 Mon Sep 17 00:00:00 2001 From: Cathy Ouyang Date: Fri, 16 Sep 2022 15:11:28 -0700 Subject: [PATCH 1/2] docs: add clarifications to read timeout --- docs/storage/retry_timeout.rst | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/storage/retry_timeout.rst b/docs/storage/retry_timeout.rst index bc1912658..b2e8b6e02 100644 --- a/docs/storage/retry_timeout.rst +++ b/docs/storage/retry_timeout.rst @@ -12,22 +12,28 @@ Configuring Timeouts -------------------- For a number of reasons, methods which invoke API methods may take -longer than expected or desired. By default, such methods all time out -after a default interval, 60.0 seconds. Rather than blocking your application -code for that interval, you may choose to configure explicit timeouts -in your code, using one of three forms: +longer than expected or desired. By default, such methods are applied a +default timeout of 60.0 seconds. -- You can pass a single integer or float which functions as the timeout for the - entire request. E.g.: +The python-storage client uses the timeout mechanics of the underlying +``requests`` HTTP library. The connect timeout is the number of seconds +to establish a connection to the server. The read timeout is the number +of seconds the client will wait for the server to send a response. +In 99.9% of cases, this is the maximum wait time before the server sends +the first byte. + +Rather than blocking your application code for that interval,you may choose to +configure explicit timeouts in your code, using one of three forms: + +- You can specify a single value for the timeout. The timeout value will be + applied to both the connect and the read timeouts. E.g.: .. code-block:: python bucket = client.get_bucket(BUCKET_NAME, timeout=300.0) # five minutes -- You can also be passed as a two-tuple, ``(connect_timeout, read_timeout)``, - where the ``connect_timeout`` sets the maximum time required to establish - the connection to the server, and the ``read_timeout`` sets the maximum - time to wait for a completed response. E.g.: +- You can also pass a two-tuple, ``(connect_timeout, read_timeout)``, + if you would like to set the values separately. E.g.: .. code-block:: python From 4f1c0971c34b2d150bbd2dac6a4013cb2ccfee56 Mon Sep 17 00:00:00 2001 From: Cathy Ouyang Date: Tue, 27 Dec 2022 13:23:52 -0800 Subject: [PATCH 2/2] update wording per comments --- docs/storage/retry_timeout.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/storage/retry_timeout.rst b/docs/storage/retry_timeout.rst index b2e8b6e02..c9911a3f2 100644 --- a/docs/storage/retry_timeout.rst +++ b/docs/storage/retry_timeout.rst @@ -19,11 +19,10 @@ The python-storage client uses the timeout mechanics of the underlying ``requests`` HTTP library. The connect timeout is the number of seconds to establish a connection to the server. The read timeout is the number of seconds the client will wait for the server to send a response. -In 99.9% of cases, this is the maximum wait time before the server sends -the first byte. +In most cases, this is the maximum wait time before the server sends +the first byte. Please refer to the `requests documentation `_ for details. -Rather than blocking your application code for that interval,you may choose to -configure explicit timeouts in your code, using one of three forms: +You may also choose to configure explicit timeouts in your code, using one of three forms: - You can specify a single value for the timeout. The timeout value will be applied to both the connect and the read timeouts. E.g.: