whitson-pvt-sdk

name	whitson-pvt-sdk
description	Install and use the Whitson PVT Python SDK from external Python projects. Use when configuring WhitsonPVTClient, authenticating with ClientCredentials, using v2 API resources, calling regions/wells/samples/projects/fluid models/black oil tables/reports, or working with the SDK's Pydantic request and response models.

Whitson PVT SDK

Install

Use Python 3.10 or newer.

uv add whitson-pvt-sdk

or:

pip install whitson-pvt-sdk

Create A Client

Import the public client and credential model:

from whitson_pvt_sdk import WhitsonPVTClient
from whitson_pvt_sdk.shared.models import ClientCredentials

client = WhitsonPVTClient(
    credentials=ClientCredentials(
        client_id="...",
        client_secret="...",
    ),
    base_url="https://internal.pvt.whitson.com",
)

The SDK defaults to version="v2". Do not pass version unless a different API version is explicitly needed. Use version="v1" only for legacy compatibility; v1 is deprecated and expected to be removed soon.

Authentication goes through the external API token endpoint by default. Do not pass provider-specific auth settings unless a non-standard deployment explicitly requires them.

Authentication is handled automatically. If a caller needs the same bearer token for a non-SDK integration, use the explicit helper:

token = client.get_access_token()

Do not use client.authentication; auth is not exposed as a resource.

Retries And Timeouts

The SDK retries transient read failures by default. GET requests and downloads retry 408, 429, 500, 502, 503, and 504. Mutating requests (POST, PUT, and multipart uploads) are not retried by default, except for HTTP 429 rate-limit responses. Token exchange follows the same retry timing and attempt policy.

Retry timing honors Retry-After, retry-after-ms, and X-RateLimit-Reset headers when present.

Configure retries and timeouts on WhitsonPVTClient:

from whitson_pvt_sdk import WhitsonPVTClient
from whitson_pvt_sdk.shared.models import ClientCredentials, RetryConfig

client = WhitsonPVTClient(
    credentials=ClientCredentials(client_id="...", client_secret="..."),
    base_url="https://internal.pvt.whitson.com",
    retry_config=RetryConfig(max_attempts=3),
    timeout=30.0,
    file_timeout=60.0,
)

Use RetryConfig(max_attempts=1) to disable retries. max_attempts includes the first request. RetryConfig.methods controls non-429 retries only; remove 429 from RetryConfig.statuses to disable all-method rate-limit retries. If all retries are exhausted on HTTP 429, the SDK raises RateLimitError with retry_after_seconds when retry timing headers are present.

Common Resource Calls

Access resources from the client:

regions = client.regions.list(limit=100)
region = client.regions.get(region_id=123)

wells = client.wells.list(region_id=123, limit=100)
well = client.wells.get(well_id=456)

samples = client.samples.list(well_id=456)
sample = client.samples.get(sample_id=789)

projects = client.projects.list(region_id=123, limit=100)
project = client.projects.get(project_id=321)

fluid_models = client.fluid_models.list(project_id=321, limit=100)
fluid_model = client.fluid_models.get(fluid_model_id=654)

black_oil_tables = client.black_oil_tables.list(fluid_model_id=654, limit=100)
black_oil_table = client.black_oil_tables.get(black_oil_table_id=987)

For paginated v2 list endpoints, use iterate() for lazy traversal or list_all() for eager collection. Pass limit=<int> to control page size.

Pagination

v2 list endpoints (regions, wells, projects, fluid models, black oil tables) return a pagination: PaginationMeta field with next_cursor and prev_cursor. Use the generated helpers for most callers:

for region in client.regions.iterate(limit=50):
    print(region.name)

all_wells = client.wells.list_all(region_id=123, limit=50)

When manual cursor control is needed, call list() directly and follow next_cursor:

page = client.regions.list(limit=50)
page2 = client.regions.list(cursor=page.pagination.next_cursor, limit=50)

Passing limit sets the page size (1–250). When omitted, the API default applies (usually 20).

Creating And Updating Data

Use generated Pydantic models from the selected API version for create and update requests.

from whitson_pvt_sdk.v2.models import CreateRegionModel, UpdateRegionModel

created = client.regions.create(
    CreateRegionModel(
        name="New region",
        region_type="asset",
        reservoir_type="Conventional",
    )
)
updated = client.regions.update(
    region_id=created.id,
    data=UpdateRegionModel(name="Renamed region"),
)

For legacy version="v1" usage, import request models from whitson_pvt_sdk.v1.models.

Use the SDK methods instead of manually constructing HTTP requests. Returned values are Pydantic response models, so callers can use normal attribute access and model_dump() when they need dictionaries.

Reports

Report export returns zip bytes and a synthetic filename:

archive_data, filename = client.reports.export(report_id=123)

Report import and preflight accept zip bytes. Pass ImportArchiveOptions when import options are needed:

from pathlib import Path

from whitson_pvt_sdk.shared.models import ImportArchiveOptions

archive_data = Path("archive.zip").read_bytes()

preflight = client.reports.preflight_import(
    archive_data,
    options=ImportArchiveOptions(region_id=123),
)

result = client.reports.import_archive(
    archive_data,
    options=ImportArchiveOptions(
        region_id=123,
        acknowledge_suggestions=True,
    ),
)