diff --git a/HISTORY.md b/HISTORY.md index 85776264..64984e36 100644 --- a/HISTORY.md +++ b/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) diff --git a/docs/user_guide/advanced.md b/docs/user_guide/advanced.md index b0fc1db3..d86d7bb6 100644 --- a/docs/user_guide/advanced.md +++ b/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). diff --git a/docs/user_guide/client.md b/docs/user_guide/client.md index 8fbb46e0..633a0601 100644 --- a/docs/user_guide/client.md +++ b/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: diff --git a/pyinaturalist/constants.py b/pyinaturalist/constants.py index 92e2976f..3853d1b4 100644 --- a/pyinaturalist/constants.py +++ b/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) diff --git a/test/test_session.py b/test/test_session.py index 30ef1cce..274d1979 100644 --- a/test/test_session.py +++ b/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.