Skip to content

WIP docs: added base api types to the type reference #689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jrvb-rl merged 4 commits into from
Nov 22, 2025
Merged

WIP docs: added base api types to the type reference #689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4ec63e9
Restructure type references to be clearer
sid-rl Nov 21, 2025
167b609
title underline formatting
sid-rl Nov 21, 2025
a1de3a8
Rename SDK's RequestOptions to BaseRequestOptions (avoid conflict wit…
sid-rl Nov 21, 2025
58c8f71
base api types in the type reference
sid-rl Nov 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/sdk/async/devbox.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,6 @@ The ``AsyncDevbox`` class provides asynchronous methods for managing and interac
.. automodule:: runloop_api_client.sdk.async_devbox
:members:

.. automodule:: runloop_api_client.sdk.protocols
:members: AsyncCommandInterface, AsyncFileInterface, AsyncNetworkInterface
:undoc-members:
3 changes: 3 additions & 0 deletions docs/sdk/sync/devbox.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,6 @@ The ``Devbox`` class provides synchronous methods for managing and interacting w
.. automodule:: runloop_api_client.sdk.devbox
:members:

.. automodule:: runloop_api_client.sdk.protocols
:members: CommandInterface, FileInterface, NetworkInterface
:undoc-members:
77 changes: 47 additions & 30 deletions docs/sdk/types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,21 @@
Type Reference
==============

This page documents all TypeDict parameter types used throughout the SDK.
The Runloop Python SDK uses TypeDict objects for configuration parameters to the various API calls. This page documents the TypeDict objects used throughout the SDK.

Core Request Options
Blueprint Parameters
--------------------

These TypeDicts define options for streaming, timeouts, polling, and other request configuration.

.. autotypeddict:: runloop_api_client.sdk._types.ExecuteStreamingCallbacks

.. autotypeddict:: runloop_api_client.sdk._types.RequestOptions

.. autotypeddict:: runloop_api_client.sdk._types.LongRequestOptions
These TypeDicts define parameters for blueprint creation and listing.

.. autotypeddict:: runloop_api_client.sdk._types.PollingRequestOptions
.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintCreateParams

.. autotypeddict:: runloop_api_client.sdk._types.LongPollingRequestOptions
.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintListParams

Devbox Parameters
-----------------

These TypeDicts define parameters for devbox creation, execution, file operations, network tunnels, and snapshots.
These TypeDicts define parameters for devbox creation, listing, and operations.

Creation Parameters
~~~~~~~~~~~~~~~~~~~
Expand All @@ -30,18 +24,18 @@ Creation Parameters

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxCreateFromImageParams

Execution Parameters
~~~~~~~~~~~~~~~~~~~~

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteParams

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteAsyncParams

Listing Parameters
~~~~~~~~~~~~~~~~~~

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxListParams

Command Execution Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteParams

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteAsyncParams

File Operation Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -54,14 +48,16 @@ File Operation Parameters
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxUploadFileParams

Network Tunnel Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxCreateTunnelParams

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxRemoveTunnelParams

Snapshot Parameters
~~~~~~~~~~~~~~~~~~~
-------------------

These TypeDicts define parameters for snapshot creation, listing, and updating.

.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxSnapshotDiskParams

Expand All @@ -71,15 +67,6 @@ Snapshot Parameters

.. autotypeddict:: runloop_api_client.sdk._types.SDKDiskSnapshotUpdateParams

Blueprint Parameters
--------------------

These TypeDicts define parameters for blueprint creation and listing.

.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintCreateParams

.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintListParams

Storage Object Parameters
-------------------------

Expand All @@ -90,3 +77,33 @@ These TypeDicts define parameters for storage object creation, listing, and down
.. autotypeddict:: runloop_api_client.sdk._types.SDKObjectListParams

.. autotypeddict:: runloop_api_client.sdk._types.SDKObjectDownloadParams

Core Request Options
--------------------

These TypeDicts define options for timeouts, idempotency, polling, and other low-level request configuration. All other TypeDicts in the SDK extend from one of these core types.

