kubetorch 0.2.0__py3-none-any.whl

kubetorch/docs/api/python/volumes.rst

@@ -0,0 +1,13 @@
+Volumes
+=======
+
+Kubetorch provides persistent storage through the ``Volume`` class, which abstracts Kubernetes PersistentVolumeClaims
+while maintaining the flexibility to work with any storage backend your cluster supports.
+
+Volume Class
+~~~~~~~~~~~~~~
+
+.. autoclass:: kubetorch.Volume
+   :members:
+
+    .. automethod:: __init__

kubetorch/docs/api/python.rst

@@ -0,0 +1,101 @@
+Python API
+==========
+
+The API Reference provides detailed information about the Kubetorch Python API and CLI commands.
+
+If you are just getting started with Kubetorch or looking for use cases and examples, we recommend first checking out:
+
+* `Guides <https://www.run.house/kubetorch/introduction>`_: quick start, high level concepts, developer guides, and more
+
+* `Examples <https://www.run.house/examples>`_: end-to-end examples using Kubetorch
+
+Compute
+-------
+
+The ``Compute`` class allows you to define the resources and environment needed for your workloads,
+while controlling how the compute is managed and scaled based on demand. This includes specifying
+hardware requirements that can be either generic or tailored to your specific Kubernetes infrastructure and setup.
+
+.. toctree::
+   :maxdepth: 1
+
+   python/compute
+
+Image
+------
+
+The ``Image`` class enables you to define and customize the containerized environment for your workloads.
+You can specify a pre-built Docker image as your foundation and layer on additional setup steps that run
+at launch time, eliminating the need to rebuild images for every code change.
+
+.. toctree::
+   :maxdepth: 1
+
+   python/image
+
+
+Module
+------
+
+The ``Fn`` and ``Cls`` classes are wrappers around your locally defined Python functions and classes, respectively.
+Once wrapped, these objects can be sent ``.to(compute)``, which launches a service on your cluster (taking into
+account the compute requirements) and syncs over the necessary files to run the function remotely.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   python/fn
+
+.. toctree::
+   :maxdepth: 1
+
+   python/cls
+
+
+App
+---
+
+The ``App`` class wraps a Python CLI command or script, enabling you to run entire applications remotely on the cluster.
+Unlike ``Fn`` and ``Cls`` which wrap individual functions or classes, ``App`` deploys and executes complete Python files
+with all their dependencies, making it ideal for training scripts, data processing pipelines, or even web applications.
+
+.. toctree::
+   :maxdepth: 1
+
+   python/app
+
+Secrets
+-------
+
+Secrets such as provider keys and environment variables can be set when defining compute. These are set at launch time
+and accessible during the scope of your program.
+
+.. toctree::
+   :maxdepth: 1
+
+   python/secret
+
+Config
+------
+
+Kubetorch uses a local configuration file (stored at ``~/.kt/config.yaml``) to allow you to set global defaults for
+your services. You can update the config file manually, use the ``kt config`` command, or set them as environment variables.
+You can also override defaults directly in the resource constructor for a specific service.
+
+.. toctree::
+   :maxdepth: 1
+
+   python/config
+
+Volumes
+-------
+
+The ``Volume`` class enables persistent storage for your workloads, allowing data to persist beyond individual pod lifecycles.
+Kubetorch automatically manages Kubernetes PersistentVolumeClaims (PVCs) while providing a simple Python interface for
+storage configuration.
+
+.. toctree::
+   :maxdepth: 1
+
+   python/volumes

