samsara-api 4.2.0__py3-none-any.whl → 4.3.0__py3-none-any.whl

samsara/core/__init__.py

@@ -8,6 +8,7 @@ from importlib import import_module
 if typing.TYPE_CHECKING:
     from .api_error import ApiError
     from .client_wrapper import AsyncClientWrapper, BaseClientWrapper, SyncClientWrapper
+    from .custom_pagination import AsyncCustomPager, SyncCustomPager
     from .datetime_utils import serialize_datetime
     from .file import File, convert_file_dict_to_httpx_tuples, with_content_type
     from .http_client import AsyncHttpClient, HttpClient
@@ -30,6 +31,7 @@ if typing.TYPE_CHECKING:
 _dynamic_imports: typing.Dict[str, str] = {
     "ApiError": ".api_error",
     "AsyncClientWrapper": ".client_wrapper",
+    "AsyncCustomPager": ".custom_pagination",
     "AsyncHttpClient": ".http_client",
     "AsyncHttpResponse": ".http_response",
     "AsyncPager": ".pagination",
@@ -41,6 +43,7 @@ _dynamic_imports: typing.Dict[str, str] = {
     "IS_PYDANTIC_V2": ".pydantic_utilities",
     "RequestOptions": ".request_options",
     "SyncClientWrapper": ".client_wrapper",
+    "SyncCustomPager": ".custom_pagination",
     "SyncPager": ".pagination",
     "UniversalBaseModel": ".pydantic_utilities",
     "UniversalRootModel": ".pydantic_utilities",
@@ -82,6 +85,7 @@ def __dir__():
 __all__ = [
     "ApiError",
     "AsyncClientWrapper",
+    "AsyncCustomPager",
     "AsyncHttpClient",
     "AsyncHttpResponse",
     "AsyncPager",
@@ -93,6 +97,7 @@ __all__ = [
     "IS_PYDANTIC_V2",
     "RequestOptions",
     "SyncClientWrapper",
+    "SyncCustomPager",
     "SyncPager",
     "UniversalBaseModel",
     "UniversalRootModel",

samsara/core/client_wrapper.py

@@ -10,7 +10,7 @@ class BaseClientWrapper:
     def __init__(
         self,
         *,
-        token: typing.Optional[typing.Union[str, typing.Callable[[], str]]] = None,
+        token: typing.Union[str, typing.Callable[[], str]],
         headers: typing.Optional[typing.Dict[str, str]] = None,
         base_url: str,
         timeout: typing.Optional[float] = None,
@@ -22,19 +22,17 @@ class BaseClientWrapper:
 
     def get_headers(self) -> typing.Dict[str, str]:
         headers: typing.Dict[str, str] = {
-            "User-Agent": "samsara-api/4.2.0",
+            "User-Agent": "samsara-api/4.3.0",
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "samsara-api",
-            "X-Fern-SDK-Version": "4.2.0",
+            "X-Fern-SDK-Version": "4.3.0",
             **(self.get_custom_headers() or {}),
         }
-        token = self._get_token()
-        if token is not None:
-            headers["Authorization"] = f"Bearer {token}"
+        headers["Authorization"] = f"Bearer {self._get_token()}"
         return headers
 
-    def _get_token(self) -> typing.Optional[str]:
-        if isinstance(self._token, str) or self._token is None:
+    def _get_token(self) -> str:
+        if isinstance(self._token, str):
             return self._token
         else:
             return self._token()
@@ -53,7 +51,7 @@ class SyncClientWrapper(BaseClientWrapper):
     def __init__(
         self,
         *,
-        token: typing.Optional[typing.Union[str, typing.Callable[[], str]]] = None,
+        token: typing.Union[str, typing.Callable[[], str]],
         headers: typing.Optional[typing.Dict[str, str]] = None,
         base_url: str,
         timeout: typing.Optional[float] = None,
@@ -72,16 +70,26 @@ class AsyncClientWrapper(BaseClientWrapper):
     def __init__(
         self,
         *,
-        token: typing.Optional[typing.Union[str, typing.Callable[[], str]]] = None,
+        token: typing.Union[str, typing.Callable[[], str]],
         headers: typing.Optional[typing.Dict[str, str]] = None,
         base_url: str,
         timeout: typing.Optional[float] = None,
+        async_token: typing.Optional[typing.Callable[[], typing.Awaitable[str]]] = None,
         httpx_client: httpx.AsyncClient,
     ):
         super().__init__(token=token, headers=headers, base_url=base_url, timeout=timeout)
+        self._async_token = async_token
         self.httpx_client = AsyncHttpClient(
             httpx_client=httpx_client,
             base_headers=self.get_headers,
             base_timeout=self.get_timeout,
             base_url=self.get_base_url,
+            async_base_headers=self.async_get_headers,
         )
+
+    async def async_get_headers(self) -> typing.Dict[str, str]:
+        headers = self.get_headers()
+        if self._async_token is not None:
+            token = await self._async_token()
+            headers["Authorization"] = f"Bearer {token}"
+        return headers

samsara/core/custom_pagination.py

@@ -0,0 +1,152 @@
+# This file was auto-generated by Fern from our API Definition.
+
+"""
+Custom Pagination Support
+
+This file is designed to be modified by SDK users to implement their own
+pagination logic. The generator will import SyncCustomPager and AsyncCustomPager
+from this module when custom pagination is used.
+
+Users should:
+1. Implement their custom pager (e.g., PayrocPager, MyCustomPager, etc.)
+2. Create adapter classes (SyncCustomPager/AsyncCustomPager) that bridge
+   between the generated SDK code and their custom pager implementation
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Generic, Iterator, TypeVar
+
+# Import the base utilities you'll need
+# Adjust these imports based on your actual structure
+try:
+    from .client_wrapper import AsyncClientWrapper, SyncClientWrapper
+except ImportError:
+    # Fallback for type hints
+    AsyncClientWrapper = Any  # type: ignore
+    SyncClientWrapper = Any  # type: ignore
+
+TItem = TypeVar("TItem")
+TResponse = TypeVar("TResponse")
+
+
+class SyncCustomPager(Generic[TItem, TResponse]):
+    """
+    Adapter for custom synchronous pagination.
+
+    The generator will call this with:
+        SyncCustomPager(initial_response=response, client_wrapper=client_wrapper)
+
+    Implement this class to extract pagination metadata from your response
+    and delegate to your custom pager implementation.
+
+    Example implementation:
+
+        class SyncCustomPager(Generic[TItem, TResponse]):
+            def __init__(
+                self,
+                *,
+                initial_response: TResponse,
+                client_wrapper: SyncClientWrapper,
+            ):
+                # Extract data and pagination metadata from response
+                data = initial_response.data  # Adjust based on your response structure
+                links = initial_response.links
+
+                # Initialize your custom pager
+                self._pager = MyCustomPager(
+                    current_page=Page(data),
+                    httpx_client=client_wrapper.httpx_client,
+                    get_headers=client_wrapper.get_headers,
+                    # ... other parameters
+                )
+
+            def __iter__(self):
+                return iter(self._pager)
+
+            # Delegate other methods to your pager...
+    """
+
+    def __init__(
+        self,
+        *,
+        initial_response: TResponse,
+        client_wrapper: SyncClientWrapper,
+    ):
+        """
+        Initialize the custom pager.
+
+        Args:
+            initial_response: The parsed API response from the first request
+            client_wrapper: The client wrapper providing HTTP client and utilities
+        """
+        raise NotImplementedError(
+            "SyncCustomPager must be implemented. "
+            "Please implement this class in core/custom_pagination.py to define your pagination logic. "
+            "See the class docstring for examples."
+        )
+
+    def __iter__(self) -> Iterator[TItem]:
+        """Iterate through all items across all pages."""
+        raise NotImplementedError("Must implement __iter__ method")
+
+
+class AsyncCustomPager(Generic[TItem, TResponse]):
+    """
+    Adapter for custom asynchronous pagination.
+
+    The generator will call this with:
+        AsyncCustomPager(initial_response=response, client_wrapper=client_wrapper)
+
+    Implement this class to extract pagination metadata from your response
+    and delegate to your custom async pager implementation.
+
+    Example implementation:
+
+        class AsyncCustomPager(Generic[TItem, TResponse]):
+            def __init__(
+                self,
+                *,
+                initial_response: TResponse,
+                client_wrapper: AsyncClientWrapper,
+            ):
+                # Extract data and pagination metadata from response
+                data = initial_response.data  # Adjust based on your response structure
+                links = initial_response.links
+
+                # Initialize your custom async pager
+                self._pager = MyAsyncCustomPager(
+                    current_page=Page(data),
+                    httpx_client=client_wrapper.httpx_client,
+                    get_headers=client_wrapper.get_headers,
+                    # ... other parameters
+                )
+
+            async def __aiter__(self):
+                return self._pager.__aiter__()
+
+            # Delegate other methods to your pager...
+    """
+
+    def __init__(
+        self,
+        *,
+        initial_response: TResponse,
+        client_wrapper: AsyncClientWrapper,
+    ):
+        """
+        Initialize the custom async pager.
+
+        Args:
+            initial_response: The parsed API response from the first request
+            client_wrapper: The client wrapper providing HTTP client and utilities
+        """
+        raise NotImplementedError(
+            "AsyncCustomPager must be implemented. "
+            "Please implement this class in core/custom_pagination.py to define your pagination logic. "
+            "See the class docstring for examples."
+        )
+
+    async def __aiter__(self) -> AsyncIterator[TItem]:
+        """Asynchronously iterate through all items across all pages."""
+        raise NotImplementedError("Must implement __aiter__ method")

samsara/core/http_client.py

@@ -14,13 +14,13 @@ from .file import File, convert_file_dict_to_httpx_tuples
 from .force_multipart import FORCE_MULTIPART
 from .jsonable_encoder import jsonable_encoder
 from .query_encoder import encode_query
-from .remove_none_from_dict import remove_none_from_dict
+from .remove_none_from_dict import remove_none_from_dict as remove_none_from_dict
 from .request_options import RequestOptions
 from httpx._types import RequestFiles
 
-INITIAL_RETRY_DELAY_SECONDS = 0.5
-MAX_RETRY_DELAY_SECONDS = 10
-MAX_RETRY_DELAY_SECONDS_FROM_HEADER = 30
+INITIAL_RETRY_DELAY_SECONDS = 1.0
+MAX_RETRY_DELAY_SECONDS = 60.0
+JITTER_FACTOR = 0.2  # 20% random jitter
 
 
 def _parse_retry_after(response_headers: httpx.Headers) -> typing.Optional[float]:
@@ -64,6 +64,38 @@ def _parse_retry_after(response_headers: httpx.Headers) -> typing.Optional[float
     return seconds
 
 
+def _add_positive_jitter(delay: float) -> float:
+    """Add positive jitter (0-20%) to prevent thundering herd."""
+    jitter_multiplier = 1 + random() * JITTER_FACTOR
+    return delay * jitter_multiplier
+
+
+def _add_symmetric_jitter(delay: float) -> float:
+    """Add symmetric jitter (±10%) for exponential backoff."""
+    jitter_multiplier = 1 + (random() - 0.5) * JITTER_FACTOR
+    return delay * jitter_multiplier
+
+
+def _parse_x_ratelimit_reset(response_headers: httpx.Headers) -> typing.Optional[float]:
+    """
+    Parse the X-RateLimit-Reset header (Unix timestamp in seconds).
+    Returns seconds to wait, or None if header is missing/invalid.
+    """
+    reset_time_str = response_headers.get("x-ratelimit-reset")
+    if reset_time_str is None:
+        return None
+
+    try:
+        reset_time = int(reset_time_str)
+        delay = reset_time - time.time()
+        if delay > 0:
+            return delay
+    except (ValueError, TypeError):
+        pass
+
+    return None
+
+
 def _retry_timeout(response: httpx.Response, retries: int) -> float:
     """
     Determine the amount of time to wait before retrying a request.
@@ -71,17 +103,19 @@ def _retry_timeout(response: httpx.Response, retries: int) -> float:
     with a jitter to determine the number of seconds to wait.
     """
 
-    # If the API asks us to wait a certain amount of time (and it's a reasonable amount), just do what it says.
+    # 1. Check Retry-After header first
     retry_after = _parse_retry_after(response.headers)
-    if retry_after is not None and retry_after <= MAX_RETRY_DELAY_SECONDS_FROM_HEADER:
-        return retry_after
+    if retry_after is not None and retry_after > 0:
+        return min(retry_after, MAX_RETRY_DELAY_SECONDS)
 
-    # Apply exponential backoff, capped at MAX_RETRY_DELAY_SECONDS.
-    retry_delay = min(INITIAL_RETRY_DELAY_SECONDS * pow(2.0, retries), MAX_RETRY_DELAY_SECONDS)
+    # 2. Check X-RateLimit-Reset header (with positive jitter)
+    ratelimit_reset = _parse_x_ratelimit_reset(response.headers)
+    if ratelimit_reset is not None:
+        return _add_positive_jitter(min(ratelimit_reset, MAX_RETRY_DELAY_SECONDS))
 
-    # Add a randomness / jitter to the retry delay to avoid overwhelming the server with retries.
-    timeout = retry_delay * (1 - 0.25 * random())
-    return timeout if timeout >= 0 else 0
+    # 3. Fall back to exponential backoff (with symmetric jitter)
+    backoff = min(INITIAL_RETRY_DELAY_SECONDS * pow(2.0, retries), MAX_RETRY_DELAY_SECONDS)
+    return _add_symmetric_jitter(backoff)
 
 
 def _should_retry(response: httpx.Response) -> bool:
@@ -89,6 +123,21 @@ def _should_retry(response: httpx.Response) -> bool:
     return response.status_code >= 500 or response.status_code in retryable_400s
 
 
+def _maybe_filter_none_from_multipart_data(
+    data: typing.Optional[typing.Any],
+    request_files: typing.Optional[RequestFiles],
+    force_multipart: typing.Optional[bool],
+) -> typing.Optional[typing.Any]:
+    """
+    Filter None values from data body for multipart/form requests.
+    This prevents httpx from converting None to empty strings in multipart encoding.
+    Only applies when files are present or force_multipart is True.
+    """
+    if data is not None and isinstance(data, typing.Mapping) and (request_files or force_multipart):
+        return remove_none_from_dict(data)
+    return data
+
+
 def remove_omit_from_dict(
     original: typing.Dict[str, typing.Optional[typing.Any]],
     omit: typing.Optional[typing.Any],
@@ -188,7 +237,7 @@ class HttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> httpx.Response:
@@ -210,6 +259,28 @@ class HttpClient:
         if (request_files is None or len(request_files) == 0) and force_multipart:
             request_files = FORCE_MULTIPART
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {}) or {}
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit,
+                    )
+                )
+            )
+        )
+
         response = self.httpx_client.request(
             method=method,
             url=urllib.parse.urljoin(f"{base_url}/", path),
@@ -222,23 +293,7 @@ class HttpClient:
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {}) or {}
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,
@@ -246,9 +301,9 @@ class HttpClient:
             timeout=timeout,
         )
 
-        max_retries: int = request_options.get("max_retries", 0) if request_options is not None else 0
+        max_retries: int = request_options.get("max_retries", 2) if request_options is not None else 2
         if _should_retry(response=response):
-            if max_retries > retries:
+            if retries < max_retries:
                 time.sleep(_retry_timeout(response=response, retries=retries))
                 return self.request(
                     path=path,
@@ -285,7 +340,7 @@ class HttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> typing.Iterator[httpx.Response]:
@@ -307,6 +362,28 @@ class HttpClient:
 
         json_body, data_body = get_request_body(json=json, data=data, request_options=request_options, omit=omit)
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {})
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit,
+                    )
+                )
+            )
+        )
+
         with self.httpx_client.stream(
             method=method,
             url=urllib.parse.urljoin(f"{base_url}/", path),
@@ -319,23 +396,7 @@ class HttpClient:
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {})
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,
@@ -353,12 +414,19 @@ class AsyncHttpClient:
         base_timeout: typing.Callable[[], typing.Optional[float]],
         base_headers: typing.Callable[[], typing.Dict[str, str]],
         base_url: typing.Optional[typing.Callable[[], str]] = None,
+        async_base_headers: typing.Optional[typing.Callable[[], typing.Awaitable[typing.Dict[str, str]]]] = None,
     ):
         self.base_url = base_url
         self.base_timeout = base_timeout
         self.base_headers = base_headers
+        self.async_base_headers = async_base_headers
         self.httpx_client = httpx_client
 
+    async def _get_headers(self) -> typing.Dict[str, str]:
+        if self.async_base_headers is not None:
+            return await self.async_base_headers()
+        return self.base_headers()
+
     def get_base_url(self, maybe_base_url: typing.Optional[str]) -> str:
         base_url = maybe_base_url
         if self.base_url is not None and base_url is None:
@@ -386,7 +454,7 @@ class AsyncHttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> httpx.Response:
@@ -408,6 +476,31 @@ class AsyncHttpClient:
 
         json_body, data_body = get_request_body(json=json, data=data, request_options=request_options, omit=omit)
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Get headers (supports async token providers)
+        _headers = await self._get_headers()
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {}) or {}
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit,
+                    )
+                )
+            )
+        )
+
         # Add the input to each of these and do None-safety checks
         response = await self.httpx_client.request(
             method=method,
@@ -415,29 +508,13 @@ class AsyncHttpClient:
             headers=jsonable_encoder(
                 remove_none_from_dict(
                     {
-                        **self.base_headers(),
+                        **_headers,
                         **(headers if headers is not None else {}),
                         **(request_options.get("additional_headers", {}) or {} if request_options is not None else {}),
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {}) or {}
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,
@@ -445,9 +522,9 @@ class AsyncHttpClient:
             timeout=timeout,
         )
 
-        max_retries: int = request_options.get("max_retries", 0) if request_options is not None else 0
+        max_retries: int = request_options.get("max_retries", 2) if request_options is not None else 2
         if _should_retry(response=response):
-            if max_retries > retries:
+            if retries < max_retries:
                 await asyncio.sleep(_retry_timeout(response=response, retries=retries))
                 return await self.request(
                     path=path,
@@ -483,7 +560,7 @@ class AsyncHttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> typing.AsyncIterator[httpx.Response]:
@@ -505,35 +582,44 @@ class AsyncHttpClient:
 
         json_body, data_body = get_request_body(json=json, data=data, request_options=request_options, omit=omit)
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Get headers (supports async token providers)
+        _headers = await self._get_headers()
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {})
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit=omit,
+                    )
+                )
+            )
+        )
+
         async with self.httpx_client.stream(
             method=method,
             url=urllib.parse.urljoin(f"{base_url}/", path),
             headers=jsonable_encoder(
                 remove_none_from_dict(
                     {
-                        **self.base_headers(),
+                        **_headers,
                         **(headers if headers is not None else {}),
                         **(request_options.get("additional_headers", {}) if request_options is not None else {}),
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {})
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit=omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,