OSDU Python Client
Python client library for OSDU services, automatically generated from OpenAPI specifications and wrapped with a handwritten facade that handles authentication, retries, partition headers, and ergonomic per-operation calls.
Installation
pip install osdu-python-client
The base install supports Community/baremetal (Keycloak client credentials) and AWS (OAuth2 client credentials) — both use only httpx which is already a core dependency. For other cloud providers, install the matching extra:
| Cloud | Extra | Command |
|---|---|---|
| Azure / Entra ID | azure |
pip install 'osdu-python-client[azure]' |
| GCP | gcp |
pip install 'osdu-python-client[gcp]' |
| IBM | ibm |
pip install 'osdu-python-client[ibm]' |
| All providers | all-csp |
pip install 'osdu-python-client[all-csp]' |
Feature extras:
| Feature | Extra | Command |
|---|---|---|
Wellbore DDMS Parquet bulk data (pyarrow) |
parquet |
pip install 'osdu-python-client[parquet]' |
Python 3.10+ is required (tested on 3.10 through 3.14).
Quick Start
from osdu_python_client import OsduClient
from osdu_python_client.generated.search.models.query_request import QueryRequest
with OsduClient() as osdu: # config loaded from .env
dto = osdu.search.query_records(
body=QueryRequest(kind="osdu:wks:master-data--Wellbore:*", query="*", limit=1)
)
for record in dto.results:
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 — 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)
This client keeps each record's data block free-form, matching the canonical
OSDU Map<String, Object> — data is schema-on-read and versioned by kind, so
a single client cannot hard-code every OSDU kind. When you want autocomplete and
runtime validation for a specific kind and version, pair the client with the
companion osdu-python-models
package (osdu_models). It provides typed Pydantic v2 models for
work-product-component, master-data, and dataset entity types, and bridges
into a record through plain model_validate() / model_dump() — no changes to
the client required.
pip install osdu-python-models
from osdu_models.workproductcomponent.well_log.v1_4_0 import Curve, Data
# Read: envelope from the client, `data` validated into a typed model.
record = osdu.wellbore_ddms.get_welllog_osdu(record_id=record_id)
data = Data.model_validate(record.data.additional_properties)
print(data.Name) # typed attribute, not data["Name"]
# Write: author `data` as a model, dump it back into the free-form block.
new = Data(
WellboreID="namespace:master-data--Wellbore:abc:",
Name="example",
Curves=[Curve(CurveID="GR", Mnemonic="GR")],
)
body = {"kind": ..., "acl": ..., "legal": ...,
"data": new.model_dump(by_alias=True, exclude_none=True)}
Depending on the operation, the client may surface data as a generated model
rather than a plain dict; the samples below carry a small helper that normalises
both.
Runnable, end-to-end examples combining both packages live in the separate
equinor/osdu-python-samples
repository — covering search, get, versioning, reference navigation, bulk-data
read/write, and typed WellLog ingestion.
Available Services
| Attribute | Service | Alias |
|---|---|---|
crs_catalog |
CRS Catalog | — |
crs_conversion |
CRS Conversion | — |
dataset |
Dataset | — |
entitlements |
Entitlements | — |
file |
File | — |
indexer |
Indexer | — |
legal |
Legal | — |
notification |
Notification | — |
partition |
Partition | — |
policy |
Policy | — |
register |
Register | — |
schema_service |
Schema | schema |
search |
Search | — |
storage |
Storage | — |
unit_v2 |
Unit v2 | — |
unit_v3 |
Unit v3 | unit |
wellbore_ddms |
Wellbore DDMS | — |
workflow |
Workflow | — |
An alias is the older name for a service that has since been renamed or split; both names return the same object.
Configuration
Configuration is loaded from environment variables or a .env file:
SERVER=https://your-osdu-instance.com
DATA_PARTITION_ID=your-partition
AUTH_PROVIDER=azure_msal
CLIENT_ID=...
AUTHORITY=https://login.microsoftonline.com/<tenant>
SCOPES=.../.default
AUTH_MODE=interactive # interactive | device_flow | client_credentials | workload_identity
Auth Providers
Auth is pluggable via AUTH_PROVIDER. Azure MSAL is built in; other CSPs can be passed directly.
| Provider | Status | Required config |
|---|---|---|
azure_msal |
built-in | CLIENT_ID, AUTHORITY, SCOPES, AUTH_MODE |
aws_cognito |
stub | bring your own TokenProvider |
gcp_iam |
stub | bring your own TokenProvider |
ibm_iam |
stub | bring your own TokenProvider |
Azure MSAL flows
AUTH_MODE |
When to use | Required config |
|---|---|---|
interactive |
Local dev / tests | client_id, authority, scopes |
device_flow |
Headless scripts | client_id, authority, scopes |
client_credentials |
CI, service-to-service | + client_secret |
workload_identity |
AKS / Workload Identity Federation | scopes; optional azure_client_id, azure_tenant_id, azure_federated_token_file |
Tokens are cached to .msal_token_cache.bin (override with MSAL_CACHE_PATH). The transport retries 401 once with force_refresh=True and retries 429/502/503/504 with exponential backoff honouring Retry-After.
For workload_identity the token is cached in memory because there a writeable file system may not be available. The optional parameters are typically set by the Kubernetes runtime.
Custom / bring-your-own provider
Implement the TokenProvider protocol (one method) and pass it directly:
class MyAwsProvider:
def get_token(self, force_refresh: bool = False) -> str:
return "..." # return a bearer token string
osdu = OsduClient(token_provider=MyAwsProvider())
Async
import asyncio
from osdu_python_client import AsyncOsduClient
from osdu_python_client.generated.search.models.query_request import QueryRequest
async def main():
async with AsyncOsduClient() as osdu:
dto = await osdu.search.query_records(
body=QueryRequest(kind="osdu:wks:master-data--Wellbore:*", query="*", limit=1)
)
return dto.results
asyncio.run(main())
Per-service Header Overrides
# Scope extra headers to one service
with osdu.with_headers(service="crs_conversion", **{"frame-of-reference": "units=SI"}):
osdu.crs_conversion.convert_point_v4(body=req)
# Or apply to all services (e.g. correlation IDs)
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.
Wellbore DDMS: Parquet bulk data
Well-log bulk data is served as Parquet by Wellbore DDMS (the /data endpoints
negotiate application/json or application/x-parquet; Parquet is the
primary, performant format). The wellbore_ddms facade adds native Parquet
read/write on top of the generated endpoints. These helpers require the
parquet extra (pip install 'osdu-python-client[parquet]'); calling them
without it raises an ImportError explaining what to install.
# Read bulk data as a pyarrow.Table (or a pandas.DataFrame with as_dataframe=True)
table = osdu.wellbore_ddms.read_bulk_parquet(
record_id,
curves=["MD", "GR"], # optional column filter
limit=10_000, # optional row cap
)
# Write bulk data (pyarrow.Table or pandas.DataFrame), creating a new version
osdu.wellbore_ddms.write_bulk_parquet(record_id, table)
Both helpers accept entity= (welllogs (default), wellboretrajectories,
ppfgdataset, wellpressuretestrawmeasurement), read_bulk_parquet also takes
version= and offset=/filter_=. On the async client both return awaitables.
All other generated endpoints remain available on the same facade (e.g.
osdu.wellbore_ddms.get_welllog_osdu(...)).
For large datasets, write in chunks via a session (open → upload chunks → commit, with automatic abandon-on-error):
# One call orchestrates the whole session lifecycle
osdu.wellbore_ddms.write_bulk_parquet_session(
record_id,
[chunk1, chunk2, chunk3], # a single Table/DataFrame or an iterable of them
mode="update", # or "overwrite"
)
# Or drive the steps yourself for full control
session_id = osdu.wellbore_ddms.open_bulk_session(record_id, mode="update")
osdu.wellbore_ddms.write_chunk_parquet(record_id, session_id, chunk1)
osdu.wellbore_ddms.write_chunk_parquet(record_id, session_id, chunk2)
result = osdu.wellbore_ddms.commit_bulk_session(record_id, session_id)
# ... or osdu.wellbore_ddms.abandon_bulk_session(record_id, session_id)
The generated JSON
/datareads now sendAccept: application/jsonby default (the server otherwise returns Parquet and JSON parsing fails). Useread_bulk_parquetfor the Parquet path.
Debugging
from osdu_python_client import enable_debug_logging
enable_debug_logging() # transport + auth at DEBUG
enable_debug_logging(include_bodies=True) # also log truncated request/response bodies
Authorization and Cookie headers are always redacted from log output. Bodies are off by default because OSDU payloads may contain PII.
Low-level: Raw Generated Client
The generated clients can be used directly with a static token when you need full control:
from osdu_python_client.generated.entitlements.api.list_group_on_behalf_of_api import (
list_all_partition_groups,
)
from osdu_python_client.generated.entitlements.client import AuthenticatedClient
client = AuthenticatedClient(
base_url="https://your-osdu-instance.com/api/entitlements/v2",
token="YOUR_ACCESS_TOKEN",
)
result = list_all_partition_groups.sync_detailed(
client=client,
data_partition_id="your-partition-id",
type_="NONE",
)
if result.parsed:
for group in result.parsed.groups:
print(group.name, group.email)
The async variant is asyncio_detailed(...).
Development
git clone https://community.opengroup.org/osdu/platform/system/sdks/osdu-python-client.git
cd osdu-python-client
uv sync --all-extras
uv run python generate_all.py
uv run pytest -q # offline unit suite; live tests: uv run pytest tests/integration -q
For adding services, updating OpenAPI specs, the release process, and project structure, see docs/development.md.
Related projects
equinor/osdu-python-models— typed Pydantic models (osdu-python-models) for OSDU recorddatablocks, an opt-in companion to this client.equinor/osdu-python-samples— runnable examples showing this client and the typed models used together.equinor/osdu-csharp-client— the C# twin of this client, with its own schemas and samples companions.
License
Ref. License Information
Metadata
Release files for osdu-python-client 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| osdu_python_client-0.12.0.tar.gz | 396.0 kB | Without provenance | Details for osdu_python_client-0.12.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| osdu_python_client-0.12.0-py3-none-any.whl | Python 3 | none | any | Details for osdu_python_client-0.12.0-py3-none-any.whl |
Total release size: 1.5 MB
Release files / osdu_python_client-0.12.0.tar.gz
| Download URL | osdu_python_client-0.12.0.tar.gz |
|---|---|
| Size | 396.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
26e1eb6043beaf8a606a9e537038a50a9613436a71074a6ef2bc549fdc0fda75
|
|
BLAKE2b-256 checksum How to use checksums |
ec561e7179e14b4ea012552251589ee69d46ee74ec23310bb1d3dd3243d1b249
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / osdu_python_client-0.12.0-py3-none-any.whl
| Download URL | osdu_python_client-0.12.0-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ab4b892ce8a249399ad2d9abbb3af2ad9cd9bf2a0d03aebf4fef330b6a7be62
|
|
BLAKE2b-256 checksum How to use checksums |
b09f6b154df99985b59ab1ef81032cdd06b761c352a86562abe242b8d5e91b03
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for osdu-python-client 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.