Swagger Petstore - OpenAPI 3.0 Python SDK

This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about Swagger at https://swagger.io. In the third iteration of the pet store, we've switched to the design first approach! You can now help us improve the API whether it's by making changes to the definition itself or to the code. That way, with time, we can improve the API in general, and expose some of the new features in OAS3.

Some useful links:

• The Pet Store repository
• The source API definition for the Pet Store

Package octri_petstore · Version 1.0.27 · 29 operations

Installation

# In the consumer project
python -m pip install /path/to/generated-sdk

# After this version is published
python -m pip install octri_petstore==1.0.27

Quickstart

The example calls loginUser (GET /user/login), a low-friction operation that requires no request arguments.

import asyncio
import os

from octri_petstore import ClientConfig, ClientAuthConfig
from octri_petstore.sdk import SwaggerPetstoreOpenAPI30
from octri_petstore.client import OAuth2ManualToken


async def main() -> None:
    config = ClientConfig(
        base_url="https://petstore3.swagger.io/api/v3",
        auth=ClientAuthConfig(petstore_auth=OAuth2ManualToken(access_token=os.environ["API_TOKEN"])),
    )
    client = SwaggerPetstoreOpenAPI30(config)
    result = await client.user.login()
    print(result)


asyncio.run(main())

Authentication

Keep credentials outside source control. The quickstart reads them from the environment and the client applies them to every request.

Scheme	ClientAuthConfig field	Sent as
petstore_auth	petstore_auth	OAuth 2 access token
api_key	api_key	api_key in header

Client behavior

• Base URL: https://petstore3.swagger.io/api/v3.
• Transport: httpx.
• Timeout: 30,000 ms per attempt.
• Retries: up to 3 attempts for status codes 408, 425, 429, 500, 502, 503, 504, with 500–8,000 ms backoff.
• Idempotency: disabled.
• Error telemetry is disabled by default, even when a reporting endpoint is baked into the build. Consumers must opt in explicitly.
• Telemetry PII filtering is enabled by default: common credentials and direct identifiers are recursively replaced with [REDACTED] before reports are sent. Disable it only through the generated logging config's filterPii (or language-native equivalent) for a trusted private sink.

High-level operation methods return the typed response body directly. The low-level request layer returns an SdkResponse<T> envelope containing data, status, headers, request ID, latency, and attempt count.

Errors and response metadata

All failure paths use a small, predictable hierarchy:

Error	Meaning
SdkValidationError	A request argument failed an OpenAPI constraint before network I/O.
SdkHttpError	The server returned a non-2xx response.
SdkNetworkError	DNS, connection, TLS, or socket failure.
SdkTimeoutError	The configured per-attempt timeout elapsed.

HTTP errors expose status_code, the response body and headers, plus request_id when the server supplies one. Preserve the request ID in support logs; it is the fastest way to correlate a failed SDK call with server-side traces.

Project layout and API discovery

• Operation implementations are grouped under src/octri_petstore/methods/.
• 6 component models are split by API domain under src/octri_petstore/types/<domain>.py or types/<tag path>/models.py, re-exported by octri_petstore.types.
• Component schemas can choose a nested model folder with x-octri-sdk-tags: ["Billing/Invoices"]; the first tag owns the model and / creates nesting.
• sdk-manifest.json is the language-neutral public API index: operations, request/response modes, model properties, enum values, and generation settings.
• Public barrel/module exports are the compatibility boundary. Import public model names from those exports; internal domain filenames may evolve without changing model names.

Command-line client

This build includes the generated CLI. Run:

octri-petstore-cli --help

CLI commands cover operations whose arguments can be represented safely as command-line flags. Use the typed library for complex request bodies and streaming workflows.

Links

• Source repository
• Issue tracker
• API documentation
• Terms of service
• Apache 2.0

Local mock-server tests

Generated SDK includes schema-derived, zero-dependency mock server and network contract suite. Node.js 20+ required. Contract probes use authored response examples only; schema-synthesized routes remain available to the local server.

./scripts/mock --port 4010 starts server. ./scripts/test runs the mock contract suite, then native SDK tests. A zero-authored-example contract run succeeds with an explicit zero-test summary; mismatches in authored examples still fail.