.. autotypeddict:: runloop_api_client.sdk._types.BaseRequestOptions

.. autotypeddict:: runloop_api_client.sdk._types.LongRequestOptions

.. autoclass:: runloop_api_client.sdk._types.PollingConfig
:members:
:undoc-members:

.. autotypeddict:: runloop_api_client.sdk._types.PollingRequestOptions

.. autotypeddict:: runloop_api_client.sdk._types.LongPollingRequestOptions

Base API Type Reference
-----------------------

.. automodule:: runloop_api_client.types.shared_params
:members:
:undoc-members:
:imported-members:

.. automodule:: runloop_api_client.types
:members:
:undoc-members:
:imported-members:
16 changes: 8 additions & 8 deletions src/runloop_api_client/sdk/_types.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ class ExecuteStreamingCallbacks(TypedDict, total=False):
"""Callback invoked for all log lines (both stdout and stderr)"""


class RequestOptions(TypedDict, total=False):
class BaseRequestOptions(TypedDict, total=False):
extra_headers: Optional[Headers]
"""Send extra headers"""

Expand All @@ -50,12 +50,12 @@ class RequestOptions(TypedDict, total=False):
"""Override the client-level default timeout for this request, in seconds"""


class LongRequestOptions(RequestOptions, total=False):
class LongRequestOptions(BaseRequestOptions, total=False):
idempotency_key: Optional[str]
"""Specify a custom idempotency key for this request"""


class PollingRequestOptions(RequestOptions, total=False):
class PollingRequestOptions(BaseRequestOptions, total=False):
polling_config: Optional[PollingConfig]
"""Configuration for polling behavior"""

