From b9f630f91f349982f7ea56e9cd09772b669c90f3 Mon Sep 17 00:00:00 2001 From: Jeff Smick Date: Fri, 4 Aug 2023 13:29:03 -0700 Subject: [PATCH 1/2] add documentation for timeouts --- README.rst | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/README.rst b/README.rst index 3230de0d..d0f07918 100644 --- a/README.rst +++ b/README.rst @@ -120,6 +120,127 @@ When building queries, adapt your classes into dicts or lists prior to using the def from_result(obj): return MyClass(obj['my_prop']) +Client Configuration +-------------------- + +Timeouts +-------- + +There are a few different timeout settings that can be configured; each comes with a default setting. We recommend that most applications simply stick to the defaults. + +Query Timeout +------------- + +The query timeout is the time, as datetime.timedelta, that Fauna will spend executing your query before aborting with a 503 Timeout error. If a query timeout occurs, the driver will throw an instance of `ServiceTimeoutError`. + +The query timeout can be set using the ``query_timeout`` option. The default value if you do not provide one is ``DefaultClientBufferTimeout`` (5 seconds). + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client + + client = Client(query_timeout=timedelta(seconds=20)) + +The query timeout can also be set to a different value for each query using the ``QueryOptions.query_timeout`` option. Doing so overrides the client configuration when performing this query. + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client, QueryOptions + + response = client.query(myQuery, QueryOptions(query_timeout=timedelta(seconds=20))) + +Client Timeout +-------------- + +The client timeout is the time, as datetime.timedelta, that the client will wait for a network response before canceling the request. If a client timeout occurs, the driver will throw an instance of ``NetworkError``. + +The client timeout is always the query timeout plus an additional buffer. This ensures that the client always waits for at least as long Fauna could work on your query and account for network latency. + +The client timeout buffer is configured by setting the ``client_buffer_timeout`` option. The default value for the buffer if you do not provide on is ``DefaultClientBufferTimeout`` (5 seconds), therefore the default client timeout is 10 seconds when considering the default query timeout. + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client + + client = Client(client_buffer_timeout=timedelta(seconds=20)) + + +Idle Timeout +------------ + +The idle timeout is the time, as datetime.timedelta, that a session will remain open after there is no more pending communication. Once the session idle time has elapsed the session is considered idle and the session is closed. Subsequent requests will create a new session; the session idle timeout does not result in an error. + +Configure the idle timeout using the ``http_idle_timeout`` option. The default value if you do not provide one is ``DefaultIdleConnectionTimeout`` (5 seconds). + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client + + client = Client(http_idle_timeout=timedelta(seconds=6)) + +> **Note** +> Your application process may continue executing after all requests are completed for the duration of the session idle timeout. To prevent this, it is recommended to call ``Client.close()`` once all requests are complete. It is not recommended to set ``http_idle_timeout`` to small values. + +Connect Timeout +--------------- + +The connect timeout is the maximum amount of time, as datetime.timedelta, to wait until a connection to Fauna is established. If the client is unable to connect within this time frame, a ``ConnectTimeout`` exception is raised. + +Configure the connect timeout using the ``http_connect_timeout`` option. The default value if you do not provide one is ``DefaultHttpConnectTimeout`` (5 seconds). + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client + + client = Client(http_connect_timeout=timedelta(seconds=6)) + +Pool Timeout +------------ + +The pool timeout specifies the maximum amount of time, in datetime.timedelta, to wait for acquiring a connection from the connection pool. If the client is unable to acquire a connection within this time frame, a ``PoolTimeout`` exception is raised. This timeout may fire if 20 connections are currently in use and one isn't released before the timeout is up. + +Configure the pool timeout using the ``http_pool_timeout`` option. The default value if you do not provide one is ``DefaultHttpPoolTimeout`` (5 seconds). + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client + + client = Client(http_pool_timeout=timedelta(seconds=6)) + +Read Timeout +------------ + +The read timeout specifies the maximum amount of time, in datetime.timedelta, to wait for a chunk of data to be received (for example, a chunk of the response body). If the client is unable to receive data within this time frame, a ``ReadTimeout`` exception is raised. + +Configure the read timeout using the ``http_read_timeout`` option. The default value if you do not provide one is ``DefaultHttpReadTimeout`` (None). + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client + + client = Client(http_read_timeout=timedelta(seconds=6)) + +Write Timeout +------------ + +The write timeout specifies the maximum amount of time, in datetime.timedelta, to wait for a chunk of data to be sent (for example, a chunk of the request body). If the client is unable to send data within this time frame, a ``WriteTimeout`` exception is raised. + +Configure the write timeout using the ``http_write_timeout`` option. The default value if you do not provide one is ``DefaultHttpWriteTimeout`` (5 seconds). + +.. code-block:: python + + from datetime import timedelta + from fauna.client import Client + + client = Client(http_write_timeout=timedelta(seconds=6)) + Query Stats ----------- From b0642271fd8d6a8327b07465db51f3e2230e355a Mon Sep 17 00:00:00 2001 From: Jeff Smick Date: Wed, 9 Aug 2023 08:36:29 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Darren Cunningham --- README.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index d0f07918..1a57924b 100644 --- a/README.rst +++ b/README.rst @@ -126,12 +126,12 @@ Client Configuration Timeouts -------- -There are a few different timeout settings that can be configured; each comes with a default setting. We recommend that most applications simply stick to the defaults. +There are a few different timeout settings that can be configured; each comes with a default setting. We recommend that most applications use the defaults. Query Timeout ------------- -The query timeout is the time, as datetime.timedelta, that Fauna will spend executing your query before aborting with a 503 Timeout error. If a query timeout occurs, the driver will throw an instance of `ServiceTimeoutError`. +The query timeout is the time, as ``datetime.timedelta``, that Fauna will spend executing your query before aborting with a ``QueryTimeoutError``. The query timeout can be set using the ``query_timeout`` option. The default value if you do not provide one is ``DefaultClientBufferTimeout`` (5 seconds). @@ -154,7 +154,7 @@ The query timeout can also be set to a different value for each query using the Client Timeout -------------- -The client timeout is the time, as datetime.timedelta, that the client will wait for a network response before canceling the request. If a client timeout occurs, the driver will throw an instance of ``NetworkError``. +The client timeout is the time, as ``datetime.timedelta``, that the client will wait for a network response before canceling the request. If a client timeout occurs, the driver will throw an instance of ``NetworkError``. The client timeout is always the query timeout plus an additional buffer. This ensures that the client always waits for at least as long Fauna could work on your query and account for network latency. @@ -171,7 +171,7 @@ The client timeout buffer is configured by setting the ``client_buffer_timeout`` Idle Timeout ------------ -The idle timeout is the time, as datetime.timedelta, that a session will remain open after there is no more pending communication. Once the session idle time has elapsed the session is considered idle and the session is closed. Subsequent requests will create a new session; the session idle timeout does not result in an error. +The idle timeout is the time, as ``datetime.timedelta``, that a session will remain open after there is no more pending communication. Once the session idle time has elapsed the session is considered idle and the session is closed. Subsequent requests will create a new session; the session idle timeout does not result in an error. Configure the idle timeout using the ``http_idle_timeout`` option. The default value if you do not provide one is ``DefaultIdleConnectionTimeout`` (5 seconds). @@ -188,7 +188,7 @@ Configure the idle timeout using the ``http_idle_timeout`` option. The default v Connect Timeout --------------- -The connect timeout is the maximum amount of time, as datetime.timedelta, to wait until a connection to Fauna is established. If the client is unable to connect within this time frame, a ``ConnectTimeout`` exception is raised. +The connect timeout is the maximum amount of time, as ``datetime.timedelta``, to wait until a connection to Fauna is established. If the client is unable to connect within this time frame, a ``ConnectTimeout`` exception is raised. Configure the connect timeout using the ``http_connect_timeout`` option. The default value if you do not provide one is ``DefaultHttpConnectTimeout`` (5 seconds). @@ -202,7 +202,7 @@ Configure the connect timeout using the ``http_connect_timeout`` option. The def Pool Timeout ------------ -The pool timeout specifies the maximum amount of time, in datetime.timedelta, to wait for acquiring a connection from the connection pool. If the client is unable to acquire a connection within this time frame, a ``PoolTimeout`` exception is raised. This timeout may fire if 20 connections are currently in use and one isn't released before the timeout is up. +The pool timeout specifies the maximum amount of time, as ``datetime.timedelta``, to wait for acquiring a connection from the connection pool. If the client is unable to acquire a connection within this time frame, a ``PoolTimeout`` exception is raised. This timeout may fire if 20 connections are currently in use and one isn't released before the timeout is up. Configure the pool timeout using the ``http_pool_timeout`` option. The default value if you do not provide one is ``DefaultHttpPoolTimeout`` (5 seconds). @@ -216,7 +216,7 @@ Configure the pool timeout using the ``http_pool_timeout`` option. The default v Read Timeout ------------ -The read timeout specifies the maximum amount of time, in datetime.timedelta, to wait for a chunk of data to be received (for example, a chunk of the response body). If the client is unable to receive data within this time frame, a ``ReadTimeout`` exception is raised. +The read timeout specifies the maximum amount of time, as ``datetime.timedelta``, to wait for a chunk of data to be received (for example, a chunk of the response body). If the client is unable to receive data within this time frame, a ``ReadTimeout`` exception is raised. Configure the read timeout using the ``http_read_timeout`` option. The default value if you do not provide one is ``DefaultHttpReadTimeout`` (None). @@ -230,7 +230,7 @@ Configure the read timeout using the ``http_read_timeout`` option. The default v Write Timeout ------------ -The write timeout specifies the maximum amount of time, in datetime.timedelta, to wait for a chunk of data to be sent (for example, a chunk of the request body). If the client is unable to send data within this time frame, a ``WriteTimeout`` exception is raised. +The write timeout specifies the maximum amount of time, as ``datetime.timedelta``, to wait for a chunk of data to be sent (for example, a chunk of the request body). If the client is unable to send data within this time frame, a ``WriteTimeout`` exception is raised. Configure the write timeout using the ``http_write_timeout`` option. The default value if you do not provide one is ``DefaultHttpWriteTimeout`` (5 seconds).