Handle Retry-After header on 429/503 responses

Relevant standards: RFC 6585 / RFC 9110

Merges and fixes https://github.com/python-tcaldav/caldav/pull/628 by temsocial

New `DAVClient` parameters:
- `rate_limit_handle` (bool, default False): when True, automatically sleep
  and retry on rate-limited responses; when False raise `RateLimitError`
  immediately so callers can implement their own strategy.
- `rate_limit_default_sleep` (Optional[int], default None): fallback sleep
  in seconds when the server's 429 omits a Retry-After header. None means
  raise rather than guess a sleep duration.
- `rate_limit_max_sleep` (Optional[int], default None): cap on the sleep
  duration; None means respect the server's value without limit.

New `error.RateLimitError(DAVError)` with `retry_after` (raw header string)
and `retry_after_seconds` (parsed float) attributes.

11 unit tests added to `TestRateLimiting` in `tests/test_caldav_unit.py`.

Co-authored-by: temsocial <temsocial@users.noreply.github.com>
Assisted-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tobixen

CHANGELOG.md

@@ -98,6 +98,24 @@ Additionally, direct `DAVClient()` instantiation should migrate to `get_davclien
   searcher.add_filter(...)
   results = searcher.search()
   ```
+* **`get_calendars()` and `get_calendar()` context managers** -- Module-level factory functions that create a client, fetch calendars, and clean up on exit:
+  ```python
+  with get_calendars(url="...", username="...", password="...") as calendars:
+      for cal in calendars:
+          ...
+  ```
+* **Base+override feature profiles** -- YAML config now supports inheriting from base feature profiles:
+  ```yaml
+  my-server:
+      features:
+          base: nextcloud
+          search.comp-type: unsupported
+  ```
+* **Feature validation** -- `caldav.config` now validates feature configuration and raises errors on unknown feature names
+* **URL space validation** -- `caldav.lib.url` now validates that URLs don't contain unquoted spaces
+* **Fallback for missing calendar-home-set** -- Client falls back to principal URL when `calendar-home-set` property is not available
+* **Load fallback for changed URLs** -- `CalendarObjectResource.load()` falls back to UID-based lookup when servers change URLs after save
+* **Retry-After / rate-limit handling** (RFC 6585 / RFC 9110) -- `DAVClient` now exposes `rate_limit_handle`, `rate_limit_default_sleep`, and `rate_limit_max_sleep` parameters. When `rate_limit_handle=True` the client automatically sleeps and retries on 429 Too Many Requests and 503 Service Unavailable responses that carry a `Retry-After` header. When `rate_limit_handle=False` (default) a `RateLimitError` is raised immediately so callers can implement their own back-off strategy. https://github.com/python-caldav/caldav/issues/627
 
 ### Fixed
 

caldav/davclient.py

@@ -10,7 +10,10 @@
 
 import logging
 import sys
+import time
 import warnings
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
 from types import TracebackType
 from typing import TYPE_CHECKING, Any, Optional
 from urllib.parse import unquote
@@ -206,6 +209,9 @@ def __init__(
         features: FeatureSet | dict | str = None,
         enable_rfc6764: bool = True,
         require_tls: bool = True,
+        rate_limit_handle: bool = False,
+        rate_limit_default_sleep: Optional[int] = None,
+        rate_limit_max_sleep: Optional[int] = None,
     ) -> None:
         """
         Sets up a HTTPConnection object towards the server in the url.
@@ -243,6 +249,16 @@ def __init__(
                        redirect to unencrypted HTTP. Set to False ONLY if you need to
                        support non-TLS servers and trust your DNS infrastructure.
                        This parameter has no effect if enable_rfc6764=False.
+          rate_limit_handle: boolean, whether to automatically sleep and retry when the server
+                             responds with 429 Too Many Requests or 503 Service Unavailable.
+                             Default: False (raise RateLimitError immediately).
+          rate_limit_default_sleep: int or None, fallback sleep duration in seconds when the
+                                    server's 429 response does not include a parseable Retry-After
+                                    header. None (default) means raise RateLimitError rather than
+                                    sleeping when no Retry-After is provided.
+          rate_limit_max_sleep: int or None, maximum number of seconds to sleep when rate limited,
+                                regardless of the server's Retry-After value. None (default) means
+                                there is no cap and the server-requested delay is respected as-is.
 
         The niquests library will honor a .netrc-file, if such a file exists
         username and password may be omitted.
@@ -341,6 +357,10 @@ def __init__(
 
         self._principal = None
 
+        self.rate_limit_handle = rate_limit_handle
+        self.rate_limit_default_sleep = rate_limit_default_sleep
+        self.rate_limit_max_sleep = rate_limit_max_sleep
+
     def __enter__(self) -> Self:
         ## Used for tests, to set up a temporarily test server
         if hasattr(self, "setup"):
@@ -931,7 +951,24 @@ def request(
         Returns:
             DAVResponse
         """
-        return self._sync_request(url, method, body, headers)
+        try:
+            return self._sync_request(url, method, body, headers)
+        except error.RateLimitError as e:
+            if not self.rate_limit_handle:
+                raise
+            retry_after_seconds = (
+                e.retry_after_seconds
+                if e.retry_after_seconds is not None
+                else self.rate_limit_default_sleep
+            )
+            if retry_after_seconds is None or retry_after_seconds <= 0:
+                raise
+            if self.rate_limit_max_sleep is not None:
+                retry_after_seconds = min(retry_after_seconds, self.rate_limit_max_sleep)
+            if retry_after_seconds <= 0:
+                raise
+            time.sleep(retry_after_seconds)
+            return self._sync_request(url, method, body, headers)
 
     def _sync_request(
         self,
@@ -974,8 +1011,31 @@ def _sync_request(
             cert=self.ssl_cert,
         )
 
-        # Handle 401 responses for auth negotiation
         r_headers = CaseInsensitiveDict(r.headers)
+
+        # Handle 429/503 responses: raise RateLimitError so the caller can decide whether to retry
+        if r.status_code in (429, 503):
+            retry_after_header: Optional[str] = r_headers.get("Retry-After")
+            retry_seconds: Optional[float] = None
+            if retry_after_header:
+                try:
+                    retry_seconds = int(retry_after_header)
+                except ValueError:
+                    try:
+                        retry_date = parsedate_to_datetime(retry_after_header)
+                        now = datetime.now(timezone.utc)
+                        retry_seconds = max(0.0, (retry_date - now).total_seconds())
+                    except (ValueError, TypeError):
+                        pass
+            if r.status_code == 429 or retry_after_header is not None:
+                raise error.RateLimitError(
+                    url=str(url_obj),
+                    reason=f"Rate limited or service unavailable. Retry after: {retry_after_header}",
+                    retry_after=retry_after_header,
+                    retry_after_seconds=retry_seconds,
+                )
+
+        # Handle 401 responses for auth negotiation
         if (
             r.status_code == 401
             and "WWW-Authenticate" in r_headers

caldav/lib/error.py

@@ -133,6 +133,22 @@ class ResponseError(DAVError):
     pass
 
 
+class RateLimitError(DAVError):
+    """Raised when the server responds with 429 Too Many Requests or
+    503 Service Unavailable with a Retry-After header."""
+
+    def __init__(
+        self,
+        url: str | None = None,
+        reason: str | None = None,
+        retry_after: str | None = None,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(url=url, reason=reason)
+        self.retry_after = retry_after
+        self.retry_after_seconds = retry_after_seconds
+
+
 exception_by_method: dict[str, DAVError] = defaultdict(lambda: DAVError)
 for method in (
     "delete",