groundhog-hpc 0.5.5__tar.gz → 0.5.7__tar.gz

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/.gitignore

@@ -13,3 +13,4 @@ wheels/
 /CLAUDE.md
 /.DS_Store
 /.coverage
+/docs/plans/*.md

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: groundhog-hpc
-Version: 0.5.5
+Version: 0.5.7
 Summary: Iterative HPC function development. As many 'first tries' as you need.
 Author-email: Owen Price Skelly <OwenPriceSkelly@uchicago.edu>
 License: MIT
@@ -15,8 +15,8 @@ Requires-Dist: packaging>=24.0
 Requires-Dist: proxystore>=0.8.3
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
-Requires-Dist: tomli-w>=1.0.0
 Requires-Dist: tomli>=1.1.0; python_full_version < '3.11'
+Requires-Dist: tomlkit>=0.12.0
 Requires-Dist: typer>=0.16.1
 Requires-Dist: uv>=0.9.5
 Description-Content-Type: text/markdown
@@ -36,13 +36,19 @@ Groundhog automatically manages remote environments (powered by [uv](https://doc
 
 ```python
 # /// script
-# requires-python = ">=3.10"
-# dependencies = ["numpy"]
+# requires-python = ">=3.12,<3.13"
+# dependencies = [
+#     numpy,
+# ]
+#
+# [tool.hog.tutorial]  # Globus Compute Tutorial Endpoint
+# endpoint = "4b116d3c-1703-4f8f-9f6f-39921e5864df"
+#
 # ///
 
 import groundhog_hpc as hog
 
-@hog.function(endpoint="your-endpoint-id", account="your-account")
+@hog.function(endpoint='tutorial') # points to [tool.hog.tutorial] config
 def compute(x: int) -> int:
     import numpy as np
     return int(np.sum(range(x)))
@@ -57,4 +63,4 @@ Run with: `hog run myscript.py main`
 
 ---
 
-see also: [examples/README.md](./examples/README.md)
+see also: [examples](https://groundhog-hpc.readthedocs.io/en/latest/examples/)

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/README.md

@@ -13,13 +13,19 @@ Groundhog automatically manages remote environments (powered by [uv](https://doc
 
 ```python
 # /// script
-# requires-python = ">=3.10"
-# dependencies = ["numpy"]
+# requires-python = ">=3.12,<3.13"
+# dependencies = [
+#     numpy,
+# ]
+#
+# [tool.hog.tutorial]  # Globus Compute Tutorial Endpoint
+# endpoint = "4b116d3c-1703-4f8f-9f6f-39921e5864df"
+#
 # ///
 
 import groundhog_hpc as hog
 
-@hog.function(endpoint="your-endpoint-id", account="your-account")
+@hog.function(endpoint='tutorial') # points to [tool.hog.tutorial] config
 def compute(x: int) -> int:
     import numpy as np
     return int(np.sum(range(x)))
@@ -34,4 +40,4 @@ Run with: `hog run myscript.py main`
 
 ---
 
-see also: [examples/README.md](./examples/README.md)
+see also: [examples](https://groundhog-hpc.readthedocs.io/en/latest/examples/)

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
   "pydantic>=2.0.0",
   "rich>=13.0.0",
   "tomli>=1.1.0 ; python_full_version < '3.11'",
-  "tomli-w>=1.0.0",
+  "tomlkit>=0.12.0",
   "typer>=0.16.1",
   "uv>=0.9.5",
 ]
@@ -65,6 +65,12 @@ dev = [
   "ruff>=0.12.11",
   "ty>=0.0.1a21",
 ]
+docs = [
+  "mkdocs>=1.6.0",
+  "mkdocs-material>=9.5.0",
+  "mkdocstrings[python]>=0.26.0",
+  "click<=8.2.1",  # NOTE: can be changed to >=8.3.2 when released
+]
 
 
 [tool.ruff.lint]

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/src/groundhog_hpc/__init__.py

@@ -32,6 +32,7 @@ import os
 
 from groundhog_hpc.decorators import function, harness, method
 from groundhog_hpc.import_hook import install_import_hook
+from groundhog_hpc.logging import setup_logging
 from groundhog_hpc.utils import mark_import_safe
 
 try:
@@ -41,5 +42,8 @@ except importlib.metadata.PackageNotFoundError:
 
 __all__ = ["function", "harness", "method", "mark_import_safe", "__version__"]
 
+# Configure logging on import
+setup_logging()
+
 if not os.environ.get("GROUNDHOG_NO_IMPORT_HOOK"):
     install_import_hook()

groundhog_hpc-0.5.7/src/groundhog_hpc/app/add.py

@@ -0,0 +1,136 @@
+"""Add command for managing PEP 723 script dependencies."""
+
+import os
+import subprocess
+from pathlib import Path
+
+import typer
+import uv
+from rich.console import Console
+
+from groundhog_hpc.app.utils import (
+    normalize_python_version_with_uv,
+    update_requires_python,
+)
+from groundhog_hpc.configuration.endpoints import (
+    KNOWN_ENDPOINTS,
+    get_endpoint_schema_comments,
+    parse_endpoint_spec,
+)
+from groundhog_hpc.configuration.pep723 import add_endpoint_to_script
+from groundhog_hpc.logging import setup_logging
+
+console = Console()
+
+KNOWN_ENDPOINT_ALIASES = []
+for name in KNOWN_ENDPOINTS.keys():
+    KNOWN_ENDPOINT_ALIASES += [name]
+    KNOWN_ENDPOINT_ALIASES += [
+        f"{name}.{variant}" for variant in KNOWN_ENDPOINTS[name]["variants"].keys()
+    ]
+
+
+def add(
+    script: Path = typer.Argument(..., help="Path to the script to modify"),
+    packages: list[str] | None = typer.Argument(None, help="Packages to add"),
+    requirements: list[Path] | None = typer.Option(
+        None, "--requirements", "--requirement", "-r", help="Add dependencies from file"
+    ),
+    python: str | None = typer.Option(
+        None, "--python", "-p", help="Python version specifier"
+    ),
+    endpoints: list[str] = typer.Option(
+        [],
+        "--endpoint",
+        "-e",
+        help=(
+            "Add endpoint configuration (e.g., anvil, anvil.gpu, name:uuid). "
+            f"Known endpoints: {', '.join(KNOWN_ENDPOINT_ALIASES)}. Can specify multiple."
+        ),
+    ),
+    log_level: str = typer.Option(
+        None,
+        "--log-level",
+        help="Set logging level (DEBUG, INFO, WARNING, ERROR)\n\n[env: GROUNDHOG_LOG_LEVEL=]",
+    ),
+) -> None:
+    """Add dependencies or update Python version in a script's PEP 723 metadata."""
+    if log_level:
+        os.environ["GROUNDHOG_LOG_LEVEL"] = log_level.upper()
+        # Reconfigure logging with the new level
+        setup_logging()
+
+    if not script.exists():
+        console.print(f"[red]Error: Script '{script}' not found[/red]")
+        raise typer.Exit(1)
+
+    # handle --python flag separately
+    if python:
+        try:
+            normalized_python = normalize_python_version_with_uv(python)
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]{e.stderr.strip()}[/red]")
+            raise typer.Exit(1)
+
+        update_requires_python(script, normalized_python)
+        console.print(f"[green]Updated Python requirement in {script}[/green]")
+
+    packages, requirements = packages or [], requirements or []
+    if packages or requirements:
+        cmd = [f"{uv.find_uv_bin()}", "add", "--script", str(script)]
+        cmd += packages
+
+        for req_file in requirements:
+            cmd += ["-r", str(req_file)]
+
+        try:
+            subprocess.run(
+                cmd,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            console.print(f"[green]Added dependencies to {script}[/green]")
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]{e.stderr.strip()}[/red]")
+            raise typer.Exit(1)
+
+    # handle --endpoint flags
+    if endpoints:
+        content = script.read_text()
+        added_any = False
+
+        for endpoint_spec_str in endpoints:
+            try:
+                spec = parse_endpoint_spec(endpoint_spec_str)
+            except Exception as e:
+                console.print(f"[red]Error: {e}[/red]")
+                raise typer.Exit(1)
+
+            # Build config dict from the spec
+            endpoint_config = {"endpoint": spec.uuid, **spec.base_defaults}
+            variant_config = spec.variant_defaults if spec.variant else None
+
+            # Fetch schema comments if UUID is valid (not a TODO placeholder)
+            schema_comments = None
+            if not spec.uuid.startswith("TODO"):
+                schema_comments = get_endpoint_schema_comments(spec.uuid)
+
+            content, skip_msg = add_endpoint_to_script(
+                content,
+                endpoint_name=spec.name,
+                endpoint_config=endpoint_config,
+                variant_name=spec.variant,
+                variant_config=variant_config,
+                schema_comments=schema_comments,
+            )
+
+            if skip_msg:
+                console.print(f"[yellow]{skip_msg}[/yellow]")
+            else:
+                added_any = True
+
+        script.write_text(content)
+
+        if added_any:
+            console.print(f"[green]Added endpoint configuration to {script}[/green]")

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/src/groundhog_hpc/app/init.py

@@ -1,5 +1,6 @@
 """Init command for creating new Groundhog scripts."""
 
+import os
 import subprocess
 from pathlib import Path
 from typing import Optional
@@ -11,9 +12,15 @@ from rich.console import Console
 from groundhog_hpc.app.utils import normalize_python_version_with_uv
 from groundhog_hpc.configuration.endpoints import (
     KNOWN_ENDPOINTS,
-    fetch_and_format_endpoints,
+    get_endpoint_schema_comments,
+    parse_endpoint_spec,
 )
-from groundhog_hpc.configuration.pep723 import Pep723Metadata
+from groundhog_hpc.configuration.pep723 import (
+    Pep723Metadata,
+    add_endpoint_to_script,
+    remove_endpoint_from_script,
+)
+from groundhog_hpc.logging import setup_logging
 
 console = Console()
 
@@ -46,8 +53,18 @@ def init(
             "Can specify multiple."
         ),
     ),
+    log_level: str = typer.Option(
+        None,
+        "--log-level",
+        help="Set logging level (DEBUG, INFO, WARNING, ERROR)\n\n[env: GROUNDHOG_LOG_LEVEL=]",
+    ),
 ) -> None:
     """Create a new groundhog script with PEP 723 metadata and example code."""
+    if log_level:
+        os.environ["GROUNDHOG_LOG_LEVEL"] = log_level.upper()
+        # Reconfigure logging with the new level
+        setup_logging()
+
     if Path(filename).exists():
         console.print(f"[red]Error: {filename} already exists[/red]")
         raise typer.Exit(1)
@@ -67,32 +84,59 @@ def init(
     assert default_meta.tool and default_meta.tool.uv
     exclude_newer = default_meta.tool.uv.exclude_newer
 
-    # Fetch and format endpoint configurations if provided
-    endpoint_blocks = []
+    # Parse endpoint specs if provided
+    endpoint_specs = []
     if endpoints:
         try:
-            endpoint_blocks = fetch_and_format_endpoints(endpoints)
-            for endpoint in endpoint_blocks:
-                console.print(f"[green]✓[/green] Fetched schema for {endpoint.name}")
+            endpoint_specs = [parse_endpoint_spec(spec) for spec in endpoints]
         except Exception as e:
             console.print(f"[red]Error: {e}[/red]")
             raise typer.Exit(1)
 
+    # Determine endpoint name for decorator (first endpoint or placeholder)
+    first_endpoint_name = endpoint_specs[0].name if endpoint_specs else "my_endpoint"
+
+    # Render template (always includes my_endpoint placeholder)
     env = Environment(loader=PackageLoader("groundhog_hpc", "templates"))
     template = env.get_template("init_script.py.jinja")
     content = template.render(
         filename=filename,
         python=python,
         exclude_newer=exclude_newer,
-        endpoint_blocks=endpoint_blocks,
+        endpoint_name=first_endpoint_name,
     )
+
+    # If endpoints provided, replace placeholder with real endpoints
+    if endpoint_specs:
+        # Remove placeholder
+        content = remove_endpoint_from_script(content, "my_endpoint")
+
+        # Add each requested endpoint
+        for spec in endpoint_specs:
+            endpoint_config = {"endpoint": spec.uuid, **spec.base_defaults}
+            variant_config = spec.variant_defaults if spec.variant else None
+
+            # Fetch schema comments if UUID is valid (not a TODO placeholder)
+            schema_comments = None
+            if not spec.uuid.startswith("TODO"):
+                schema_comments = get_endpoint_schema_comments(spec.uuid)
+
+            content, _ = add_endpoint_to_script(
+                content,
+                endpoint_name=spec.name,
+                endpoint_config=endpoint_config,
+                variant_name=spec.variant,
+                variant_config=variant_config,
+                schema_comments=schema_comments,
+            )
+
     Path(filename).write_text(content)
 
     console.print(f"[green]✓[/green] Created {filename}")
-    if endpoint_blocks:
+    if endpoint_specs:
         console.print("\nNext steps:")
         console.print(
-            f"  1. Update fields in the \\[tool.hog.{endpoint_blocks[0].name}] block"
+            f"  1. Update fields in the \\[tool.hog.{endpoint_specs[0].name}] block"
         )
         console.print(f"  2. Run with: [bold]hog run {filename} main[/bold]")
     else:

groundhog_hpc-0.5.7/src/groundhog_hpc/app/remove.py

@@ -0,0 +1,112 @@
+"""Remove command for managing PEP 723 script dependencies."""
+
+import os
+import subprocess
+from pathlib import Path
+
+import typer
+import uv
+from rich.console import Console
+
+from groundhog_hpc.configuration.endpoints import KNOWN_ENDPOINTS
+from groundhog_hpc.configuration.pep723 import remove_endpoint_from_script
+from groundhog_hpc.logging import setup_logging
+
+console = Console()
+
+KNOWN_ENDPOINT_ALIASES = []
+for name in KNOWN_ENDPOINTS.keys():
+    KNOWN_ENDPOINT_ALIASES += [name]
+    KNOWN_ENDPOINT_ALIASES += [
+        f"{name}.{variant}" for variant in KNOWN_ENDPOINTS[name]["variants"].keys()
+    ]
+
+
+def remove(
+    script: Path = typer.Argument(..., help="Path to the script to modify"),
+    packages: list[str] | None = typer.Argument(None, help="Packages to remove"),
+    endpoints: list[str] = typer.Option(
+        [],
+        "--endpoint",
+        "-e",
+        help=(
+            "Remove endpoint or variant configuration (e.g., anvil, anvil.gpu, my_endpoint). "
+            f"Known endpoints: {', '.join(KNOWN_ENDPOINT_ALIASES)}. Can specify multiple. "
+            "Note: Removing a base endpoint (e.g., anvil) removes all its variants. "
+            "Removing a specific variant (e.g., anvil.gpu) leaves the base and other variants intact."
+        ),
+    ),
+    log_level: str = typer.Option(
+        None,
+        "--log-level",
+        help="Set logging level (DEBUG, INFO, WARNING, ERROR)\n\n[env: GROUNDHOG_LOG_LEVEL=]",
+    ),
+) -> None:
+    """Remove dependencies from a script's PEP 723 metadata."""
+    if log_level:
+        os.environ["GROUNDHOG_LOG_LEVEL"] = log_level.upper()
+        # Reconfigure logging with the new level
+        setup_logging()
+
+    # Validate script exists
+    if not script.exists():
+        console.print(f"[red]Error: Script '{script}' not found[/red]")
+        raise typer.Exit(1)
+
+    # Handle package removal
+    packages = packages or []
+    if packages:
+        # Shell out to uv
+        cmd = [f"{uv.find_uv_bin()}", "remove", "--script", str(script)]
+        cmd.extend(packages)
+
+        try:
+            subprocess.run(
+                cmd,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            console.print(f"[green]Removed packages from {script}[/green]")
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]{e.stderr.strip()}[/red]")
+            raise typer.Exit(1)
+
+    # Handle endpoint removal
+    if endpoints:
+        content = script.read_text()
+        removed_any = False
+
+        for endpoint_spec in endpoints:
+            # Parse endpoint spec to extract base name and optional variant
+            # Format can be: "name", "name.variant", or "name:uuid"
+            # Split by ':' first to handle "name:uuid" or "name.variant:uuid"
+            name_part = endpoint_spec.split(":")[0]
+
+            # Check if user specified a variant
+            if "." in name_part:
+                base_name, variant_name = name_part.split(".", 1)
+            else:
+                base_name = name_part
+                variant_name = None
+
+            original_content = content
+            content = remove_endpoint_from_script(content, base_name, variant_name)
+
+            if content != original_content:
+                removed_any = True
+            else:
+                if variant_name:
+                    console.print(
+                        f"[yellow]Variant '{base_name}.{variant_name}' not found in {script}[/yellow]"
+                    )
+                else:
+                    console.print(
+                        f"[yellow]Endpoint '{base_name}' not found in {script}[/yellow]"
+                    )
+
+        if removed_any:
+            script.write_text(content)
+            console.print(
+                f"[green]Removed endpoint configuration(s) from {script}[/green]"
+            )

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/src/groundhog_hpc/app/run.py

@@ -13,6 +13,7 @@ from groundhog_hpc.app.utils import (
 from groundhog_hpc.configuration.pep723 import read_pep723
 from groundhog_hpc.errors import RemoteExecutionError
 from groundhog_hpc.harness import Harness
+from groundhog_hpc.logging import setup_logging
 from groundhog_hpc.utils import (
     get_groundhog_version_spec,
     import_user_script,
@@ -32,11 +33,21 @@ def run(
         "--no-fun-allowed",
         help="Suppress emoji output\n\n[env: GROUNDHOG_NO_FUN_ALLOWED=]",
     ),
+    log_level: str = typer.Option(
+        None,
+        "--log-level",
+        help="Set logging level (DEBUG, INFO, WARNING, ERROR)\n\n[env: GROUNDHOG_LOG_LEVEL=]",
+    ),
 ) -> None:
     """Run a Python script on a Globus Compute endpoint."""
     if no_fun_allowed:
         os.environ["GROUNDHOG_NO_FUN_ALLOWED"] = str(no_fun_allowed)
 
+    if log_level:
+        os.environ["GROUNDHOG_LOG_LEVEL"] = log_level.upper()
+        # Reconfigure logging with the new level
+        setup_logging()
+
     script_path = script.resolve()
     if not script_path.exists():
         typer.echo(f"Error: Script '{script_path}' not found", err=True)
@@ -92,8 +103,9 @@ def run(
     except RemoteExecutionError as e:
         if e.returncode == 124:
             typer.echo(
-                "Remote execution failed (timed out - try "
-                "increasing walltime for long running jobs)",
+                "Remote execution failed: (exit code 124 - timed out). \nTry increasing walltime for "
+                "long running jobs by setting my_function.walltime (in seconds) "
+                "before invoking my_function.remote/submit()",
                 err=True,
             )
             raise

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/src/groundhog_hpc/compute.py

@@ -5,6 +5,7 @@ ShellFunctions, registering them, and submitting them for execution on remote
 endpoints.
 """
 
+import logging
 import os
 import warnings
 from functools import lru_cache
@@ -14,6 +15,8 @@ from uuid import UUID
 from groundhog_hpc.future import GroundhogFuture
 from groundhog_hpc.templating import template_shell_command
 
+logger = logging.getLogger(__name__)
+
 warnings.filterwarnings(
     "ignore",
     category=UserWarning,
@@ -44,7 +47,10 @@ def _get_compute_client() -> Client:
 
 
 def script_to_submittable(
-    script_path: str, function_name: str, payload: str
+    script_path: str,
+    function_name: str,
+    payload: str,
+    walltime: int | float | None = None,
 ) -> ShellFunction:
     """Convert a user script and function name into a Globus Compute ShellFunction.
 
@@ -52,6 +58,7 @@ def script_to_submittable(
         script_path: Path to the Python script containing the function
         function_name: Name of the function to execute remotely
         payload: Serialized arguments string
+        walltime: Optional maximum execution time in seconds for ShellFunction timeout
 
     Returns:
         A ShellFunction ready to be submitted to a Globus Compute executor
@@ -60,7 +67,7 @@ def script_to_submittable(
 
     shell_command = template_shell_command(script_path, function_name, payload)
     shell_function = gc.ShellFunction(
-        shell_command, name=function_name.replace(".", "_")
+        shell_command, name=function_name.replace(".", "_"), walltime=walltime
     )
     return shell_function
 
@@ -82,20 +89,27 @@ def submit_to_executor(
     """
     import globus_compute_sdk as gc
 
-    # Extract walltime and set it on the shell function
-    config = user_endpoint_config.copy()
-    if "walltime" in config:
-        shell_function.walltime = config.pop("walltime")
-
     # Validate config against endpoint schema and filter out unexpected keys
+    config = user_endpoint_config.copy()
     if schema := get_endpoint_schema(endpoint):
         expected_keys = set(schema.get("properties", {}).keys())
         unexpected_keys = set(config.keys()) - expected_keys
         if unexpected_keys:
+            logger.debug(
+                f"Filtering unexpected config keys for endpoint {endpoint}: {unexpected_keys}"
+            )
             config = {k: v for k, v in config.items() if k not in unexpected_keys}
 
+    logger.debug(f"Creating Globus Compute executor for endpoint {endpoint}")
     with gc.Executor(endpoint, user_endpoint_config=config) as executor:
+        func_name = getattr(
+            shell_function, "__name__", getattr(shell_function, "name", "unknown")
+        )
+        logger.info(f"Submitting function '{func_name}' to endpoint '{endpoint}'")
         future = executor.submit(shell_function)
+        task_id = getattr(future, "task_id", None)
+        if task_id:
+            logger.info(f"Task submitted with ID: {task_id}")
         deserializing_future = GroundhogFuture(future)
         return deserializing_future
 
@@ -114,7 +128,8 @@ def get_task_status(task_id: str | UUID | None) -> dict[str, Any]:
         return {"status": "status pending", "exception": None}
 
     client = _get_compute_client()
-    return client.get_task(task_id)
+    task_status = client.get_task(task_id)
+    return task_status
 
 
 @lru_cache

{groundhog_hpc-0.5.5 → groundhog_hpc-0.5.7}/src/groundhog_hpc/configuration/defaults.py

@@ -1,6 +1,7 @@
 # Default Globus Compute Executor configuration
 DEFAULT_USER_CONFIG = {
     "worker_init": "",
+    "endpoint_setup": "",
 }
 
 # default maximum execution time for remote functions (in seconds)