osdu-python-client 0.10.0__tar.gz → 0.11.0__tar.gz

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osdu-python-client
-Version: 0.10.0
+Version: 0.11.0
 Summary: Python client for OSDU services
 Author: OSDU team
 License-Expression: Apache-2.0
@@ -90,7 +90,7 @@ with OsduClient() as osdu:  # config loaded from .env
         print(record.additional_properties)
 ```
 
-Each `osdu.<service>.<operation>(...)` call auto-binds the underlying client and `data-partition-id`, returns the parsed response model on 2xx, and raises `OsduError` on non-2xx. Call `.detailed(...)` on any operation to get the full `Response` envelope (status code, headers, parsed error model).
+Each `osdu.<service>.<operation>(...)` call auto-binds the underlying client and `data-partition-id`, returns the parsed response model on 2xx, and raises `OsduError` on non-2xx — or `OsduTransportError`, also an `OsduError`, when no response arrives at all. Call `.detailed(...)` on any operation to get the full `Response` envelope (status code, headers, parsed error model).
 
 ## Typed data models (optional companion)
 
@@ -241,6 +241,8 @@ with osdu.with_headers(**{"x-correlation-id": correlation_id}):
 
 The async client exposes the same helper as `async with osdu.with_headers(...)`.
 
+`with_headers` changes service clients that every caller of `osdu` shares, so it is for process-wide values. In a web service, pass per-request values per call instead — see [Using the client in a web service](https://community.opengroup.org/osdu/platform/system/sdks/osdu-python-client/-/blob/main/docs/usage.md#using-the-client-in-a-web-service).
+
 ## Wellbore DDMS: Parquet bulk data
 
 Well-log bulk data is served as Parquet by Wellbore DDMS (the `/data` endpoints

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/README.md

@@ -41,7 +41,7 @@ with OsduClient() as osdu:  # config loaded from .env
         print(record.additional_properties)
 ```
 
-Each `osdu.<service>.<operation>(...)` call auto-binds the underlying client and `data-partition-id`, returns the parsed response model on 2xx, and raises `OsduError` on non-2xx. Call `.detailed(...)` on any operation to get the full `Response` envelope (status code, headers, parsed error model).
+Each `osdu.<service>.<operation>(...)` call auto-binds the underlying client and `data-partition-id`, returns the parsed response model on 2xx, and raises `OsduError` on non-2xx — or `OsduTransportError`, also an `OsduError`, when no response arrives at all. Call `.detailed(...)` on any operation to get the full `Response` envelope (status code, headers, parsed error model).
 
 ## Typed data models (optional companion)
 
@@ -192,6 +192,8 @@ with osdu.with_headers(**{"x-correlation-id": correlation_id}):
 
 The async client exposes the same helper as `async with osdu.with_headers(...)`.
 
