improved typing and made the ignore matching less docker-specific

Author: james-rl

src/runloop_api_client/lib/_ignore.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
 import os
+from abc import ABC, abstractmethod
 from typing import Iterable, Optional, Sequence
 from pathlib import Path, PurePosixPath
 from dataclasses import dataclass
 
 __all__ = [
     "IgnorePattern",
+    "IgnoreMatcher",
+    "DockerIgnoreMatcher",
     "read_ignorefile",
     "compile_ignore",
     "path_match",
@@ -281,3 +284,61 @@ def iter_included_files(
             if is_ignored(rel_file, is_dir=False, patterns=patterns):
                 continue
             yield file_path
+
+
+class IgnoreMatcher(ABC):
+    """Abstract interface for ignore matchers like .dockerignore and .gitignore.
+
+    There is considerable variation for each ignore file format, so this interface
+    provides a minimal contract for supporting each format. Implementations are
+    responsible for interpreting any underlying ignore configuration (files, inline
+    patterns, etc.) and returning all files that should be included under a given
+    root directory.
+    """
+
+    @abstractmethod
+    def iter_paths(self, root: Path) -> Iterable[Path]:
+        """Yield filesystem paths to include under ``root``."""
+
+
+@dataclass(frozen=True)
+class DockerIgnoreMatcher(IgnoreMatcher):
+    """Ignore matcher that mirrors Docker's .dockerignore semantics.
+
+    This matcher:
+    - Closely follows Docker's .dockerignore semantics.
+    - Always loads patterns from ``.dockerignore`` in the provided context
+      root, if present.
+    - Optionally loads additional patterns from an extra ignorefile.
+    - Optionally appends inline pattern strings.
+
+    Note: Patterns follow Docker-style semantics (``!`` negation, ``**`` support).
+    """
+
+    extra_ignorefile: str | Path | None = None
+    patterns: Sequence[str] | None = None
+
+    def iter_paths(self, root: Path) -> Iterable[Path]:
+        """Yield non-ignored files under ``root`` honoring Docker-style patterns."""
+
+        root = root.resolve()
+
+        all_patterns: list[str] = []
+
+        # 1) Always consider .dockerignore under the context root, if present.
+        default_ignorefile = root / ".dockerignore"
+        all_patterns.extend(read_ignorefile(default_ignorefile))
+
+        # 2) Optional additional ignorefile.
+        if self.extra_ignorefile is not None:
+            ignore_path = Path(self.extra_ignorefile)
+            if not ignore_path.exists():
+                raise FileNotFoundError(f"Ignore file does not exist: {ignore_path}")
+            all_patterns.extend(read_ignorefile(ignore_path))
+
+        # 3) Optional inline patterns appended last.
+        if self.patterns:
+            all_patterns.extend(self.patterns)
+
+        compiled: list[IgnorePattern] = compile_ignore(all_patterns)
+        return iter_included_files(root, patterns=compiled)

src/runloop_api_client/lib/context_loader.py

@@ -5,54 +5,30 @@
 from typing import Iterable, Optional, Sequence
 from pathlib import Path
 
-from ._ignore import IgnorePattern, compile_ignore, read_ignorefile, iter_included_files
+from ._ignore import IgnoreMatcher, IgnorePattern, DockerIgnoreMatcher, iter_included_files
 
 
 def build_docker_context_tar(
     context_root: Path,
     *,
-    ignore: Optional[Sequence[str] | Path | str] = None,
+    ignore: Optional[IgnoreMatcher] = None,
 ) -> bytes:
-    """Create a .tar.gz of the build context, honoring ignore patterns.
+    """Create a .tar.gz of the build context, honoring Docker-style ignore patterns.
 
     - Treats ``context_root`` as the build context root.
     - Always loads ``.dockerignore`` under ``context_root`` if present.
-    - An optional ``ignore`` argument may be provided:
-
-      * If a :class:`pathlib.Path` or string is given, it is treated as an
-        additional ignorefile path whose patterns are appended after
-        ``.dockerignore``.
-      * If a sequence of strings is given, they are treated as inline patterns
-        appended after any file-derived patterns.
-
-    Patterns use Docker-style semantics with ``!`` negation and ``**`` support.
+    - An optional :class:`IgnoreMatcher` may be provided to customise how ignore
+      patterns are resolved; when omitted, :class:`DockerIgnoreMatcher` is used.
     """
 
     context_root = context_root.resolve()
 
-    all_patterns: list[str] = []
-
-    # 1) Always consider .dockerignore under the context root, if present.
-    default_ignorefile = context_root / ".dockerignore"
-    all_patterns.extend(read_ignorefile(default_ignorefile))
-
-    # 2) Optional additional ignore source
-    if ignore is not None:
-        if isinstance(ignore, (str, Path)):
-            ignore_path = Path(ignore)
-            if not ignore_path.exists():
-                raise FileNotFoundError(f"Ignore file does not exist: {ignore_path}")
-            all_patterns.extend(read_ignorefile(ignore_path))
-        else:
-            # Treat as a sequence of raw patterns
-            all_patterns.extend(list(ignore))
-
-    compiled: list[IgnorePattern] = compile_ignore(all_patterns)
+    matcher: IgnoreMatcher = ignore or DockerIgnoreMatcher()
 
     buf = io.BytesIO()
 
     with tarfile.open(mode="w:gz", fileobj=buf) as tf:
-        for path in _iter_build_context_files(context_root, patterns=compiled):
+        for path in matcher.iter_paths(context_root):
             rel = path.relative_to(context_root)
             tf.add(path, arcname=rel.as_posix())
 

src/runloop_api_client/sdk/_build_context.py

@@ -13,6 +13,7 @@
 from dataclasses import dataclass
 from typing_extensions import Protocol
 
+from ..lib._ignore import IgnoreMatcher
 from ..lib.context_loader import build_docker_context_tar
 from ..types.object_create_params import ContentType
 
@@ -47,7 +48,7 @@ def __call__(  # pragma: no cover - interface only
         context_root: Path,
         *,
         name: str | None = None,
-        ignore: str | Path | tuple[str, ...] | list[str] | None = None,
+        ignore: IgnoreMatcher | None = None,
     ) -> BuildContextArtifact:
         """Package the given directory into a tarball.
 
@@ -67,7 +68,7 @@ def default_build_context_strategy(
     context_root: Path,
     *,
     name: str | None = None,
-    ignore: str | Path | tuple[str, ...] | list[str] | None = None,
+    ignore: IgnoreMatcher | None = None,
 ) -> BuildContextArtifact:
     """Default implementation that wraps ``build_docker_context_tar``.
 

src/runloop_api_client/sdk/async_.py

@@ -24,6 +24,7 @@
 from .._types import Timeout, NotGiven, not_given
 from .._client import DEFAULT_MAX_RETRIES, AsyncRunloop
 from ._helpers import detect_content_type
+from ..lib._ignore import IgnoreMatcher
 from .async_devbox import AsyncDevbox
 from .async_snapshot import AsyncSnapshot
 from .async_blueprint import AsyncBlueprint
@@ -375,7 +376,7 @@ async def upload_from_dir(
         name: Optional[str] = None,
         metadata: Optional[Dict[str, str]] = None,
         ttl: Optional[timedelta] = None,
-        ignore: str | Path | Sequence[str] | None = None,
+        ignore: IgnoreMatcher | None = None,
         **options: Unpack[LongRequestOptions],
     ) -> AsyncStorageObject:
         """Create and upload an object from a local directory.
@@ -390,12 +391,11 @@ async def upload_from_dir(
         :type metadata: Optional[Dict[str, str]]
         :param ttl: Optional Time-To-Live, after which the object is automatically deleted
         :type ttl: Optional[timedelta]
-        :param ignore: Optional ignore configuration. If a string or :class:`Path`
-            is provided it is treated as the path to an additional ignorefile.
-            If a sequence of strings is provided, they are interpreted as inline
-            ignore patterns appended after patterns loaded from
-            ``.dockerignore`` under ``dir_path``.
-        :type ignore: Optional[str | Path | Sequence[str]]
+        :param ignore: Optional ignore matcher. When provided it controls which
+            files under ``dir_path`` are included in the archived build
+            context. When omitted, a default Docker-style matcher that honors
+            ``.dockerignore`` under ``dir_path`` is used.
+        :type ignore: Optional[IgnoreMatcher]
         :param options: See :typeddict:`~runloop_api_client.sdk._types.LongRequestOptions`
             for available options
         :return: Wrapper for the uploaded object

src/runloop_api_client/sdk/async_storage_object.py

@@ -8,6 +8,7 @@
 from ._types import BaseRequestOptions, LongRequestOptions, SDKObjectDownloadParams
 from .._client import AsyncRunloop
 from ..types.object_view import ObjectView
+from ..types.blueprint_create_params import BuildContext
 from ..types.object_download_url_view import ObjectDownloadURLView
 
 
@@ -159,10 +160,10 @@ async def upload_content(self, content: str | bytes | Iterable[bytes]) -> None:
         response = await self._client._client.put(url, content=content)
         response.raise_for_status()
 
-    def as_build_context(self) -> dict[str, str]:
+    def as_build_context(self) -> BuildContext:
         """Return this object in the shape expected for a Blueprint build context.
 
-        The returned dict can be passed directly to ``build_context`` or
+        The returned mapping can be passed directly to ``build_context`` or
         ``named_build_contexts`` when creating a blueprint.
         """
         return {

src/runloop_api_client/sdk/storage_object.py

@@ -8,6 +8,7 @@
 from ._types import BaseRequestOptions, LongRequestOptions, SDKObjectDownloadParams
 from .._client import Runloop
 from ..types.object_view import ObjectView
+from ..types.blueprint_create_params import BuildContext
 from ..types.object_download_url_view import ObjectDownloadURLView
 
 
@@ -159,10 +160,10 @@ def upload_content(self, content: str | bytes | Iterable[bytes]) -> None:
         response = self._client._client.put(url, content=content)
         response.raise_for_status()
 
-    def as_build_context(self) -> dict[str, str]:
+    def as_build_context(self) -> BuildContext:
         """Return this object in the shape expected for a Blueprint build context.
 
-        The returned dict can be passed directly to ``build_context`` or
+        The returned mapping can be passed directly to ``build_context`` or
         ``named_build_contexts`` when creating a blueprint.
         """
         return {

src/runloop_api_client/sdk/sync.py

@@ -26,6 +26,7 @@
 from ._helpers import detect_content_type
 from .snapshot import Snapshot
 from .blueprint import Blueprint
+from ..lib._ignore import IgnoreMatcher
 from .storage_object import StorageObject
 from ..lib.context_loader import build_docker_context_tar
 from ..types.object_create_params import ContentType
@@ -374,7 +375,7 @@ def upload_from_dir(
         name: Optional[str] = None,
         metadata: Optional[Dict[str, str]] = None,
         ttl: Optional[timedelta] = None,
-        ignore: str | Path | Sequence[str] | None = None,
+        ignore: IgnoreMatcher | None = None,
         **options: Unpack[LongRequestOptions],
     ) -> StorageObject:
         """Create and upload an object from a local directory.
@@ -389,12 +390,11 @@ def upload_from_dir(
         :type metadata: Optional[Dict[str, str]]
         :param ttl: Optional Time-To-Live, after which the object is automatically deleted
         :type ttl: Optional[timedelta]
-        :param ignore: Optional ignore configuration. If a string or :class:`pathlib.Path`
-            is provided it is treated as the path to an additional ignorefile.
-            If a sequence of strings is provided, they are interpreted as inline
-            ignore patterns appended after patterns loaded from
-            ``.dockerignore`` under ``dir_path``.
-        :type ignore: Optional[str | Path | Sequence[str]]
+        :param ignore: Optional ignore matcher. When provided it controls which
+            files under ``dir_path`` are included in the archived build
+            context. When omitted, a default Docker-style matcher that honors
+            ``.dockerignore`` under ``dir_path`` is used.
+        :type ignore: Optional[IgnoreMatcher]
         :param options: See :typeddict:`~runloop_api_client.sdk._types.LongRequestOptions`
             for available options
         :return: Wrapper for the uploaded object

tests/sdk/test_async_clients.py

@@ -25,6 +25,7 @@
     AsyncBlueprintOps,
     AsyncStorageObjectOps,
 )
+from runloop_api_client.lib._ignore import DockerIgnoreMatcher
 from runloop_api_client.lib.polling import PollingConfig
 
 
@@ -461,7 +462,8 @@ async def test_upload_from_dir_with_inline_ignore_patterns(
         mock_async_client._client = http_client
 
         client = AsyncStorageObjectOps(mock_async_client)
-        obj = await client.upload_from_dir(test_dir, ignore=["*.log", "build/"])
+        matcher = DockerIgnoreMatcher(patterns=["*.log", "build/"])
+        obj = await client.upload_from_dir(test_dir, ignore=matcher)
 
         assert isinstance(obj, AsyncStorageObject)
         uploaded_content = http_client.put.call_args[1]["content"]

tests/sdk/test_clients.py

@@ -25,6 +25,7 @@
     BlueprintOps,
     StorageObjectOps,
 )
+from runloop_api_client.lib._ignore import DockerIgnoreMatcher
 from runloop_api_client.lib.polling import PollingConfig
 
 
@@ -545,7 +546,8 @@ def test_upload_from_dir_with_extra_ignore_file(
         mock_client._client = http_client
 
         client = StorageObjectOps(mock_client)
-        obj = client.upload_from_dir(test_dir, ignore=extra_ignore)
+        matcher = DockerIgnoreMatcher(extra_ignorefile=extra_ignore)
+        obj = client.upload_from_dir(test_dir, ignore=matcher)
 
         assert isinstance(obj, StorageObject)
         uploaded_content = http_client.put.call_args[1]["content"]
@@ -577,7 +579,8 @@ def test_upload_from_dir_with_inline_ignore_patterns(
         mock_client._client = http_client
 
         client = StorageObjectOps(mock_client)
-        obj = client.upload_from_dir(test_dir, ignore=["*.log", "build/"])
+        matcher = DockerIgnoreMatcher(patterns=["*.log", "build/"])
+        obj = client.upload_from_dir(test_dir, ignore=matcher)
 
         assert isinstance(obj, StorageObject)
         uploaded_content = http_client.put.call_args[1]["content"]