feat(SDK): Build context helpers for the python clients and SDKs (#684)

* added context loader helper

* added context loader helper to make it easier to add build context when creating a blueprint

* added oop build context functional method wrapper

* added context helpers to SDKs

* made ctxt example a bit better

* made this example better

* refactored ignore logic to follow moby (docker project) pattern matching logic and tests

* fixed some tests and broken imports

* improved typing and made the ignore matching less docker-specific

* added tar filter for upload_from_dir

* fixed bad type

* removed some dead code and standardized the ignore interface & made it a bit more ergonomic

* rolled back change that made tar its own filter type -- big misunderstanding

* added handling for extremely weird edge case behavior for dockerignore

* added some type hints and override flags

* docstring fixes and consolidation of duplicated ignore code

Author: james-rl

README-SDK.md

@@ -8,11 +8,23 @@ The `RunloopSDK` builds on top of the underlying REST client and provides a Pyth
 - [Quickstart (synchronous)](#quickstart-synchronous)
 - [Quickstart (asynchronous)](#quickstart-asynchronous)
 - [Core Concepts](#core-concepts)
-- [Devbox](#devbox)
-- [Blueprint](#blueprint)
-- [Snapshot](#snapshot)
-- [StorageObject](#storageobject)
-- [Mounting Storage Objects to Devboxes](#mounting-storage-objects-to-devboxes)
+  - [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)
@@ -409,6 +421,52 @@ blueprint = runloop.blueprint.create(
     system_setup_commands=["pip install numpy pandas"],
 )
 
+# Or create a blueprint with a Docker build context from a local directory
+from pathlib import Path
+from runloop_api_client.lib.context_loader import build_docker_context_tar
+
+context_root = Path("./my-app")
+tar_bytes = build_docker_context_tar(context_root)
+
+build_ctx_obj = runloop.storage_object.upload_from_bytes(
+    data=tar_bytes,
+    name="my-app-context.tar.gz",
+    content_type="tgz",
+)
+
+shared_root = Path("./shared-lib")
+shared_tar = build_docker_context_tar(shared_root)
+
+shared_ctx_obj = runloop.storage_object.upload_from_bytes(
+    data=shared_tar,
+    name="shared-lib-context.tar.gz",
+    content_type="tgz",
+)
+
+blueprint_with_context = runloop.blueprint.create(
+    name="my-blueprint-with-context",
+    dockerfile="""\
+FROM node:22
+WORKDIR /usr/src/app
+
+# copy using the build context from the object
+COPY package.json package.json
+COPY src src
+
+# copy from named context
+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)
+    named_build_contexts={
+        "shared": shared_ctx_obj.as_build_context(),
+    },
+)
+
 # Or get an existing one
 blueprint = runloop.blueprint.from_id(blueprint_id="bpt_123")
 

src/runloop_api_client/lib/__init__.py

@@ -0,0 +1,3 @@
+"""
+Helpers for `runloop_api_client`.
+"""