fix: prevent exceptions while parsing HTTP response error bodies (#911)

ci.ruff.toml

@@ -1,4 +1,6 @@
 # This is the Ruff config used in CI.
 # In development, ruff.toml is used instead.
 
-target-version = 'py38'
+target-version = 'py38'
+[lint]
+exclude = ["langfuse/api/**/*.py"]

langfuse/Sampler.py

@@ -37,7 +37,7 @@ def sample_event(self, event: dict):
             return True
 
     def deterministic_sample(self, trace_id: str, sample_rate: float):
-        """determins if an event should be sampled based on the trace_id and sample_rate. Event will be sent to server if True"""
+        """Determins if an event should be sampled based on the trace_id and sample_rate. Event will be sent to server if True"""
         log.debug(
             f"Applying deterministic sampling to trace_id: {trace_id} with rate {sample_rate}"
         )

langfuse/api/README.md

@@ -0,0 +1,161 @@
+# Finto Python Library
+
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-SDK%20generated%20by%20Fern-brightgreen)](https://github.com/fern-api/fern)
+[![pypi](https://img.shields.io/pypi/v/finto)](https://pypi.python.org/pypi/finto)
+
+The Finto Python library provides convenient access to the Finto API from Python.
+
+## Installation
+
+```sh
+pip install finto
+```
+
+## Usage
+
+Instantiate and use the client with the following:
+
+```python
+from finto import CreateDatasetItemRequest, DatasetStatus
+from finto.client import FernLangfuse
+
+client = FernLangfuse(
+    x_langfuse_sdk_name="YOUR_X_LANGFUSE_SDK_NAME",
+    x_langfuse_sdk_version="YOUR_X_LANGFUSE_SDK_VERSION",
+    x_langfuse_public_key="YOUR_X_LANGFUSE_PUBLIC_KEY",
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    base_url="https://yourhost.com/path/to/api",
+)
+client.dataset_items.create(
+    request=CreateDatasetItemRequest(
+        dataset_name="string",
+        input={"key": "value"},
+        expected_output={"key": "value"},
+        metadata={"key": "value"},
+        source_trace_id="string",
+        source_observation_id="string",
+        id="string",
+        status=DatasetStatus.ACTIVE,
+    ),
+)
+```
+
+## Async Client
+
+The SDK also exports an `async` client so that you can make non-blocking calls to our API.
+
+```python
+import asyncio
+
+from finto import CreateDatasetItemRequest, DatasetStatus
+from finto.client import AsyncFernLangfuse
+
+client = AsyncFernLangfuse(
+    x_langfuse_sdk_name="YOUR_X_LANGFUSE_SDK_NAME",
+    x_langfuse_sdk_version="YOUR_X_LANGFUSE_SDK_VERSION",
+    x_langfuse_public_key="YOUR_X_LANGFUSE_PUBLIC_KEY",
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    base_url="https://yourhost.com/path/to/api",
+)
+
+
+async def main() -> None:
+    await client.dataset_items.create(
+        request=CreateDatasetItemRequest(
+            dataset_name="string",
+            input={"key": "value"},
+            expected_output={"key": "value"},
+            metadata={"key": "value"},
+            source_trace_id="string",
+            source_observation_id="string",
+            id="string",
+            status=DatasetStatus.ACTIVE,
+        ),
+    )
+
+
+asyncio.run(main())
+```
+
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be thrown.
+
+```python
+from .api_error import ApiError
+
+try:
+    client.dataset_items.create(...)
+except ApiError as e:
+    print(e.status_code)
+    print(e.body)
+```
+
+## Advanced
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retriable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
+
+A request is deemed retriable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
+
+Use the `max_retries` request option to configure this behavior.
+
+```python
+client.dataset_items.create(...,{
+    max_retries=1
+})
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.
+
+```python
+
+from finto.client import FernLangfuse
+
+client = FernLangfuse(..., { timeout=20.0 }, )
+
+
+# Override timeout for a specific method
+client.dataset_items.create(...,{
+    timeout_in_seconds=1
+})
+```
+
+### Custom Client
+
+You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies
+and transports.
+```python
+import httpx
+from finto.client import FernLangfuse
+
+client = FernLangfuse(
+    ...,
+    http_client=httpx.Client(
+        proxies="http://my.test.proxy.example.com",
+        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
+    ),
+)
+```
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

langfuse/api/client.py

@@ -6,10 +6,7 @@
 
 from .core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
 from .resources.dataset_items.client import AsyncDatasetItemsClient, DatasetItemsClient
-from .resources.dataset_run_items.client import (
-    AsyncDatasetRunItemsClient,
-    DatasetRunItemsClient,
-)
+from .resources.dataset_run_items.client import AsyncDatasetRunItemsClient, DatasetRunItemsClient
 from .resources.datasets.client import AsyncDatasetsClient, DatasetsClient
 from .resources.health.client import AsyncHealthClient, HealthClient
 from .resources.ingestion.client import AsyncIngestionClient, IngestionClient
@@ -26,27 +23,29 @@
 
 class FernLangfuse:
     """
-    Use this class to access the different functions within the SDK. You can instantiate any number of clients with different configuration that will propogate to these functions.
+    Use this class to access the different functions within the SDK. You can instantiate any number of clients with different configuration that will propagate to these functions.
 
-    Parameters:
-        - base_url: str. The base url to use for requests from the client.
+    Parameters
+    ----------
+    base_url : str
+        The base url to use for requests from the client.
 
-        - x_langfuse_sdk_name: typing.Optional[str].
+    x_langfuse_sdk_name : typing.Optional[str]
+    x_langfuse_sdk_version : typing.Optional[str]
+    x_langfuse_public_key : typing.Optional[str]
+    username : typing.Optional[typing.Union[str, typing.Callable[[], str]]]
+    password : typing.Optional[typing.Union[str, typing.Callable[[], str]]]
+    timeout : typing.Optional[float]
+        The timeout to be used, in seconds, for requests. By default the timeout is 60 seconds, unless a custom httpx client is used, in which case this default is not enforced.
 
-        - x_langfuse_sdk_version: typing.Optional[str].
+    follow_redirects : typing.Optional[bool]
+        Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
 
-        - x_langfuse_public_key: typing.Optional[str].
+    httpx_client : typing.Optional[httpx.Client]
+        The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
 
-        - username: typing.Optional[typing.Union[str, typing.Callable[[], str]]].
-
-        - password: typing.Optional[typing.Union[str, typing.Callable[[], str]]].
-
-        - timeout: typing.Optional[float]. The timeout to be used, in seconds, for requests by default the timeout is 60 seconds, unless a custom httpx client is used, in which case a default is not set.
-
-        - follow_redirects: typing.Optional[bool]. Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
-
-        - httpx_client: typing.Optional[httpx.Client]. The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
-    ---
+    Examples
+    --------
     from finto.client import FernLangfuse
 
     client = FernLangfuse(
@@ -69,12 +68,10 @@ def __init__(
         username: typing.Optional[typing.Union[str, typing.Callable[[], str]]] = None,
         password: typing.Optional[typing.Union[str, typing.Callable[[], str]]] = None,
         timeout: typing.Optional[float] = None,
-        follow_redirects: typing.Optional[bool] = None,
-        httpx_client: typing.Optional[httpx.Client] = None,
+        follow_redirects: typing.Optional[bool] = True,
+        httpx_client: typing.Optional[httpx.Client] = None
     ):
-        _defaulted_timeout = (
-            timeout if timeout is not None else 60 if httpx_client is None else None
-        )
+        _defaulted_timeout = timeout if timeout is not None else 60 if httpx_client is None else None
         self._client_wrapper = SyncClientWrapper(
             base_url=base_url,
             x_langfuse_sdk_name=x_langfuse_sdk_name,
@@ -84,17 +81,13 @@ def __init__(
             password=password,
             httpx_client=httpx_client
             if httpx_client is not None
-            else httpx.Client(
-                timeout=_defaulted_timeout, follow_redirects=follow_redirects
-            )
+            else httpx.Client(timeout=_defaulted_timeout, follow_redirects=follow_redirects)
             if follow_redirects is not None
             else httpx.Client(timeout=_defaulted_timeout),
             timeout=_defaulted_timeout,
         )
         self.dataset_items = DatasetItemsClient(client_wrapper=self._client_wrapper)
-        self.dataset_run_items = DatasetRunItemsClient(
-            client_wrapper=self._client_wrapper
-        )
+        self.dataset_run_items = DatasetRunItemsClient(client_wrapper=self._client_wrapper)
         self.datasets = DatasetsClient(client_wrapper=self._client_wrapper)
         self.health = HealthClient(client_wrapper=self._client_wrapper)
         self.ingestion = IngestionClient(client_wrapper=self._client_wrapper)
@@ -111,27 +104,29 @@ def __init__(
 
 class AsyncFernLangfuse:
     """
-    Use this class to access the different functions within the SDK. You can instantiate any number of clients with different configuration that will propogate to these functions.
-
-    Parameters:
-        - base_url: str. The base url to use for requests from the client.
+    Use this class to access the different functions within the SDK. You can instantiate any number of clients with different configuration that will propagate to these functions.
 
-        - x_langfuse_sdk_name: typing.Optional[str].
+    Parameters
+    ----------
+    base_url : str
+        The base url to use for requests from the client.
 
-        - x_langfuse_sdk_version: typing.Optional[str].
+    x_langfuse_sdk_name : typing.Optional[str]
+    x_langfuse_sdk_version : typing.Optional[str]
+    x_langfuse_public_key : typing.Optional[str]
+    username : typing.Optional[typing.Union[str, typing.Callable[[], str]]]
+    password : typing.Optional[typing.Union[str, typing.Callable[[], str]]]
+    timeout : typing.Optional[float]
+        The timeout to be used, in seconds, for requests. By default the timeout is 60 seconds, unless a custom httpx client is used, in which case this default is not enforced.
 
-        - x_langfuse_public_key: typing.Optional[str].
+    follow_redirects : typing.Optional[bool]
+        Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
 
-        - username: typing.Optional[typing.Union[str, typing.Callable[[], str]]].
+    httpx_client : typing.Optional[httpx.AsyncClient]
+        The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
 
-        - password: typing.Optional[typing.Union[str, typing.Callable[[], str]]].
-
-        - timeout: typing.Optional[float]. The timeout to be used, in seconds, for requests by default the timeout is 60 seconds, unless a custom httpx client is used, in which case a default is not set.
-
-        - follow_redirects: typing.Optional[bool]. Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
-
-        - httpx_client: typing.Optional[httpx.AsyncClient]. The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
-    ---
+    Examples
+    --------
     from finto.client import AsyncFernLangfuse
 
     client = AsyncFernLangfuse(
@@ -154,12 +149,10 @@ def __init__(
         username: typing.Optional[typing.Union[str, typing.Callable[[], str]]] = None,
         password: typing.Optional[typing.Union[str, typing.Callable[[], str]]] = None,
         timeout: typing.Optional[float] = None,
-        follow_redirects: typing.Optional[bool] = None,
-        httpx_client: typing.Optional[httpx.AsyncClient] = None,
+        follow_redirects: typing.Optional[bool] = True,
+        httpx_client: typing.Optional[httpx.AsyncClient] = None
     ):
-        _defaulted_timeout = (
-            timeout if timeout is not None else 60 if httpx_client is None else None
-        )
+        _defaulted_timeout = timeout if timeout is not None else 60 if httpx_client is None else None
         self._client_wrapper = AsyncClientWrapper(
             base_url=base_url,
             x_langfuse_sdk_name=x_langfuse_sdk_name,
@@ -169,19 +162,13 @@ def __init__(
             password=password,
             httpx_client=httpx_client
             if httpx_client is not None
-            else httpx.AsyncClient(
-                timeout=_defaulted_timeout, follow_redirects=follow_redirects
-            )
+            else httpx.AsyncClient(timeout=_defaulted_timeout, follow_redirects=follow_redirects)
             if follow_redirects is not None
             else httpx.AsyncClient(timeout=_defaulted_timeout),
             timeout=_defaulted_timeout,
         )
-        self.dataset_items = AsyncDatasetItemsClient(
-            client_wrapper=self._client_wrapper
-        )
-        self.dataset_run_items = AsyncDatasetRunItemsClient(
-            client_wrapper=self._client_wrapper
-        )
+        self.dataset_items = AsyncDatasetItemsClient(client_wrapper=self._client_wrapper)
+        self.dataset_run_items = AsyncDatasetRunItemsClient(client_wrapper=self._client_wrapper)
         self.datasets = AsyncDatasetsClient(client_wrapper=self._client_wrapper)
         self.health = AsyncHealthClient(client_wrapper=self._client_wrapper)
         self.ingestion = AsyncIngestionClient(client_wrapper=self._client_wrapper)
@@ -190,9 +177,7 @@ def __init__(
         self.observations = AsyncObservationsClient(client_wrapper=self._client_wrapper)
         self.projects = AsyncProjectsClient(client_wrapper=self._client_wrapper)
         self.prompts = AsyncPromptsClient(client_wrapper=self._client_wrapper)
-        self.score_configs = AsyncScoreConfigsClient(
-            client_wrapper=self._client_wrapper
-        )
+        self.score_configs = AsyncScoreConfigsClient(client_wrapper=self._client_wrapper)
         self.score = AsyncScoreClient(client_wrapper=self._client_wrapper)
         self.sessions = AsyncSessionsClient(client_wrapper=self._client_wrapper)
         self.trace = AsyncTraceClient(client_wrapper=self._client_wrapper)

langfuse/api/core/__init__.py

@@ -6,7 +6,8 @@
 from .file import File, convert_file_dict_to_httpx_tuples
 from .http_client import AsyncHttpClient, HttpClient
 from .jsonable_encoder import jsonable_encoder
-from .pydantic_utilities import pydantic_v1
+from .pydantic_utilities import deep_union_pydantic_dicts, pydantic_v1
+from .query_encoder import encode_query
 from .remove_none_from_dict import remove_none_from_dict
 from .request_options import RequestOptions
 
@@ -20,6 +21,8 @@
     "RequestOptions",
     "SyncClientWrapper",
     "convert_file_dict_to_httpx_tuples",
+    "deep_union_pydantic_dicts",
+    "encode_query",
     "jsonable_encoder",
     "pydantic_v1",
     "remove_none_from_dict",