osdu-python-client 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

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/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/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/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/errors.py

@@ -1,3 +1,8 @@
+import functools
+
+import httpx
+
+
 class OsduError(Exception):
     pass
 
@@ -14,3 +19,26 @@ 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/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/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/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.9.0.dist-info → osdu_python_client-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osdu-python-client
-Version: 0.9.0
+Version: 0.11.0
 Summary: Python client for OSDU services
 Author: OSDU team
 License-Expression: Apache-2.0
@@ -20,11 +20,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: attrs>=26.1.0
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: openapi-python-client>=0.28.3
 Requires-Dist: pydantic-settings>=2.13.1
 Requires-Dist: python-dateutil>=2.9.0.post0
-Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: ruff>=0.15.12
 Provides-Extra: azure
 Requires-Dist: msal>=1.35.1; extra == "azure"
 Requires-Dist: azure-identity>=1.14.0; extra == "azure"
@@ -45,6 +42,9 @@ Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
 Requires-Dist: pytest-mock==3.15.1; extra == "dev"
 Requires-Dist: pydantic-settings==2.14.0; extra == "dev"
 Requires-Dist: msal==1.36.0; extra == "dev"
+Requires-Dist: openapi-python-client<0.29,>=0.28.3; extra == "dev"
+Requires-Dist: pyyaml>=6.0.3; extra == "dev"
+Requires-Dist: ruff>=0.15.12; extra == "dev"
 Dynamic: license-file
 
 # OSDU Python Client
@@ -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.9.0.dist-info → osdu_python_client-0.11.0.dist-info}/RECORD

@@ -1,14 +1,14 @@
-osdu_python_client/__init__.py,sha256=IfMMte_prpYP-4VZa-gmeYoQGgArDGuoFxYW9RKZol8,796
-osdu_python_client/async_client.py,sha256=4O07GD4mEFIblPK5FAkzw9yJoOtlsjoPPeq71TEjBIk,4995
+osdu_python_client/__init__.py,sha256=lH0Q4LFBhfdGQIVxALAOc4IaUO-Ly0CJp3dMb2aw8w0,846
+osdu_python_client/async_client.py,sha256=XocPs2KyoS7c5azGmQvIiGqGMmqSmgPeNR7uuN3-y1Y,5642
 osdu_python_client/async_client.pyi,sha256=6OqjLvRoN_MrxZiJ9T2aQKHpjyIApkyGpd4D9PlBx-U,2937
-osdu_python_client/client.py,sha256=-cnJK4Z5qqV50KoHT5frZnUvvxWsKEsWgjYl6XlkLfY,4926
+osdu_python_client/client.py,sha256=iZbYwiiJYw8T7Xgp6ACZK0-yx6aVgmPqKkx_ahgHaSc,5487
 osdu_python_client/client.pyi,sha256=mqlvJgG9A9Qse2-IkO6Yutt3vX4SEhu08cA0irV1XbQ,2685
-osdu_python_client/config.py,sha256=bVEYrYGmD5yDfIT-uzvLb4UKR4x5qC67Cn6jYRhps6E,1666
-osdu_python_client/errors.py,sha256=4Je5XW67es-uYUXs7mjBQxxYcw-VPAHOUgqRjxcsQdc,315
+osdu_python_client/config.py,sha256=wo1Cfs5CNwSFsVwUxwuM8JFQT5zPd1HWJRuBleguwsw,2137
+osdu_python_client/errors.py,sha256=kISd0BDTu4r1o1OBnCGmkGGZ1V00kiZUvYCMm8-2xpY,1374
 osdu_python_client/hooks.py,sha256=_VxWw1iEoEELfgJysar0jwDcdJesTF5WCrRhgY3j3cw,561
 osdu_python_client/logging_setup.py,sha256=lIOhkzg9BOsET2TbaNNdNJPT0C1-6-4ae5c7UOEX3hs,1286
 osdu_python_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-osdu_python_client/transport.py,sha256=SrFmuozAUgUtMUDCn-7g_gMFee2vcQU-Hq6ZPaetLac,9613
+osdu_python_client/transport.py,sha256=eKQQUduqNACGmdHW8mpgobFYe9OwLm_zwBmSo64XSiA,10528
 osdu_python_client/auth/__init__.py,sha256=yUfClGNUgwP1RP7e_EJnTNslcJDY4NNTJmfoD0Rr_s4,2478
 osdu_python_client/auth/_base.py,sha256=GMvdYiXcbRPglG5zGZbLnGfCdNUh2C7-RwVHwFB2QRM,1967
 osdu_python_client/auth/aws.py,sha256=wT9w7YkQsa91l9qcYoYpCqRiNVZ7eegmQJKEvLdcYYI,3423
@@ -945,11 +945,11 @@ osdu_python_client/generated/workflow/models/workflow_run_response.py,sha256=ORX
 osdu_python_client/generated/workflow/models/workflow_run_response_status.py,sha256=cjW9NPUtP1s31DBOObnTH3feY3_kLxu7YXHV5uKNmcE,274
 osdu_python_client/generated/workflow/models/workflow_run_status.py,sha256=cvpitWQX_eoirngqDCfFYHDtN3RAPoWU_9Zk6IPXT-U,268
 osdu_python_client/services/__init__.py,sha256=_ZJwu7SBUPudjm_Kotd5vjSo_nQKlUh4SaSxBAYqiuM,112
-osdu_python_client/services/facade.py,sha256=YJqRc5gex8dU1bax2k_mk_OiPo7dcTfVaxnd69dMto4,5947
+osdu_python_client/services/facade.py,sha256=pXDYYfVcn3Ls1L1It6tVOv-gZgD8uKg8K9JmEn_kbDc,6544
 osdu_python_client/services/registry.py,sha256=T8norw7WM3RucbktjENpA00CTnRu3chn9KzAAfddviA,5459
-osdu_python_client/services/wellbore_ddms.py,sha256=xyVCTe2O5UkhReMVmDuT5XmhzHWJTLx7fdSNK8ckFYA,20468
-osdu_python_client-0.9.0.dist-info/licenses/LICENSE,sha256=mbmpdYp4WedCVTL1gTJqhNVnR6h012ht-b3eG9xYM3A,11418
-osdu_python_client-0.9.0.dist-info/METADATA,sha256=ZrTdw2nfEAymupN9rPmzM5RY59QFVygOKVWf1afIdVc,14663
-osdu_python_client-0.9.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-osdu_python_client-0.9.0.dist-info/top_level.txt,sha256=1WpzwJhlCok7kjThasFuwXMOk7lfy_GaubVUv0217Ck,19
-osdu_python_client-0.9.0.dist-info/RECORD,,
+osdu_python_client/services/wellbore_ddms.py,sha256=3DunJJcjcn0DRx_ONgm14xl3ikrz6AoQs_JYKwFsEwY,20756
+osdu_python_client-0.11.0.dist-info/licenses/LICENSE,sha256=mbmpdYp4WedCVTL1gTJqhNVnR6h012ht-b3eG9xYM3A,11418
+osdu_python_client-0.11.0.dist-info/METADATA,sha256=xI9IuLqtMz20Rrm6kqBxFwvvy645D_DThUj7KaHpMpA,15152
+osdu_python_client-0.11.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+osdu_python_client-0.11.0.dist-info/top_level.txt,sha256=1WpzwJhlCok7kjThasFuwXMOk7lfy_GaubVUv0217Ck,19
+osdu_python_client-0.11.0.dist-info/RECORD,,