kubetorch/docs/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath("../"))
+
+# -- Project information -----------------------------------------------------
+
+project = "Kubetorch"
+copyright = "Runhouse Inc"
+author = "the Runhouse team 🏃‍♀️🏠"
+
+# The full version, including alpha/beta/rc tags
+import kubetorch
+
+release = kubetorch.__version__
+
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "_ext.json_globaltoc",
+]
+
+autodoc_typehints_format = "short"
+autodoc_default_flags = ["members", "show-inheritance"]
+autodoc_member_order = "bysource"
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+markdown_http_base = "/docs/guide"
+markdown_anchor_sections = True
+
+if tags.has("json"):
+    # Force simpler output format (helps CLI output)
+    autodoc_typehints = "signature"  # "description"
+    napoleon_use_param = True
+    napoleon_use_rtype = True
+
+    html_link_suffix = ""
+    json_baseurl = "docs/"
+
+# -- Options for HTML output -------------------------------------------------
+
+if not tags.has("json"):
+    html_theme = "sphinx_book_theme"
+
+html_title = "Kubetorch"
+html_theme_options = {
+    "path_to_docs": "docs/",
+    "home_page_in_toc": True,
+}
+
+# -- Disable "View Source" links and code display ----------------------------
+
+html_show_sourcelink = False  # hides "View Source" link
+html_copy_source = False  # prevents .html files from containing source code

kubetorch/docs/index.rst

@@ -0,0 +1,20 @@
+Kubetorch API Reference
+=======================
+
+This document contains only API references.
+
+For further information and examples using Kubetorch, please refer to:
+
+* `Installation Guide <https://www.run.house/kubetorch/installation>`_: basic and advanced installation guides
+
+* `Developer Guide <https://www.run.house/kubetorch/introduction>`_: quick start, high level concepts,
+  developer guides, and more
+
+* `Examples <https://www.run.house/examples>`_: end-to-end examples using Kubetorch
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Reference
+
+   api/python
+   api/cli

kubetorch/docs/requirements.txt

@@ -0,0 +1,5 @@
+myst-parser==2.0.0
+sphinx==6.2.1
+sphinx_autodoc_typehints==1.17.0
+sphinx-book-theme==1.0.1
+sphinxcontrib-serializinghtml==1.1.5

kubetorch/globals.py

