run-yonder 0.1.0__tar.gz

run_yonder-0.1.0/.claude/worktrees/logo-icon-variants/README.rst

@@ -0,0 +1,244 @@
+.. image:: doc/assets/images/logo.svg
+   :alt: yonder
+   :align: center
+   :width: 380px
+
+|
+
+yonder
+======
+
+Run Python functions on container-backed runners via a decorator.
+Functions and their arguments are serialized with
+`cloudpickle <https://github.com/cloudpipe/cloudpickle>`_, shipped to the
+runner, executed there, and the result is shipped back.
+
+Install
+-------
+
+.. code:: bash
+
+    # core package
+    pip install -e .
+
+    # with the bundled Docker runner
+    pip install -e ".[docker]"
+
+    # with the bundled Kubernetes runner
+    pip install -e ".[k8s]"
+
+Quick start
+-----------
+
+.. code:: python
+
+    import yonder
+    from yonder import DockerRunner
+
+    # Existing image. If the image doesn't already have cloudpickle, set
+    # inject_cloudpickle=True to derive an image that does (cached across
+    # runs, keyed by the base image). `when=` is an optional zero-arg
+    # predicate that makes the runner a no-op (calls run locally) when it
+    # returns False — useful for "use the container only if the library
+    # isn't already installed on the host".
+    runnerA = DockerRunner(
+        image="url/to/image",
+        env={"ENV_VARA": "value"},
+        mounts={"/host/path": "/in/container"},
+        inject_cloudpickle=True,
+        when=lambda: liba_not_present(),
+    )
+
+    # Build from a Dockerfile (context defaults to the Dockerfile's directory).
+    runnerB = DockerRunner(
+        dockerfile="./docker/myimg.Dockerfile",
+        build_args={"VERSION": "1.2.3"},
+    )
+
+    # On-demand: fresh container per call instead of one long-lived container.
+    ephemeral = DockerRunner(image="url/to/image", on_demand=True)
+
+    # Attach to a container you manage outside yonder. yonder will start it
+    # if it's stopped, but never removes it on close.
+    external = DockerRunner(container="my-dev-container")
+
+    # Register them by name.
+    yonder.register({
+        "runnerA": runnerA,
+        "runnerB": runnerB,
+        "ephemeral": ephemeral,
+        "external": external,
+    })
+
+    # Decorate. Dispatch policy lives on the runner (via the runner's
+    # `when=`); the decorator just names the target.
+    @yonder.yonder(runner="runnerA")
+    def functionA(a, b):
+        return a + b
+
+    @yonder.yonder(runner="runnerB")
+    def functionB(a, b):
+        return a * b
+
+Lazy start by default
+~~~~~~~~~~~~~~~~~~~~~
+
+A registered runner is **not** built/started until it's actually needed.
+The first decorated call that targets a runner triggers its ``start()``
+(image build/pull, persistent container creation). Runners that are never
+called incur no cost.
+
+You can pre-warm explicitly when you'd rather pay startup cost up front:
+
+.. code:: python
+
+    runnerA.start()       # pre-warm a specific runner
+    yonder.wait()         # pre-warm every registered runner (parallel)
+
+Both are opt-in. On-demand runners always behave the same way — they spin
+up a fresh container per call regardless of pre-warming.
+
+Tear down
+~~~~~~~~~
+
+Tear down when done:
+
+.. code:: python
+
+    yonder.closeAll()
+    # or, per-runner:
+    runnerA.close()
+
+``DockerRunner`` is also a context manager:
+
+.. code:: python
+
+    with DockerRunner(image="python:3.11-slim") as r:
+        yonder.register({"tmp": r})
+        yonder.wait()
+        ...
+    # container removed on exit
+
+DockerRunner options
+--------------------
+
+.. code:: python
+
+    DockerRunner(
+        # Exactly one of these three is required:
+        image=None,          # use/pull an existing image; yonder creates the container
+        dockerfile=None,     # build an image locally first; yonder creates the container
+        container=None,      # attach to an existing container (managed outside yonder)
+
+        build_context=None,  # override the build context directory (dockerfile mode)
+        build_args=None,     # dict of Docker ARGs (dockerfile mode)
+
+        env=None,            # environment variables (image/dockerfile mode only)
+        mounts=None,         # {host_path: container_path} (image/dockerfile mode only)
+        on_demand=False,     # one-shot container per call (image/dockerfile mode only)
+        name=None,           # container/tag name (auto-generated if omitted)
+        inject_cloudpickle=False,  # derive `FROM image + RUN pip install cloudpickle`
+                                   # (image mode only; tagged by base-image hash so the
+                                   # docker layer cache makes re-runs cheap)
+        client=None,         # pre-built docker.DockerClient (else docker.from_env())
+    )
+
+K8sRunner
+---------
+
+Attach to an existing Kubernetes pod and exec into one of its containers.
+Pods are treated like externally-managed containers — yonder never creates
+or removes them.
+
+.. code:: python
+
+    from yonder import K8sRunner
+
+    # By pod name.
+    by_name = K8sRunner(
+        pod="my-pod-abc123",
+        namespace="default",
+        container="app",  # optional; defaults to the pod's first container
+    )
+
+    # By label selector — first Running pod that matches is used.
+    by_selector = K8sRunner(
+        selector="app=my-app,env=dev",
+        namespace="default",
+    )
+
+.. code:: python
+
+    K8sRunner(
+        # Exactly one of these two is required:
+        pod=None,            # attach by pod name
+        selector=None,       # attach by label selector
+
+        namespace="default", # pod namespace
+        container=None,      # container within the pod (default: first)
+        kubeconfig=None,     # kubeconfig path (else KUBECONFIG/~/.kube/config,
+                             # falling back to in-cluster config)
+        context=None,        # kubeconfig context
+        name=None,           # runner name (auto-derived if omitted)
+        api_client=None,     # pre-built kubernetes.client.ApiClient
+    )
+
+The target container must have ``python`` on ``PATH`` and ``cloudpickle``
+installed (same Python minor version as the host is strongly recommended).
+
+Architecture
+------------
+
+- **``Runner``** (``yonder.Runner``) — abstract base. Implementations hold
+  their own config and expose ``run(payload) -> bytes``, plus optional
+  ``start()`` / ``close()`` lifecycle hooks.
+- **``DockerRunner``** — default implementation; uses the
+  `Docker SDK for Python <https://docker-py.readthedocs.io/>`_. Supports
+  existing images, Dockerfile builds, and attaching to externally-managed
+  containers; persistent and on-demand modes.
+- **``K8sRunner``** — Kubernetes implementation; uses the
+  `Kubernetes Python client <https://github.com/kubernetes-client/python>`_
+  to exec into a pod selected by name or label selector.
+- **``YonderSession``** — process-wide name→runner registry. Populate with
+  ``yonder.register({...})``, bring everything online with
+  ``yonder.wait()``, tear everything down with ``yonder.closeAll()``.
+- **Decorator** — serializes ``(func, args, kwargs)`` with cloudpickle,
+  calls the named runner's ``run(payload)``, deserializes the envelope, and
+  either returns the value or re-raises the exception.
+
+Writing your own Runner
+-----------------------
+
+.. code:: python
+
+    from yonder import Runner, register
+
+    class MyRunner(Runner):
+        def __init__(self, **config):
+            ...
+
+        def start(self):
+            # eager init (build/pull image, warm container, etc.)
+            ...
+
+        def run(self, payload: bytes) -> bytes:
+            # send payload to your execution environment,
+            # return the cloudpickled envelope
+            ...
+
+        def close(self):
+            ...
+
+    register({"mine": MyRunner(...)})
+
+Container requirements
+----------------------
+
+Images used with ``DockerRunner`` must have:
+
+- ``python`` on ``PATH``
+- ``cloudpickle`` installed (``pip install cloudpickle``). If your base
+  image doesn't have it, pass ``inject_cloudpickle=True`` and yonder will
+  build a derived image that does (one-time, cached).
+- Ideally the same Python minor version as the host (cloudpickle pickles
+  function bytecode, which is not portable across CPython minor versions).