+`with_headers` changes service clients that every caller of `osdu` shares, so it is for process-wide values. In a web service, pass per-request values per call instead — see [Using the client in a web service](https://community.opengroup.org/osdu/platform/system/sdks/osdu-python-client/-/blob/main/docs/usage.md#using-the-client-in-a-web-service).
+
 ## Wellbore DDMS: Parquet bulk data
 
 Well-log bulk data is served as Parquet by Wellbore DDMS (the `/data` endpoints

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "osdu-python-client"
-version = "0.10.0"
+version = "0.11.0"
 description = "Python client for OSDU services"
 readme = "README.md"
 requires-python = ">=3.10"

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client/__init__.py

@@ -12,6 +12,7 @@ from osdu_python_client.errors import (
     OsduConfigError,
     OsduError,
     OsduRetryExhausted,
+    OsduTransportError,
 )
 from osdu_python_client.logging_setup import enable_debug_logging
 
@@ -26,6 +27,7 @@ __all__ = [
     "OsduConfigError",
     "OsduError",
     "OsduRetryExhausted",
+    "OsduTransportError",
     "TokenProvider",
     "enable_debug_logging",
 ]

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client/async_client.py

@@ -15,7 +15,7 @@ from osdu_python_client.services.registry import (
     ServiceSpec,
     load_authenticated_client,
 )
-from osdu_python_client.transport import AsyncRetryTransport
+from osdu_python_client.transport import AsyncRetryTransport, warn_on_overwritten_headers
 
 
 class AsyncOsduClient:
@@ -98,6 +98,17 @@ class AsyncOsduClient:
     async def with_headers(
         self, *, service: str | None = None, **headers: str
     ) -> AsyncIterator["AsyncOsduClient"]:
+        """Temporarily set extra headers on one or all built service clients.
+
+        The headers are written onto the service clients themselves, which
+        every caller of this ``AsyncOsduClient`` shares. Use it for process-wide
+        values (a CRS ``frame-of-reference``, a batch job's correlation id),
+        not per-request ones: in a web service, concurrent requests would see
+        each other's headers. Per-request partition goes in as
+        ``data_partition_id=`` on the operation; per-request auth goes through
+        a ``TokenProvider``.
+        """
+        warn_on_overwritten_headers(headers)
         if service is not None:
             getattr(self, service)
             # ``_httpx_clients`` is keyed by the canonical attribute, so an

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client/client.py

@@ -15,7 +15,7 @@ from osdu_python_client.services.registry import (
     ServiceSpec,
     load_authenticated_client,
 )
-from osdu_python_client.transport import RetryTransport
+from osdu_python_client.transport import RetryTransport, warn_on_overwritten_headers
 
 
 class OsduClient:
@@ -96,7 +96,17 @@ class OsduClient:
     def with_headers(
         self, *, service: str | None = None, **headers: str
     ) -> Iterator["OsduClient"]:
-        """Temporarily set extra headers on one or all built service clients."""
+        """Temporarily set extra headers on one or all built service clients.
+
+        The headers are written onto the service clients themselves, which
+        every caller of this ``OsduClient`` shares. Use it for process-wide
+        values (a CRS ``frame-of-reference``, a batch job's correlation id),
+        not per-request ones: in a web service, concurrent requests would see
+        each other's headers. Per-request partition goes in as
+        ``data_partition_id=`` on the operation; per-request auth goes through
+        a ``TokenProvider``.
+        """
+        warn_on_overwritten_headers(headers)
         if service is not None:
             getattr(self, service)
             # ``_httpx_clients`` is keyed by the canonical attribute, so an

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client/config.py

@@ -46,4 +46,14 @@ class OsduConfig(BaseSettings):
         return spec.endpoint
 
     def url_for(self, service: str) -> str:
-        return f"{self.server.rstrip('/')}{self.endpoint_for(service)}"
+        """Base URL for ``service``.
+
+        An ``endpoint_overrides`` value is normally a path appended to
+        ``server``. An absolute ``http(s)://`` value is used as-is instead, for
+        deployments where a service is not reachable under the shared server --
+        a sidecar, a port-forward, or a service on another host.
+        """
+        endpoint = self.endpoint_for(service)
+        if endpoint.startswith(("http://", "https://")):
+            return endpoint.rstrip("/")
+        return f"{self.server.rstrip('/')}{endpoint}"

osdu_python_client-0.11.0/src/osdu_python_client/errors.py

@@ -0,0 +1,44 @@
+import functools
+
+import httpx
+
+
+class OsduError(Exception):
+    pass
+
+
+class OsduConfigError(OsduError):
+    pass
+
+
+class OsduAuthError(OsduError):
+    pass
+
+
+class OsduRetryExhausted(OsduError):
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class OsduTransportError(OsduError):
+    """No HTTP response was received: connect failure, timeout, protocol error.
+
+    Raised by facade calls in place of the underlying ``httpx.TransportError``.
+    The concrete exception also subclasses the original httpx type (see
+    :func:`wrap_transport_error`), so ``except httpx.ConnectError`` written
+    before this existed still catches it, and ``except OsduError`` now catches
+    every facade failure.
+    """
+
+
+@functools.cache
+def _transport_error_type(cls: type[httpx.TransportError]) -> type[OsduTransportError]:
+    return type(f"Osdu{cls.__name__}", (OsduTransportError, cls), {})
+
+
+def wrap_transport_error(err: httpx.TransportError) -> OsduTransportError:
+    request: httpx.Request | None = getattr(err, "_request", None)
+    target = f" calling {request.method} {request.url}" if request is not None else ""
+    wrapped_cls = _transport_error_type(type(err))
+    return wrapped_cls(f"{type(err).__name__}{target}: {err}", request=request)  # type: ignore[call-arg]

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client/services/facade.py

@@ -6,7 +6,9 @@ import pkgutil
 from types import ModuleType
 from typing import Any
 
-from osdu_python_client.errors import OsduError
+import httpx
+
+from osdu_python_client.errors import OsduError, wrap_transport_error
 
 
 _ERROR_BODY_MAX = 1024
@@ -43,6 +45,9 @@ class Endpoint:
 
     ``.detailed(...)`` returns the full ``Response`` envelope for callers who
     need status code / headers / raw parsed error model.
+
+    Both raise ``OsduTransportError`` when no response arrives at all
+    (connect failure, timeout), so ``except OsduError`` covers every failure.
     """
 
     __slots__ = (
@@ -88,15 +93,27 @@ class Endpoint:
     def __call__(self, *args: Any, **kw: Any) -> Any:
         if self._is_async:
             return self._async_call(*args, **kw)
-        return _unwrap(self._sync_detailed(*args, **self._bind(kw)))
+        return _unwrap(self._sync_send(*args, **kw))
 
     def detailed(self, *args: Any, **kw: Any) -> Any:
         if self._is_async:
-            return self._async_detailed(*args, **self._bind(kw))
-        return self._sync_detailed(*args, **self._bind(kw))
+            return self._async_send(*args, **kw)
+        return self._sync_send(*args, **kw)
+
+    def _sync_send(self, *args: Any, **kw: Any) -> Any:
+        try:
+            return self._sync_detailed(*args, **self._bind(kw))
+        except httpx.TransportError as err:
+            raise wrap_transport_error(err) from err
+
+    async def _async_send(self, *args: Any, **kw: Any) -> Any:
+        try:
+            return await self._async_detailed(*args, **self._bind(kw))
+        except httpx.TransportError as err:
+            raise wrap_transport_error(err) from err
 
     async def _async_call(self, *args: Any, **kw: Any) -> Any:
-        return _unwrap(await self._async_detailed(*args, **self._bind(kw)))
+        return _unwrap(await self._async_send(*args, **kw))
 
 
 class ServiceFacade:

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client/services/wellbore_ddms.py

@@ -22,7 +22,9 @@ from __future__ import annotations
 from typing import Any
 from urllib.parse import quote
 
-from osdu_python_client.errors import OsduError
+import httpx
+
+from osdu_python_client.errors import OsduError, wrap_transport_error
 from osdu_python_client.services.facade import ServiceFacade
 
 PARQUET_MEDIA_TYPE = "application/x-parquet"
@@ -345,6 +347,18 @@ class WellboreDdmsFacade(ServiceFacade):
 
     # -- helpers -----------------------------------------------------------
 
+    def _request_sync(self, **kw: Any) -> httpx.Response:
+        try:
+            return self._client.get_httpx_client().request(**kw)
+        except httpx.TransportError as err:
+            raise wrap_transport_error(err) from err
+
+    async def _request_async(self, **kw: Any) -> httpx.Response:
+        try:
+            return await self._client.get_async_httpx_client().request(**kw)
+        except httpx.TransportError as err:
+            raise wrap_transport_error(err) from err
+
     def _headers(self, accept_or_content: str, *, write: bool, dp: str | None) -> dict[str, str]:
         key = "Content-Type" if write else "Accept"
         headers = {key: accept_or_content}
@@ -382,7 +396,7 @@ class WellboreDdmsFacade(ServiceFacade):
         as_dataframe, data_partition_id,
     ) -> Any:
         url = _data_url(entity, record_id, version)
-        response = self._client.get_httpx_client().request(
+        response = self._request_sync(
             method="get",
             url=url,
             params=_read_params(offset, limit, curves, filter_),
@@ -394,7 +408,7 @@ class WellboreDdmsFacade(ServiceFacade):
     def _write_bulk_parquet_sync(self, record_id, data, entity, data_partition_id) -> Any:
         url = _data_url(entity, record_id, None)
         body = self._encode_table(data)
-        response = self._client.get_httpx_client().request(
+        response = self._request_sync(
             method="post",
             url=url,
             content=body,
@@ -407,7 +421,7 @@ class WellboreDdmsFacade(ServiceFacade):
         self, record_id, entity, mode, from_version, time_to_live, meta, dp,
     ) -> str:
         url = _sessions_url(entity, record_id)
-        response = self._client.get_httpx_client().request(
+        response = self._request_sync(
             method="post",
             url=url,
             json=_create_session_body(mode, from_version, time_to_live, meta),
@@ -419,7 +433,7 @@ class WellboreDdmsFacade(ServiceFacade):
     def _write_chunk_parquet_sync(self, record_id, session_id, data, entity, dp) -> Any:
         url = _session_data_url(entity, record_id, session_id)
         body = self._encode_table(data)
-        response = self._client.get_httpx_client().request(
+        response = self._request_sync(
             method="post",
             url=url,
             content=body,
@@ -430,7 +444,7 @@ class WellboreDdmsFacade(ServiceFacade):
 
     def _patch_session_sync(self, record_id, session_id, entity, state, dp) -> Any:
         url = _session_url(entity, record_id, session_id)
-        response = self._client.get_httpx_client().request(
+        response = self._request_sync(
             method="patch",
             url=url,
             json={"state": state},
@@ -464,7 +478,7 @@ class WellboreDdmsFacade(ServiceFacade):
         as_dataframe, data_partition_id,
     ) -> Any:
         url = _data_url(entity, record_id, version)
-        response = await self._client.get_async_httpx_client().request(
+        response = await self._request_async(
             method="get",
             url=url,
             params=_read_params(offset, limit, curves, filter_),
@@ -476,7 +490,7 @@ class WellboreDdmsFacade(ServiceFacade):
     async def _write_bulk_parquet_async(self, record_id, data, entity, data_partition_id) -> Any:
         url = _data_url(entity, record_id, None)
         body = self._encode_table(data)
-        response = await self._client.get_async_httpx_client().request(
+        response = await self._request_async(
             method="post",
             url=url,
             content=body,
@@ -489,7 +503,7 @@ class WellboreDdmsFacade(ServiceFacade):
         self, record_id, entity, mode, from_version, time_to_live, meta, dp,
     ) -> str:
         url = _sessions_url(entity, record_id)
-        response = await self._client.get_async_httpx_client().request(
+        response = await self._request_async(
             method="post",
             url=url,
             json=_create_session_body(mode, from_version, time_to_live, meta),
@@ -501,7 +515,7 @@ class WellboreDdmsFacade(ServiceFacade):
     async def _write_chunk_parquet_async(self, record_id, session_id, data, entity, dp) -> Any:
         url = _session_data_url(entity, record_id, session_id)
         body = self._encode_table(data)
-        response = await self._client.get_async_httpx_client().request(
+        response = await self._request_async(
             method="post",
             url=url,
             content=body,
@@ -512,7 +526,7 @@ class WellboreDdmsFacade(ServiceFacade):
 
     async def _patch_session_async(self, record_id, session_id, entity, state, dp) -> Any:
         url = _session_url(entity, record_id, session_id)
-        response = await self._client.get_async_httpx_client().request(
+        response = await self._request_async(
             method="patch",
             url=url,
             json={"state": state},

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client/transport.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 import random
 import time
+import warnings
 from typing import Iterable, Mapping
 
 import httpx
@@ -66,6 +67,25 @@ def _log_response_body(response: httpx.Response) -> None:
         body_log.debug("← body=%s", _truncate_body(response.content))
 
 
+def warn_on_overwritten_headers(headers: Mapping[str, str]) -> None:
+    """Warn when ``with_headers`` is given a header the transport replaces.
+
+    The transport sets ``Authorization`` from the token provider on every
+    request, so a value passed through ``with_headers`` never reaches the
+    server. Forwarding a caller's token takes a ``TokenProvider`` instead
+    (see docs/usage.md, "Using the client in a web service").
+    """
+    if any(name.lower() == "authorization" for name in headers):
+        warnings.warn(
+            "with_headers(Authorization=...) has no effect: the transport sets "
+            "Authorization from the token provider on every request. Pass a "
+            "TokenProvider that returns the token you want sent instead.",
+            UserWarning,
+            # user code -> contextmanager __enter__ -> with_headers -> here
+            stacklevel=4,
+        )
+
+
 class RetryTransport(httpx.BaseTransport):
     def __init__(
         self,

{osdu_python_client-0.10.0 → osdu_python_client-0.11.0}/src/osdu_python_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osdu-python-client
-Version: 0.10.0
+Version: 0.11.0
 Summary: Python client for OSDU services
 Author: OSDU team
 License-Expression: Apache-2.0
@@ -90,7 +90,7 @@ with OsduClient() as osdu:  # config loaded from .env
         print(record.additional_properties)
 ```
 
-Each `osdu.<service>.<operation>(...)` call auto-binds the underlying client and `data-partition-id`, returns the parsed response model on 2xx, and raises `OsduError` on non-2xx. Call `.detailed(...)` on any operation to get the full `Response` envelope (status code, headers, parsed error model).
+Each `osdu.<service>.<operation>(...)` call auto-binds the underlying client and `data-partition-id`, returns the parsed response model on 2xx, and raises `OsduError` on non-2xx — or `OsduTransportError`, also an `OsduError`, when no response arrives at all. Call `.detailed(...)` on any operation to get the full `Response` envelope (status code, headers, parsed error model).
 
 ## Typed data models (optional companion)
 
@@ -241,6 +241,8 @@ with osdu.with_headers(**{"x-correlation-id": correlation_id}):
 
 The async client exposes the same helper as `async with osdu.with_headers(...)`.
 
+`with_headers` changes service clients that every caller of `osdu` shares, so it is for process-wide values. In a web service, pass per-request values per call instead — see [Using the client in a web service](https://community.opengroup.org/osdu/platform/system/sdks/osdu-python-client/-/blob/main/docs/usage.md#using-the-client-in-a-web-service).
+
 ## Wellbore DDMS: Parquet bulk data
 
 Well-log bulk data is served as Parquet by Wellbore DDMS (the `/data` endpoints

osdu_python_client-0.10.0/src/osdu_python_client/errors.py

@@ -1,16 +0,0 @@
-class OsduError(Exception):
-    pass
-
-
-class OsduConfigError(OsduError):
-    pass
-
-
-class OsduAuthError(OsduError):
-    pass
-
-
-class OsduRetryExhausted(OsduError):
-    def __init__(self, message: str, status_code: int | None = None) -> None:
-        super().__init__(message)
-        self.status_code = status_code