Merge pull request #539 from pyinat/timeout

Increase default timeout to 20 seconds

HISTORY.md

@@ -3,6 +3,7 @@
 ## Unreleased
 * ⚠️ Drop support for python 3.7
 * Fix `KeyError` when using `create_observation()` in dry-run mode
+* Increase default request timeout from 10 to 20 seconds
 
 ## 0.19.0 (2023-12-12)
 

docs/user_guide/advanced.md

@@ -186,8 +186,12 @@ Credentials storage with keyring + KeePassXC
 
 ## Sessions
 If you want more control over how requests are sent, you can provide your own {py:class}`.ClientSession`
-object using the `session` argument for any API request function.
-See Caching and Rate-Limiting sections below for examples.
+object using the `session` argument for any API request function:
+```python
+>>> from pyinaturalist import ClientSession
+>>> session = ClientSession(...)
+>>> request_function(..., session=session)
+```
 
 ## Caching
 All API requests are cached by default. These expire in 30 minutes for most endpoints, and
@@ -220,6 +224,22 @@ from pyinaturalist import clear_cache
 clear_cache()
 ```
 
+## Timeouts
+If you are seeing frequent timeouts (`TimeoutError`) due to iNat server problems or a slow internet
+connection, you can increase the timeout (default: 20 seconds):
+```python
+>>> from pyinaturalist import ClientSession
+>>> session = ClientSession(timeout=40)
+```
+
+## Retries
+Similarly, if you are seeing intermittent non-timeout errors due to server issues, you can adjust
+the number of times to retry failed requests (default: 5):
+```python
+>>> from pyinaturalist import ClientSession
+>>> session = ClientSession(retries=7)
+```
+
 ## Rate Limiting
 Rate limiting is applied to all requests so they stay within the rates specified by iNaturalist's
 [API Recommended Practices](https://www.inaturalist.org/pages/api+recommended+practices).

docs/user_guide/client.md

@@ -88,12 +88,12 @@ For example, a common use case for this is to add `locale` and `preferred_place_
 
 These parameters will then be automatically used for any endpoints that accept them.
 
-## Caching, Rate-limiting, and Retries
+## Caching, Rate-limiting, Timeouts, and Retries
 See :py:class:`.ClientSession` and :ref:`advanced` for details on these settings.
 
-``iNatClient`` will accept any arguments for ``ClientSession``, for example:
+`iNatClient` will accept any arguments for `ClientSession`, for example:
 ```py
->>> client = iNatClient(per_second=50, expire_after=3600, retries=3)
+>>> client = iNatClient(per_second=50, expire_after=3600, timeout=30, retries=3)
 ```
 
 Or you can provide your own session object:

pyinaturalist/constants.py

@@ -33,7 +33,7 @@
 REQUESTS_PER_SECOND = 1
 REQUESTS_PER_MINUTE = 60
 REQUESTS_PER_DAY = 10000
-REQUEST_TIMEOUT = 10
+REQUEST_TIMEOUT = 20
 REQUEST_RETRIES = 5  # Maximum number of retries for a failed request
 RETRY_BACKOFF = 0.5  # Exponential backoff factor for retries
 RETRY_STATUSES = (500, 502, 503, 504)

test/test_session.py

@@ -8,7 +8,7 @@
 from requests_ratelimiter import Limiter, RequestRate
 from urllib3.exceptions import MaxRetryError
 
-from pyinaturalist.constants import CACHE_EXPIRATION
+from pyinaturalist.constants import CACHE_EXPIRATION, REQUEST_TIMEOUT
 from pyinaturalist.session import (
     CACHE_FILE,
     ClientSession,
@@ -202,7 +202,7 @@ def test_session__send(mock_limiter, mock_requests_send):
     session = ClientSession()
     request = Request(method='GET', url='http://test.com').prepare()
     session.send(request)
-    mock_requests_send.assert_called_with(request, timeout=(5, 10))
+    mock_requests_send.assert_called_with(request, timeout=(5, REQUEST_TIMEOUT))
 
 
 @pytest.mark.enable_client_session  # For all other tests, caching is disabled. Re-enable that here.