@@ -0,0 +1,285 @@
+import asyncio
+import atexit
+import os
+import signal
+import socket
+import subprocess
+import threading
+import time
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from kubetorch.config import KubetorchConfig
+from kubetorch.serving.constants import (
+    DEFAULT_NGINX_HEALTH_ENDPOINT,
+    DEFAULT_NGINX_PORT,
+    LOCAL_NGINX_PORT,
+    NGINX_GATEWAY_PROXY,
+)
+
+# For use in `kt deploy` decorators
+disable_decorators = False
+
+config = KubetorchConfig()
+
+
+@dataclass(frozen=True)
+class PFHandle:
+    process: subprocess.Popen
+    port: int
+    base_url: str  # "http://localhost:<port>"
+
+
+# cache a single pf per service (currently just a single NGINX proxy)
+_port_forwards: Dict[str, PFHandle] = {}
+# Use both a threading lock and an asyncio lock for different contexts
+_pf_lock = threading.Lock()
+# Async lock must be created lazily when event loop is available
+_pf_async_lock: Optional[asyncio.Lock] = None
+
+
+def _kill(proc: Optional[subprocess.Popen]) -> None:
+    if not proc:
+        return
+    try:
+        if proc.poll() is None:
+            os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+            proc.wait(timeout=3)
+    except Exception:
+        pass
+
+
+def _cleanup_port_forwards():
+    with _pf_lock:
+        for h in list(_port_forwards.values()):
+            _kill(h.process)
+        _port_forwards.clear()
+
+
+def _ensure_pf(
+    service_name: str, namespace: str, remote_port: int, health_endpoint: str
+) -> PFHandle:
+    from kubetorch.resources.compute.utils import find_available_port
+    from kubetorch.serving.utils import wait_for_port_forward
+
+    # Fast path: check without lock first
+    h = _port_forwards.get(service_name)
+    if h and h.process.poll() is None:
+        return h
+
+    # Slow path: need to create port forward
+    with _pf_lock:
+        # Double-check pattern: check again inside the lock
+        h = _port_forwards.get(service_name)
+        if h and h.process.poll() is None:
+            return h
+
+        # Now create the port forward while holding the lock
+        # This ensures only one thread creates the port forward
+        local_port = find_available_port(LOCAL_NGINX_PORT)
+
+        cmd = [
+            "kubectl",
+            "port-forward",
+            f"svc/{service_name}",
+            f"{local_port}:{remote_port}",
+            "--namespace",
+            namespace,
+        ]
+        proc = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, start_new_session=True
+        )
+
+        # If it dies immediately, surface stderr (much clearer than a generic timeout)
+        time.sleep(0.3)
+
+        if proc.poll() is not None:
+            err = (proc.stderr.read() or b"").decode(errors="ignore")
+            raise RuntimeError(
+                f"kubectl port-forward exited (rc={proc.returncode}): {err.strip()}"
+            )
+
+        if health_endpoint:
+            cluster_config = wait_for_port_forward(
+                proc, local_port, health_endpoint=health_endpoint
+            )
+            if isinstance(cluster_config, dict):
+                config.cluster_config = cluster_config
+                config.write()
+        else:
+            # Minimal TCP wait (no HTTP probe)
+            deadline = time.time() + 10
+            ok = False
+            while time.time() < deadline:
+                try:
+                    with socket.create_connection(
+                        ("127.0.0.1", local_port), timeout=0.5
+                    ):
+                        ok = True
+                        break
+                except OSError:
+                    time.sleep(0.1)
+            if not ok:
+                raise TimeoutError("Timeout waiting for port forward to be ready")
+
+        time.sleep(0.2)  # tiny grace
+
+        h = PFHandle(
+            process=proc, port=local_port, base_url=f"http://localhost:{local_port}"
+        )
+        # Store in cache while still holding the lock
+        _port_forwards[service_name] = h
+        return h
+
+
+async def _ensure_pf_async(
+    service_name: str, namespace: str, remote_port: int, health_endpoint: str
+) -> PFHandle:
+    """Async version of _ensure_pf for use in async contexts."""
+    from kubetorch.resources.compute.utils import find_available_port
+    from kubetorch.serving.utils import wait_for_port_forward
+
+    # Fast path: check without lock first
+    h = _port_forwards.get(service_name)
+    if h and h.process.poll() is None:
+        return h
+
+    # Ensure async lock is created (lazy initialization)
+    global _pf_async_lock
+    if _pf_async_lock is None:
+        _pf_async_lock = asyncio.Lock()
+
+    # Slow path: need to create port forward
+    async with _pf_async_lock:
+        # Double-check pattern: check again inside the lock
+        h = _port_forwards.get(service_name)
+        if h and h.process.poll() is None:
+            return h
+
+        # Create port forward in a thread to avoid blocking the event loop
+        def create_port_forward():
+            local_port = find_available_port(LOCAL_NGINX_PORT)
+
+            cmd = [
+                "kubectl",
+                "port-forward",
+                f"svc/{service_name}",
+                f"{local_port}:{remote_port}",
+                "--namespace",
+                namespace,
+            ]
+            proc = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                start_new_session=True,
+            )
+
+            # If it dies immediately, surface stderr
+            time.sleep(0.3)
+
+            if proc.poll() is not None:
+                err = (proc.stderr.read() or b"").decode(errors="ignore")
+                raise RuntimeError(
+                    f"kubectl port-forward exited (rc={proc.returncode}): {err.strip()}"
+                )
+
+            if health_endpoint:
+                wait_for_port_forward(proc, local_port, health_endpoint=health_endpoint)
+            else:
+                # Minimal TCP wait (no HTTP probe)
+                deadline = time.time() + 10
+                ok = False
+                while time.time() < deadline:
+                    try:
+                        with socket.create_connection(
+                            ("127.0.0.1", local_port), timeout=0.5
+                        ):
+                            ok = True
+                            break
+                    except OSError:
+                        time.sleep(0.1)
+                if not ok:
+                    raise TimeoutError("Timeout waiting for port forward to be ready")
+
+            time.sleep(0.2)  # tiny grace
+
+            return PFHandle(
+                process=proc, port=local_port, base_url=f"http://localhost:{local_port}"
+            )
+
+        # Run the blocking operation in a thread
+        loop = asyncio.get_event_loop()
+        h = await loop.run_in_executor(None, create_port_forward)
+
+        # Store in cache while still holding the lock
+        _port_forwards[service_name] = h
+        return h
+
+
+def service_url(
+    service_name: str = NGINX_GATEWAY_PROXY,
+    namespace: str = config.install_namespace,
+    remote_port: int = DEFAULT_NGINX_PORT,
+    health_endpoint: str = DEFAULT_NGINX_HEALTH_ENDPOINT,
+) -> str:
+    """
+    Return a URL to reach a Kubernetes Service.
+    - If running in-cluster:  {scheme}://{svc}.{ns}.svc.cluster.local:{remote_port}{path}
+    - Else: ensure a single kubectl port-forward (cached) and return http://localhost:<port>{path}
+    """
+    from kubetorch.servers.http.utils import is_running_in_kubernetes
+
+    if is_running_in_kubernetes():
+        return f"http://{service_name}.{namespace}.svc.cluster.local:{remote_port}"
+
+    # Ingress URL into the cluster from outside
+    if config.api_url:
+        return config.api_url
+
+    h = _ensure_pf(service_name, namespace, remote_port, health_endpoint)
+
+    # if the process died between creation and use, recreate once
+    if h.process.poll() is not None:
+        with _pf_lock:
+            _port_forwards.pop(service_name, None)
+        h = _ensure_pf(service_name, namespace, remote_port, health_endpoint)
+    return h.base_url
+
+
+async def service_url_async(
+    service_name: str = NGINX_GATEWAY_PROXY,
+    namespace: str = config.install_namespace,
+    remote_port: int = DEFAULT_NGINX_PORT,
+    health_endpoint: str = DEFAULT_NGINX_HEALTH_ENDPOINT,
+) -> str:
+    """
+    Async version of service_url for use in async contexts.
+    Return a URL to reach a Kubernetes Service.
+    - If running in-cluster:  {scheme}://{svc}.{ns}.svc.cluster.local:{remote_port}{path}
+    - Else: ensure a single kubectl port-forward (cached) and return http://localhost:<port>{path}
+    """
+    from kubetorch.servers.http.utils import is_running_in_kubernetes
+
+    if is_running_in_kubernetes():
+        return f"http://{service_name}.{namespace}.svc.cluster.local:{remote_port}"
+
+    h = await _ensure_pf_async(service_name, namespace, remote_port, health_endpoint)
+
+    # if the process died between creation and use, recreate once
+    if h.process.poll() is not None:
+        # Ensure async lock is created
+        global _pf_async_lock
+        if _pf_async_lock is None:
+            _pf_async_lock = asyncio.Lock()
+
+        async with _pf_async_lock:
+            _port_forwards.pop(service_name, None)
+        h = await _ensure_pf_async(
+            service_name, namespace, remote_port, health_endpoint
+        )
+    return h.base_url
+
+
+atexit.register(_cleanup_port_forwards)

