interloper-docker 0.72.0__tar.gz → 0.74.0__tar.gz

{interloper_docker-0.72.0 → interloper_docker-0.74.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: interloper-docker
-Version: 0.72.0
+Version: 0.74.0
 Summary: Interloper Docker integration
 Author: Guillaume Onfroy
 Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>

{interloper_docker-0.72.0 → interloper_docker-0.74.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "interloper-docker"
-version = "0.72.0"
+version = "0.74.0"
 description = "Interloper Docker integration"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,6 +34,7 @@ workspace = true
 line-length = 120
 
 [tool.ruff.lint]
+preview = true
 extend-select = [
     "E",
     "I",
@@ -41,8 +42,13 @@ extend-select = [
     "ANN001",
     "ANN201",
     "ANN202",
+    "DOC",
+    "D",
 ]
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = [
     "F401",
@@ -51,4 +57,8 @@ extend-select = [
 "tests/**" = [
     "ANN",
     "F811",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
 ]

{interloper_docker-0.72.0 → interloper_docker-0.74.0}/pyproject.toml.orig

@@ -3,7 +3,7 @@
 # ###############
 [project]
 name = "interloper-docker"
-version = "0.72.0"
+version = "0.74.0"
 description = "Interloper Docker integration"
 readme = "README.md"
 authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
@@ -31,8 +31,12 @@ interloper-scheduler = { workspace = true }
 line-length = 120
 
 [tool.ruff.lint]
-extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202"]
+preview = true
+extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202", "DOC", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401", "F403"]
-"tests/**" = ["ANN", "F811"]
+"tests/**" = ["ANN", "F811", "D101", "D102", "D103", "D104"]

{interloper_docker-0.72.0 → interloper_docker-0.74.0}/src/interloper_docker/launcher.py

@@ -53,6 +53,15 @@ class DockerLauncher(Launcher):
         environment; ``settings.config`` supplies the launcher-specific
         keyword arguments.
 
+        Args:
+            settings: The launcher settings block (image, network, volumes).
+            postgres: Postgres credentials forwarded into the spawned container.
+            runner: Runner settings the spawned process builds its runner from.
+            catalog: Catalog forwarded as import paths; required, since a container
+                cannot see the caller's.
+            store: Accepted for the registry's uniform hook and unused — a
+                container opens its own connection, not the caller's.
+
         Returns:
             The configured launcher.
 
@@ -165,12 +174,12 @@ class DockerLauncher(Launcher):
         container_name = f"interloper_run_{str(run_id)[:8]}"
         try:
             container = self._client.containers.get(container_name)
-        except Exception:
+        except Exception:  # noqa: BLE001 — any client error means the run is no longer observable
             return RunState(status=RunStatus.NOT_FOUND)
 
         try:
             container.reload()
-        except Exception:
+        except Exception:  # noqa: BLE001 — any client error means the run is no longer observable
             return RunState(status=RunStatus.NOT_FOUND)
 
         state = container.attrs.get("State", {}) if container.attrs else {}
@@ -197,7 +206,12 @@ class DockerLauncher(Launcher):
         return RunState(status=RunStatus.FAILED, error=" ".join(parts))
 
     def _build_environment(self) -> dict[str, str]:
-        """Build environment variables for the container."""
+        """Build environment variables for the container.
+
+        Returns:
+            The environment the run container is started with.
+
+        """
         environment: dict[str, str] = {
             "INTERLOPER_POSTGRES_HOST": self._postgres_host,
             "INTERLOPER_POSTGRES_PORT": str(self._postgres_port),

{interloper_docker-0.72.0 → interloper_docker-0.74.0}/src/interloper_docker/runner.py

@@ -82,7 +82,12 @@ class DockerRunner(SyncRunner):
     _container_map: dict[Future[Any], Container] = PrivateAttr(default_factory=dict)
 
     def model_post_init(self, context: Any) -> None:
-        """Initialize Docker client after model initialization."""
+        """Initialize Docker client after model initialization.
+
+        Args:
+            context: Pydantic's post-init context, unused.
+
+        """
         super().model_post_init(context)
         self._docker = docker.from_env()
 
@@ -90,7 +95,12 @@ class DockerRunner(SyncRunner):
 
     @property
     def _capacity(self) -> int:
-        """Maximum number of concurrent containers."""
+        """Maximum number of concurrent containers.
+
+        Returns:
+            The configured worker count.
+
+        """
         return self.max_containers
 
     def _on_start(self) -> None:
@@ -116,8 +126,16 @@ class DockerRunner(SyncRunner):
     ) -> Future[Any]:
         """Launch an asset in a Docker container and return a polling Future.
 
+        Args:
+            operation: The operation to run in its own container.
+            partition_or_window: The partition or window to materialize, when scoped.
+
         Returns:
             A Future that raises :class:`RunnerError` on container failure.
+
+        Raises:
+            RunnerError: If the container cannot be created.
+
         """
         if self._poll_pool is None:
             raise RunnerError("Poll pool not initialized")
@@ -146,7 +164,7 @@ class DockerRunner(SyncRunner):
                 stdout=True,
                 stderr=True,
             )
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001 — one operation's failure must not abort the run
             # Container never started — emit from the host
             self.state.mark_failed(operation, format_exception(e))
             done: Future[None] = Future()
@@ -170,6 +188,11 @@ class DockerRunner(SyncRunner):
         reporting one, the host's event is the only terminal, so the asset no
         longer orphans as ``running``.  Assets already terminal (e.g. marked
         failed during ``_submit_operation``) are skipped.
+
+        Args:
+            future: The polling future that has completed.
+            operation: The operation the container ran.
+
         """
         container = self._container_map.pop(future, None)
         if container is not None:
@@ -179,7 +202,7 @@ class DockerRunner(SyncRunner):
         if not (info and info.is_terminal):
             try:
                 future.result()
-            except Exception as e:
+            except Exception as e:  # noqa: BLE001 — one operation's failure must not abort the run
                 self.state.mark_failed(operation, format_exception(e), emit=True, exception=e)
             else:
                 self.state.mark_completed(operation, emit=True)
@@ -196,6 +219,11 @@ class DockerRunner(SyncRunner):
         Same host-authored-terminal contract as :meth:`_handle_completed`
         (``emit=True``, idempotent via deterministic ids) so an asset still
         in flight when the run aborts is not left orphaned as ``running``.
+
+        Args:
+            future: The polling future being flushed.
+            operation: The operation the container ran.
+
         """
         container = self._container_map.pop(future, None)
         if container is not None:
@@ -221,6 +249,9 @@ class DockerRunner(SyncRunner):
     def _poll_container(self, container: Container) -> None:
         """Block until the container exits; raise on failure.
 
+        Args:
+            container: The container to wait on.
+
         Raises:
             RunnerError: If the container exits with a non-zero code.
         """
@@ -238,7 +269,17 @@ class DockerRunner(SyncRunner):
         partition_or_window: Partition | PartitionWindow | None,
         run_id: str,
     ) -> list[str]:
-        """Build the CLI command for asset execution in a container."""
+        """Build the CLI command for asset execution in a container.
+
+        Args:
+            dag_spec: The serialized DAG the container reconstructs.
+            partition_or_window: The partition or window to materialize, when scoped.
+            run_id: The run the container reports against.
+
+        Returns:
+            The argv the container entrypoint is started with.
+
+        """
         cmd = [
             "interloper",
             "run",
@@ -263,14 +304,24 @@ class DockerRunner(SyncRunner):
         return cmd
 
     def _build_env(self) -> dict[str, str]:
-        """Build the environment variables for the container."""
+        """Build the environment variables for the container.
+
+        Returns:
+            The environment each operation container receives.
+
+        """
         env = dict(self.env_vars)
         env["INTERLOPER_EVENTS_TO_STDERR"] = "true"
         env.update(child_process_env())
         return env
 
     def _build_volumes(self) -> dict[str, dict[str, str]]:
-        """Build the volume mounts for the container."""
+        """Build the volume mounts for the container.
+
+        Returns:
+            The mounts keyed by host path, in docker-py's shape.
+
+        """
         volumes: dict[str, dict[str, str]] = {}
         if isinstance(self.volumes, dict):
             volumes.update(self.volumes)
@@ -281,7 +332,15 @@ class DockerRunner(SyncRunner):
         return volumes
 
     def _build_name(self, operation: Operation) -> str:
-        """Build the name for the container."""
+        """Build the name for the container.
+
+        Args:
+            operation: The operation the container runs.
+
+        Returns:
+            A container name unique to this operation and run.
+
+        """
         return f"interloper_run_{self.state.run_id[:8]}_{operation.id[:8]}"
 
     # -- Real-time event streaming (stderr) ------------------------------------
@@ -336,7 +395,12 @@ class DockerRunner(SyncRunner):
             self._log_threads[container.id] = thread
 
     def _stop_container_log_streaming(self, container: Container) -> None:
-        """Stop and clean up the log streaming thread for a container."""
+        """Stop and clean up the log streaming thread for a container.
+
+        Args:
+            container: The container whose log thread is stopped.
+
+        """
         if container.id is None:
             return
         thread = self._log_threads.pop(container.id, None)