run_yonder-0.1.0/.claude/worktrees/logo-icon-variants/doc/README.rst

@@ -0,0 +1,4 @@
+Yonder
+======
+
+This is the documentation package for Yonder.

run_yonder-0.1.0/.claude/worktrees/logo-icon-variants/examples/basic/README.rst

@@ -0,0 +1,26 @@
+basic yonder example
+====================
+
+Builds a minimal image (``python:3.x-slim`` + ``cloudpickle``) and runs a
+single function either locally or inside the container.
+
+Run
+---
+
+From the repo root:
+
+.. code:: bash
+
+    pip install -e ".[docker]"
+
+    # local execution (runner.when() returns False, function runs in this process)
+    python examples/basic/main.py
+
+    # remote execution (function runs inside the freshly built container)
+    python examples/basic/main.py --remote
+
+    # crank up logging to see the build + start + exec steps
+    python examples/basic/main.py --remote --log-level DEBUG
+
+Compare the ``hostname`` / ``python`` lines between local and remote
+output to confirm the function actually ran in the container.

run_yonder-0.1.0/.claude/worktrees/logo-icon-variants/examples/rdkit/README.rst

@@ -0,0 +1,104 @@
+rdkit yonder example
+====================
+
+Demonstrates yonder's **reference mode**: a transport that ships the
+function as ``(module, qualname, args, kwargs)`` instead of cloudpickled
+bytecode, so host and container Python minor versions can differ.
+
+rdkit is the perfect case study. Its pip wheels stop at CPython 3.13, so
+a 3.14 host can't ship cloudpickled functions to a 3.13 rdkit container
+— the in-container unpickler errors with::
+
+    TypeError: code() takes at most 16 arguments (18 given)
+
+Reference mode just imports the module under the container's own Python;
+no bytecode crosses the wire.
+
+Layout
+------
+
+::
+
+    examples/rdkit/
+    ├── Dockerfile        python:3.13-slim + rdkit (+ cloudpickle, for the --try-cloudpickle path)
+    ├── main.py           script: configures the runner, calls the function
+    ├── tasks.py          module: defines molecule_properties at module scope
+    └── README.rst
+
+The function lives in `tasks.py <tasks.py>`_ (not `main.py <main.py>`_)
+because reference mode requires the function to be importable — it can't
+live inside ``main()`` and it can't live in ``__main__``.
+
+Run
+---
+
+From the repo root:
+
+.. code:: bash
+
+    pip install -e ".[docker]"
+
+    # reference mode (default): works regardless of host Python version
+    python examples/rdkit/main.py
+    python examples/rdkit/main.py --smiles "CCO"        # ethanol
+    python examples/rdkit/main.py --smiles "c1ccccc1"   # benzene
+
+    # cloudpickle mode: demonstrates the version-mismatch failure
+    python examples/rdkit/main.py --try-cloudpickle
+
+    # crank up logging to watch the build + start + exec steps
+    python examples/rdkit/main.py --log-level DEBUG
+
+``--try-cloudpickle`` builds the same image and runs the same function —
+the only difference is the runner's ``mode=``. On a host whose Python
+minor version doesn't match the container's (3.13), the cloudpickle path
+fails with a clear ``RuntimeError`` from yonder's pre-flight version
+check::
+
+    RuntimeError: Python minor version mismatch: container ... runs Python
+    3.13, host runs Python 3.14. cloudpickle pickles function bytecode,
+    which is not portable across CPython minor versions. Fix by running
+    yonder from a Python 3.13 venv on the host, or use/build an image whose
+    Python is 3.14.
+
+The reference-mode run succeeds on the same host with the same image.
+
+How reference mode works here
+-----------------------------
+
+1. `main.py <main.py>`_ configures the runner with ``mode="reference"``
+   and ``source_path="auto"``. The ``"auto"`` sentinel resolves to the
+   directory of the file that constructed the runner (here, the example
+   directory). That directory is mounted into the container at
+   ``/workspace/rdkit`` and prepended to ``PYTHONPATH``, so the
+   container can ``import tasks``.
+2. The host calls ``molecule_properties("CCO")``. The decorator sees the
+   runner is in reference mode, validates the function is at module
+   scope (it is — ``tasks.molecule_properties``), and sends a
+   stdlib-pickle payload of ``{"module": "tasks", "qualname":
+   "molecule_properties", "args": ..., "kwargs": ...}``.
+3. The container's bootstrap (still Python 3.13) installs a no-op
+   ``yonder`` shim (since yonder isn't pip-installed inside the rdkit
+   image), imports ``tasks``, resolves ``molecule_properties``, and
+   calls it. rdkit runs against the container's own Python 3.13 — no
+   cross-version bytecode anywhere.
+4. The result is ``pickle.dumps``-ed back over stdout and unpacked on
+   the host.
+
+When to use which mode
+----------------------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 50 50
+
+    * - Use cloudpickle (default)
+      - Use reference
+    * - Host and container Python versions match
+      - Versions can or must differ
+    * - You want to decorate inline functions inside ``main()``
+      - You can put the function at module scope
+    * - The function is a lambda, closure, or anything not importable
+      - The function is in an importable module
+    * - You want unsaved editor-buffer changes to ship
+      - OK with the container reading from disk

run_yonder-0.1.0/.claude/worktrees/logo-icon-variants/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yonder"
+version = "0.1.0"
+description = "Run Python functions inside containers via a decorator."
+readme = "README.rst"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Jason Berger", email = "berge472@gmail.com" }]
+keywords = ["container", "docker", "cloudpickle", "decorator", "remote-execution"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+]
+dependencies = [
+    "cloudpickle>=3.0",
+]
+
+[project.optional-dependencies]
+docker = [
+    "docker>=7.0",
+]
+k8s = [
+    "kubernetes>=28.0",
+]
+dev = [
+    "pytest>=7",
+    "ruff>=0.5",
+    "docker>=7.0",
+    "kubernetes>=28.0",
+]
+
+[project.urls]
+Source = "https://gitlab.com/berge472/yonder"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yonder"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/yonder", "README.rst", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "docker: integration test that requires a running Docker daemon",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

run_yonder-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/