Expand All @@ -80,7 +80,7 @@ class SDKDevboxExecuteAsyncParams(DevboxExecuteAsyncParams, ExecuteStreamingCall
pass


class SDKDevboxListParams(DevboxListParams, RequestOptions):
class SDKDevboxListParams(DevboxListParams, BaseRequestOptions):
pass


Expand Down Expand Up @@ -116,7 +116,7 @@ class SDKDevboxSnapshotDiskParams(DevboxSnapshotDiskParams, LongPollingRequestOp
pass


class SDKDiskSnapshotListParams(DiskSnapshotListParams, RequestOptions):
class SDKDiskSnapshotListParams(DiskSnapshotListParams, BaseRequestOptions):
pass


Expand All @@ -128,17 +128,17 @@ class SDKBlueprintCreateParams(BlueprintCreateParams, LongPollingRequestOptions)
pass


class SDKBlueprintListParams(BlueprintListParams, RequestOptions):
class SDKBlueprintListParams(BlueprintListParams, BaseRequestOptions):
pass


class SDKObjectListParams(ObjectListParams, RequestOptions):
class SDKObjectListParams(ObjectListParams, BaseRequestOptions):
pass


class SDKObjectCreateParams(ObjectCreateParams, LongRequestOptions):
pass


class SDKObjectDownloadParams(ObjectDownloadParams, RequestOptions):
class SDKObjectDownloadParams(ObjectDownloadParams, BaseRequestOptions):
pass
6 changes: 3 additions & 3 deletions src/runloop_api_client/sdk/async_blueprint.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
from typing_extensions import Unpack, override

from ..types import BlueprintView
from ._types import RequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
from ._types import BaseRequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
from .._client import AsyncRunloop
from .async_devbox import AsyncDevbox
from ..types.blueprint_build_logs_list_view import BlueprintBuildLogsListView
Expand Down Expand Up @@ -44,7 +44,7 @@ def id(self) -> str:

async def get_info(
self,
**options: Unpack[RequestOptions],
**options: Unpack[BaseRequestOptions],
) -> BlueprintView:
"""Retrieve the latest blueprint details.

Expand All @@ -59,7 +59,7 @@ async def get_info(

async def logs(
self,
**options: Unpack[RequestOptions],
**options: Unpack[BaseRequestOptions],
) -> BlueprintBuildLogsListView:
"""Retrieve build logs for the blueprint.

Expand Down
4 changes: 2 additions & 2 deletions src/runloop_api_client/sdk/async_devbox.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
)
from ._types import (
LogCallback,
RequestOptions,
BaseRequestOptions,
LongRequestOptions,
PollingRequestOptions,
SDKDevboxExecuteParams,
Expand Down Expand Up @@ -104,7 +104,7 @@ def id(self) -> str:

async def get_info(
self,
**options: Unpack[RequestOptions],
**options: Unpack[BaseRequestOptions],
) -> DevboxView:
"""Retrieve current devbox status and metadata.

Expand Down
4 changes: 2 additions & 2 deletions src/runloop_api_client/sdk/async_execution.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
from typing import Optional, Awaitable, cast
from typing_extensions import Unpack, override

from ._types import RequestOptions, LongRequestOptions
from ._types import BaseRequestOptions, LongRequestOptions
from .._client import AsyncRunloop
from .async_execution_result import AsyncExecutionResult
from ..types.devbox_async_execution_detail_view import DevboxAsyncExecutionDetailView
Expand Down Expand Up @@ -119,7 +119,7 @@ async def result(self, **options: Unpack[LongRequestOptions]) -> AsyncExecutionR
final = cast(DevboxAsyncExecutionDetailView, command_result)
return AsyncExecutionResult(self._client, self._devbox_id, final)

async def get_state(self, **options: Unpack[RequestOptions]) -> DevboxAsyncExecutionDetailView:
async def get_state(self, **options: Unpack[BaseRequestOptions]) -> DevboxAsyncExecutionDetailView:
"""Fetch the latest execution state.

:param options: Optional request configuration
Expand Down
4 changes: 2 additions & 2 deletions src/runloop_api_client/sdk/async_snapshot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
from typing_extensions import Unpack, override

from ._types import (
RequestOptions,
BaseRequestOptions,
LongRequestOptions,
PollingRequestOptions,
SDKDiskSnapshotUpdateParams,
Expand Down Expand Up @@ -50,7 +50,7 @@ def id(self) -> str:

async def get_info(
self,
**options: Unpack[RequestOptions],
**options: Unpack[BaseRequestOptions],
) -> DevboxSnapshotAsyncStatusView:
"""Retrieve the latest snapshot status.

Expand Down
4 changes: 2 additions & 2 deletions src/runloop_api_client/sdk/async_storage_object.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
from typing import Iterable
from typing_extensions import Unpack, override

from ._types import RequestOptions, LongRequestOptions, SDKObjectDownloadParams
from ._types import BaseRequestOptions, LongRequestOptions, SDKObjectDownloadParams
from .._client import AsyncRunloop
from ..types.object_view import ObjectView
from ..types.object_download_url_view import ObjectDownloadURLView
Expand Down Expand Up @@ -52,7 +52,7 @@ def upload_url(self) -> str | None:

async def refresh(
self,
**options: Unpack[RequestOptions],
**options: Unpack[BaseRequestOptions],
) -> ObjectView:
"""Fetch the latest metadata for the object.

Expand Down
6 changes: 3 additions & 3 deletions src/runloop_api_client/sdk/blueprint.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
from typing_extensions import Unpack, override

from ..types import BlueprintView
from ._types import RequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
from ._types import BaseRequestOptions, LongRequestOptions, SDKDevboxCreateFromImageParams
from .devbox import Devbox
from .._client import Runloop
from ..types.blueprint_build_logs_list_view import BlueprintBuildLogsListView
Expand Down Expand Up @@ -44,7 +44,7 @@ def id(self) -> str:

def get_info(
self,
**options: Unpack[RequestOptions],
**options: Unpack[BaseRequestOptions],
) -> BlueprintView:
"""Retrieve the latest blueprint details.

Expand All @@ -59,7 +59,7 @@ def get_info(

def logs(
self,
**options: Unpack[RequestOptions],
**options: Unpack[BaseRequestOptions],
) -> BlueprintBuildLogsListView:
"""Retrieve build logs for the blueprint.

Expand Down
Loading