kubetorch/logger.py

@@ -0,0 +1,59 @@
+import logging
+import os
+import sys
+
+
+def get_logger(name) -> logging.Logger:
+    """
+    Creates and returns a logger with the specified name.
+
+    Ensures a universal logger configuration across the codebase with the format:
+    "levelname - asctime - filename:lineno - message"
+
+    Args:
+        name (str): Name of the logger. Defaults to None, which gets the root logger.
+
+    Returns:
+        logging.Logger: Configured logger instance.
+    """
+    # Create or retrieve the logger
+    return logging.getLogger(name)
+
+
+class NewLineFormatter(logging.Formatter):
+    """Adds logging prefix to newlines to align multi-line messages."""
+
+    def __init__(self, fmt, datefmt=None):
+        logging.Formatter.__init__(self, fmt, datefmt)
+
+    def format(self, record):
+        msg = logging.Formatter.format(self, record)
+        if record.message != "":
+            parts = msg.partition(record.message)
+            msg = msg.replace("\n", "\r\n" + parts[0])
+        return msg
+
+
+root_logger = logging.getLogger("kubetorch")
+
+
+def init_logger(logger):
+    level = os.getenv("KT_LOG_LEVEL") or "INFO"
+    level = getattr(logging, level.upper())
+    logger.setLevel(level)
+    for handler in logger.handlers:
+        logger.removeHandler(handler)
+
+    if not logger.handlers:
+        formatter = NewLineFormatter(
+            "%(levelname)s | %(asctime)s | %(name)s:%(lineno)d | %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+    logger.propagate = False
+
+
+init_logger(root_logger)