Imported from WhitsonAS/whitson-pvt-sdk (
AGENTS.md). Install upstream withnpx skills add WhitsonAS/whitson-pvt-sdk. Copyright stays with the author.
Agent Notes
Start by reading the relevant existing module before changing behavior. Keep edits narrow and aligned with nearby v1/v2 patterns.
Commands
- Setup:
uv sync; install the task runner withuv tool install rust-justifjustis missing. - Focused checks:
just lint,just ty,just build. just checkrunslint -> format -> ty; it is not read-only becauseformatrunsruff format whitson_pvt_sdk/.just allregenerates models, applies lint fixes/formatting, typechecks, then builds.
Tests
- Run the test suite with
just test; it executesuv run pytest tests/ -v. - Run coverage with
just test-cov; it executesuv run pytest tests/ -v --cov=whitson_pvt_sdk --cov-report=term-missing. - Prefer
just testover invoking pytest directly unless you are intentionally running a focused subset.
Codegen
- Treat
whitson_pvt_sdk/_generated/**andwhitson_pvt_sdk/{v1,v2}/models/__init__.pyas generated output. - Regenerate only when a live local API is available at
http://localhost:4000; usejust generate v1,just generate v2, orjust generate-all, which fetchhttp://localhost:4000/external/{version}/docs/openapi.json. - The repo-specific generator lives in
scripts/sdk_generator/. It runsruff check --fix --select I,F401andruff formaton rendered endpoint/resource files, so generated files should not require a second formatting pass. - Put hand-maintained shared models in
whitson_pvt_sdk/shared/models.py; avoid hand-editing generated files unless intentionally patching generated output when the API spec is unavailable. - Authentication is excluded from generated resources via
EXCLUDED_RESOURCES; keep auth as transport infrastructure, not asclient.authentication.
Architecture
- Public entrypoint is
WhitsonPVTClientinwhitson_pvt_sdk/__init__.py; it wiresv1orv2resources and exposesget_access_token()for explicit token reuse. HTTPTransportowns thebase_url.rstrip('/') + /external/{version}prefix, bearer auth, token caching, timeouts, conservative GET retries, retry timing from rate-limit headers, error mapping, JSON parsing, bytes downloads, and multipart uploads.- Public resource classes in
whitson_pvt_sdk/v1/resources.pyandv2/resources.pyusually re-export generated facades fromwhitson_pvt_sdk/_generated/{version}/resources.py; put manual SDK conveniences there by subclassing/wrapping generated classes. - Generated resource methods use SDK-shaped names (
list,get,create,update,create_bulk,update_bulk) while lower-level generated module functions keep OpenAPI operation IDs. - Keep v1/v2 behavior aligned unless generated models intentionally differ; v2 list endpoints use paginated models for regions/projects/fluid models/black oil tables/wells.
- Report import/export is special: export returns raw zip bytes plus a synthetic filename, and import/preflight upload
archive.zipwith optionalmeta_dataserialized fromImportArchiveOptions. - Configure retries and timeouts on
WhitsonPVTClient(...)withRetryConfig,timeout, andfile_timeout; default retries apply only toGET/downloads and retry408,429,500,502,503, and504.
Endpoint Wrappers
For new endpoint wrappers or generator behavior:
- Prefer changing
scripts/sdk_generator/and regenerating over hand-editing generated endpoint/resource files. - Call
HTTPTransport.get,post,put,get_bytes, orpost_multipart. - Serialize Pydantic inputs with
model_dump(exclude_unset=True). - Validate structured responses with the generated model's
model_validate. - Add or update the matching generated resource facade method through generator inference or
OVERRIDESwhen the endpoint exists in OpenAPI. - Keep v1 and v2 behavior aligned unless generated models intentionally differ.
For SDK-only conveniences or compatibility shims that are not OpenAPI-derived, add them to whitson_pvt_sdk/{version}/resources.py, not _generated/**.
Final Checks
Before finishing a change, run the narrowest applicable checks: just test, just lint, just ty, and/or just build.
Mention if a check was skipped because it would format, regenerate code, require the local API, or depend on missing tooling.
