Skip to main content

OSDU Python Client

SCM Compliance

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]'
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.11+ is required (tested on 3.11 through 3.15).

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

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 /data reads now send Accept: application/json by default (the server otherwise returns Parquet and JSON parsing fails). Use read_bulk_parquet for 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.

License

Ref. License Information

Metadata

Release files for osdu-python-client 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for osdu-python-client 0.14.0
File Size Uploaded Provenance Actions
osdu_python_client-0.14.0.tar.gz 395.8 kB Without provenance Details for osdu_python_client-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for osdu-python-client 0.14.0
File Interpreter ABI Platform Actions
osdu_python_client-0.14.0-py3-none-any.whl Python 3 none any Details for osdu_python_client-0.14.0-py3-none-any.whl

Total release size: 1.5 MB

Release files / osdu_python_client-0.14.0.tar.gz

Download URL osdu_python_client-0.14.0.tar.gz
Size 395.8 kB
Tags Source
SHA-256 checksum
How to use checksums
338a03a19b6742db3d85ef1cd5353b21b880ea98c314e9cb3e593783f2f0ea0b
BLAKE2b-256 checksum
How to use checksums
1ed05219570ff97ddfc8eee4b9326dc47aeb6fd8f862273bc58413d7bf870d37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.14.0-py3-none-any.whl

Download URL osdu_python_client-0.14.0-py3-none-any.whl
Size 1.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
db19e6c6ee2683773b9835e5c8215d8688360652009266394c1f7c9880f9c2b6
BLAKE2b-256 checksum
How to use checksums
9890361ddecda3aad7e396f2a96da622e9eff1184556c15e2312e26e73fa3701
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.14.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page