added some type hints and override flags

james-rl · james-rl · commit 2a7fc17b8aae · 2025-12-05T15:40:40.000-08:00
diff --git a/README-SDK.md b/README-SDK.md
@@ -4,36 +4,34 @@ The `RunloopSDK` builds on top of the underlying REST client and provides a Pyth
 
 ## Table of Contents
 
-- [Runloop SDK – Python Object-Oriented Client](#runloop-sdk--python-object-oriented-client)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Quickstart (synchronous)](#quickstart-synchronous)
-  - [Quickstart (asynchronous)](#quickstart-asynchronous)
-  - [Core Concepts](#core-concepts)
-    - [RunloopSDK](#runloopsdk)
-    - [Available Resources](#available-resources)
-    - [Devbox](#devbox)
-      - [Command Execution](#command-execution)
-      - [Execution Management](#execution-management)
-      - [Execution Results](#execution-results)
-      - [Streaming Command Output](#streaming-command-output)
-      - [File Operations](#file-operations)
-      - [Network Operations](#network-operations)
-      - [Snapshot Operations](#snapshot-operations)
-      - [Devbox Lifecycle Management](#devbox-lifecycle-management)
-      - [Context Manager Support](#context-manager-support)
-    - [Blueprint](#blueprint)
-    - [Snapshot](#snapshot)
-    - [StorageObject](#storageobject)
-      - [Storage Object Upload Helpers](#storage-object-upload-helpers)
-    - [Mounting Storage Objects to Devboxes](#mounting-storage-objects-to-devboxes)
-  - [Accessing the Underlying REST Client](#accessing-the-underlying-rest-client)
-  - [Error Handling](#error-handling)
-  - [Advanced Configuration](#advanced-configuration)
-  - [Async Usage](#async-usage)
-  - [Polling Configuration](#polling-configuration)
-  - [Complete API Reference](#complete-api-reference)
-  - [Feedback](#feedback)
+- [Installation](#installation)
+- [Quickstart (synchronous)](#quickstart-synchronous)
+- [Quickstart (asynchronous)](#quickstart-asynchronous)
+- [Core Concepts](#core-concepts)
+  - [RunloopSDK](#runloopsdk)
+  - [Available Resources](#available-resources)
+  - [Devbox](#devbox)
+    - [Command Execution](#command-execution)
+    - [Execution Management](#execution-management)
+    - [Execution Results](#execution-results)
+    - [Streaming Command Output](#streaming-command-output)
+    - [File Operations](#file-operations)
+    - [Network Operations](#network-operations)
+    - [Snapshot Operations](#snapshot-operations)
+    - [Devbox Lifecycle Management](#devbox-lifecycle-management)
+    - [Context Manager Support](#context-manager-support)
+  - [Blueprint](#blueprint)
+  - [Snapshot](#snapshot)
+  - [StorageObject](#storageobject)
+    - [Storage Object Upload Helpers](#storage-object-upload-helpers)
+  - [Mounting Storage Objects to Devboxes](#mounting-storage-objects-to-devboxes)
+- [Accessing the Underlying REST Client](#accessing-the-underlying-rest-client)
+- [Error Handling](#error-handling)
+- [Advanced Configuration](#advanced-configuration)
+- [Async Usage](#async-usage)
+- [Polling Configuration](#polling-configuration)
+- [Complete API Reference](#complete-api-reference)
+- [Feedback](#feedback)
 
 ## Installation
 
@@ -447,7 +445,7 @@ shared_ctx_obj = runloop.storage_object.upload_from_bytes(
 
 blueprint_with_context = runloop.blueprint.create(
     name="my-blueprint-with-context",
-    dockerfile=\"\"\"\
+    dockerfile="""\
 FROM node:22
 WORKDIR /usr/src/app
 
@@ -460,7 +458,7 @@ COPY --from=shared / ./libs
 
 RUN npm install --only=production
 CMD ["node", "src/app.js"]
-\"\"\",
+""",
     # Primary build context
     build_context=build_ctx_obj.as_build_context(),
     # Additional named build contexts (for Docker buildx-style usage)
diff --git a/src/runloop_api_client/lib/_ignore.py b/src/runloop_api_client/lib/_ignore.py
@@ -5,6 +5,7 @@
 from typing import Iterable, Optional, Sequence
 from pathlib import Path, PurePosixPath
 from dataclasses import dataclass
+from typing_extensions import override
 
 __all__ = [
     "IgnorePattern",
@@ -320,6 +321,7 @@ class DockerIgnoreMatcher(IgnoreMatcher):
     extra_ignorefile: str | Path | None = None
     patterns: Sequence[str] | None = None
 
+    @override
     def iter_paths(self, root: Path) -> Iterable[Path]:
         """Yield non-ignored files under ``root`` honoring Docker-style patterns."""
         root = root.resolve()
@@ -380,6 +382,7 @@ def __post_init__(self) -> None:
         if isinstance(self.patterns, str):
             object.__setattr__(self, "patterns", [self.patterns])
 
+    @override
     def iter_paths(self, root: Path) -> Iterable[Path]:
         """Yield non-ignored files under ``root`` based only on ``patterns``."""
 
diff --git a/src/runloop_api_client/sdk/async_.py b/src/runloop_api_client/sdk/async_.py
@@ -421,7 +421,8 @@ async def upload_from_dir(
             for available options
         :return: Wrapper for the uploaded object
         :rtype: AsyncStorageObject
-        :raises OSError: If the local file cannot be read
+        :raises OSError: If the local directory cannot be read
+        :raises ValueError: If ``dir_path`` does not point to a directory
         """
         path = Path(dir_path)
         if not path.is_dir():
diff --git a/src/runloop_api_client/sdk/async_storage_object.py b/src/runloop_api_client/sdk/async_storage_object.py
@@ -151,8 +151,10 @@ async def delete(
     async def upload_content(self, content: str | bytes | Iterable[bytes]) -> None:
         """Upload content to the object's pre-signed URL.
 
-        :param content: Bytes or text payload to upload
-        :type content: str | bytes
+        :param content: Bytes payload, text payload, or an iterable streaming bytes
+        :type content: str | bytes | Iterable[bytes]
+        :return: None
+        :rtype: None
         :raises RuntimeError: If no upload URL is available
         :raises httpx.HTTPStatusError: Propagated from the underlying ``httpx`` client when the upload fails
         """
@@ -165,6 +167,9 @@ def as_build_context(self) -> BuildContext:
 
         The returned mapping can be passed directly to ``build_context`` or
         ``named_build_contexts`` when creating a blueprint.
+
+        :return: Mapping suitable for use as a blueprint build context
+        :rtype: BuildContext
         """
         return {
             "object_id": self._id,
diff --git a/src/runloop_api_client/sdk/storage_object.py b/src/runloop_api_client/sdk/storage_object.py
@@ -151,8 +151,10 @@ def delete(
     def upload_content(self, content: str | bytes | Iterable[bytes]) -> None:
         """Upload content to the object's pre-signed URL.
 
-        :param content: Bytes or text payload to upload
-        :type content: str | bytes
+        :param content: Bytes payload, text payload, or an iterable streaming bytes
+        :type content: str | bytes | Iterable[bytes]
+        :return: None
+        :rtype: None
         :raises RuntimeError: If no upload URL is available
         :raises httpx.HTTPStatusError: Propagated from the underlying ``httpx`` client when the upload fails
         """
@@ -165,6 +167,9 @@ def as_build_context(self) -> BuildContext:
 
         The returned mapping can be passed directly to ``build_context`` or
         ``named_build_contexts`` when creating a blueprint.
+
+        :return: Mapping suitable for use as a blueprint build context
+        :rtype: BuildContext
         """
         return {
             "object_id": self._id,
diff --git a/src/runloop_api_client/sdk/sync.py b/src/runloop_api_client/sdk/sync.py
@@ -83,7 +83,6 @@ def create_from_blueprint_id(
         :param blueprint_id: Blueprint ID to create from
         :type blueprint_id: str
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKDevboxCreateFromImageParams` for available parameters
-        :type params:
         :return: Wrapper bound to the newly created devbox
         :rtype: Devbox
         """
@@ -226,11 +225,10 @@ class BlueprintOps:
     Example:
         >>> from datetime import timedelta
         >>> from runloop_api_client.types.blueprint_build_parameters import BuildContext
-        >>> 
         >>> runloop = RunloopSDK()
         >>> obj = runloop.object_storage.upload_from_dir(
         ...     "./",
-        ...     ttl=timedelta(hours=1),    
+        ...     ttl=timedelta(hours=1),
         ... )
         >>> blueprint = runloop.blueprint.create(
         ...     name="my-blueprint",
@@ -421,6 +419,7 @@ def upload_from_dir(
         :return: Wrapper for the uploaded object
         :rtype: StorageObject
         :raises OSError: If the local file cannot be read
+        :raises ValueError: If ``dir_path`` does not point to a directory
         """
         path = Path(dir_path)
         if not path.is_dir():
@@ -545,7 +544,7 @@ def list(self, **params: Unpack[SDKScorerListParams]) -> list[Scorer]:
         page = self._client.scenarios.scorers.list(**params)
         return [Scorer(self._client, item.id) for item in page]
 
-    
+
 class AgentOps:
     """High-level manager for creating and managing agents.
 
@@ -555,15 +554,10 @@ class AgentOps:
     Example:
         >>> runloop = RunloopSDK()
         >>> # Create agent from NPM package
-        >>> agent = runloop.agent.create_from_npm(
-        ...     name="my-agent",
-        ...     package_name="@runloop/example-agent"
-        ... )
+        >>> agent = runloop.agent.create_from_npm(name="my-agent", package_name="@runloop/example-agent")
         >>> # Create agent from Git repository
         >>> agent = runloop.agent.create_from_git(
-        ...     name="git-agent",
-        ...     repository="https://github.com/user/agent-repo",
-        ...     ref="main"
+        ...     name="git-agent", repository="https://github.com/user/agent-repo", ref="main"
         ... )
         >>> # List all agents
         >>> agents = runloop.agent.list(limit=10)
@@ -605,9 +599,7 @@ def create_from_npm(
 
         Example:
             >>> agent = runloop.agent.create_from_npm(
-            ...     name="my-npm-agent",
-            ...     package_name="@runloop/example-agent",
-            ...     npm_version="^1.0.0"
+            ...     name="my-npm-agent", package_name="@runloop/example-agent", npm_version="^1.0.0"
             ... )
 
         :param package_name: NPM package name
@@ -624,7 +616,9 @@ def create_from_npm(
         :raises ValueError: If 'source' is provided in params
         """
         if "source" in params:
-            raise ValueError("Cannot specify 'source' when using create_from_npm(); source is automatically set to npm configuration")
+            raise ValueError(
+                "Cannot specify 'source' when using create_from_npm(); source is automatically set to npm configuration"
+            )
 
         npm_config: dict = {"package_name": package_name}
         if npm_version is not None:
@@ -652,9 +646,7 @@ def create_from_pip(
 
         Example:
             >>> agent = runloop.agent.create_from_pip(
-            ...     name="my-pip-agent",
-            ...     package_name="runloop-example-agent",
-            ...     pip_version=">=1.0.0"
+            ...     name="my-pip-agent", package_name="runloop-example-agent", pip_version=">=1.0.0"
             ... )
 
         :param package_name: Pip package name
@@ -671,7 +663,9 @@ def create_from_pip(
         :raises ValueError: If 'source' is provided in params
         """
         if "source" in params:
-            raise ValueError("Cannot specify 'source' when using create_from_pip(); source is automatically set to pip configuration")
+            raise ValueError(
+                "Cannot specify 'source' when using create_from_pip(); source is automatically set to pip configuration"
+            )
 
         pip_config: dict = {"package_name": package_name}
         if pip_version is not None:
@@ -701,7 +695,7 @@ def create_from_git(
             ...     name="my-git-agent",
             ...     repository="https://github.com/user/agent-repo",
             ...     ref="main",
-            ...     agent_setup=["npm install", "npm run build"]
+            ...     agent_setup=["npm install", "npm run build"],
             ... )
 
         :param repository: Git repository URL
@@ -716,7 +710,9 @@ def create_from_git(
         :raises ValueError: If 'source' is provided in params
         """
         if "source" in params:
-            raise ValueError("Cannot specify 'source' when using create_from_git(); source is automatically set to git configuration")
+            raise ValueError(
+                "Cannot specify 'source' when using create_from_git(); source is automatically set to git configuration"
+            )
 
         git_config: dict = {"repository": repository}
         if ref is not None:
@@ -743,9 +739,7 @@ def create_from_object(
             >>> obj = runloop.storage_object.upload_from_dir("./my-agent")
             >>> # Then create agent from the object
             >>> agent = runloop.agent.create_from_object(
-            ...     name="my-object-agent",
-            ...     object_id=obj.id,
-            ...     agent_setup=["chmod +x setup.sh", "./setup.sh"]
+            ...     name="my-object-agent", object_id=obj.id, agent_setup=["chmod +x setup.sh", "./setup.sh"]
             ... )
 
         :param object_id: Storage object ID
@@ -758,7 +752,9 @@ def create_from_object(
         :raises ValueError: If 'source' is provided in params
         """
         if "source" in params:
-            raise ValueError("Cannot specify 'source' when using create_from_object(); source is automatically set to object configuration")
+            raise ValueError(
+                "Cannot specify 'source' when using create_from_object(); source is automatically set to object configuration"
+            )
 
         object_config: dict = {"object_id": object_id}
         if agent_setup is not None:
