groundhog-hpc 0.5.5__py3-none-any.whl → 0.5.7__py3-none-any.whl

groundhog_hpc/logging.py

@@ -0,0 +1,51 @@
+"""Logging configuration for Groundhog HPC.
+
+This module provides centralized logging setup with support for:
+- Hierarchical per-module loggers (groundhog.compute, groundhog.serialization, etc.)
+- Environment variable configuration (GROUNDHOG_LOG_LEVEL)
+- CLI flag overrides
+- Remote log level propagation
+"""
+
+import logging
+import os
+import sys
+
+
+def setup_logging() -> None:
+    """Configure the root groundhog logger.
+
+    Reads log level from GROUNDHOG_LOG_LEVEL environment variable.
+    Defaults to WARNING if not set.
+
+    Valid log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+    Can be called multiple times to reconfigure the log level.
+    """
+    level_name = os.getenv("GROUNDHOG_LOG_LEVEL", "WARNING").upper()
+
+    # Convert string to logging level, default to WARNING if invalid
+    level = getattr(logging, level_name, logging.WARNING)
+
+    # Configure root groundhog logger
+    logger = logging.getLogger("groundhog_hpc")
+    logger.setLevel(level)
+
+    # Add stderr handler if not already present
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    else:
+        # Update level on existing handlers
+        for handler in logger.handlers:
+            handler.setLevel(level)
+
+    # Allow propagation to parent loggers (enables pytest caplog capture)
+    # This won't cause duplicate logs unless the root logger also has handlers,
+    # which is rare in production but common in tests
+    logger.propagate = True

groundhog_hpc/serialization.py

@@ -1,6 +1,7 @@
 import atexit
 import base64
 import json
+import logging
 import os
 import pickle
 import shutil
@@ -13,6 +14,8 @@ from proxystore.store import Store, get_store
 
 from groundhog_hpc.errors import DeserializationError, PayloadTooLargeError
 
+logger = logging.getLogger(__name__)
+
 # Globus Compute payload size limit (10 MB)
 PAYLOAD_SIZE_LIMIT_BYTES = 10 * 1024 * 1024
 
@@ -137,18 +140,29 @@ def serialize(
         >>> serialize(maybe_large_obj, proxy_threshold_mb=5)
     """
     if use_proxy:
+        logger.debug("Using ProxyStore for serialization (explicitly requested)")
         return _proxy_serialize(obj)
 
     payload = _direct_serialize(obj)
     payload_size = len(payload.encode("utf-8"))
     payload_size_mb = payload_size / (1024 * 1024)
 
+    logger.debug(f"Payload size: {payload_size_mb:.2f}MB")
+
     if proxy_threshold_mb is not None and payload_size_mb > proxy_threshold_mb:
+        logger.warning(
+            f"Payload size {payload_size_mb:.1f}MB exceeds threshold {proxy_threshold_mb}MB, "
+            f"using ProxyStore for efficient transfer"
+        )
         return _proxy_serialize(obj)
 
     if payload_size > size_limit_bytes:
+        logger.error(
+            f"Payload size {payload_size_mb:.2f}MB exceeds limit {size_limit_bytes / (1024 * 1024):.2f}MB"
+        )
         raise PayloadTooLargeError(payload_size_mb)
 
+    logger.debug(f"Using direct serialization for {payload_size_mb:.2f}MB payload")
     return payload
 
 
@@ -187,6 +201,7 @@ def deserialize_stdout(stdout: str) -> tuple[str | None, Any]:
     user_output = None
 
     try:
+        logger.debug("Starting deserialization of stdout")
         if delimiter in stdout:
             parts = stdout.split(delimiter, 1)
             user_output = parts[0].rstrip(
@@ -196,8 +211,13 @@ def deserialize_stdout(stdout: str) -> tuple[str | None, Any]:
                 "\n"
             )  # Remove leading newline from echo
 
-            return user_output, deserialize(serialized_result)
+            result = deserialize(serialized_result)
+            logger.debug("Successfully deserialized result from stdout")
+            return user_output, result
         else:
-            return None, deserialize(stdout)
+            result = deserialize(stdout)
+            logger.debug("Successfully deserialized result (no delimiter found)")
+            return None, result
     except Exception as e:
+        logger.error(f"Failed to deserialize result: {e}", exc_info=True)
         raise DeserializationError(user_output, e, stdout) from e

groundhog_hpc/templates/init_script.py.jinja

@@ -4,20 +4,18 @@
 #
 # [tool.uv]
 # exclude-newer = "{{ exclude_newer }}"
-# {% if endpoint_blocks %}{% for endpoint in endpoint_blocks %}
-{{ endpoint.toml_block }}
-# {% endfor %}{% else %}
+# python-preference = "managed"
+#
 # [tool.hog.my_endpoint]
 # endpoint = "TODO: Add Globus Compute endpoint UUID here"
 # # Uncomment and configure default options for "my_endpoint" here (available options vary by endpoint):
 # # account = "my-account"
 # # partition = "standard"
-# # walltime = 300 {% endif %}
 # ///
 
 import groundhog_hpc as hog
 
-@hog.function(endpoint="{{ endpoint_blocks[0].name if endpoint_blocks else 'my_endpoint' }}")
+@hog.function(endpoint="{{ endpoint_name }}")
 def hello_world(name: str = "World") -> str:
     """Example function that can be run remotely on your HPC cluster. """
     return f"Hello, {name}!"

groundhog_hpc/templates/shell_command.sh.jinja

@@ -1,5 +1,8 @@
 set -euo pipefail
 
+# Cleanup temporary files on exit
+trap 'rm -f {{ user_script_name }}.py {{ runner_name }}.py {{ script_name }}.in {{ script_name }}.out' EXIT
+
 if command -v uv &> /dev/null; then
     UV_BIN=$(command -v uv)
 else
@@ -30,6 +33,17 @@ fi
 mkdir -p "$UV_CACHE_DIR" "$UV_PYTHON_INSTALL_DIR"
 {% endraw %}
 
+# Propagate log level to remote environment
+{% if log_level %}
+# Local override - use value from dispatching environment
+export GROUNDHOG_LOG_LEVEL="{{ log_level }}"
+{% else %}
+{% raw %}
+# Respect remote environment if set, otherwise default to WARNING
+export GROUNDHOG_LOG_LEVEL="${{GROUNDHOG_LOG_LEVEL:-WARNING}}"
+{% endraw %}
+{% endif %}
+
 cat > {{ user_script_name }}.py << 'USER_SCRIPT_EOF'
 {{ user_script_contents | escape_braces }}
 USER_SCRIPT_EOF
@@ -42,7 +56,7 @@ cat > {{ script_name }}.in << 'PAYLOAD_EOF'
 {{ payload }}
 PAYLOAD_EOF
 
-"$UV_BIN" run --managed-python --with {{ version_spec }} \
+"$UV_BIN" run --with {{ version_spec }} \
   {{ runner_name }}.py
 
 echo "__GROUNDHOG_RESULT__"

groundhog_hpc/templating.py

@@ -7,6 +7,8 @@ user functions remotely. It creates shell commands that:
 3. Execute the runner with uv, which imports the user script, calls the function, and serializes results
 """
 
+import logging
+import os
 import uuid
 from hashlib import sha1
 from pathlib import Path
@@ -16,6 +18,8 @@ from jinja2 import Environment, FileSystemLoader
 from groundhog_hpc.configuration.pep723 import read_pep723, write_pep723
 from groundhog_hpc.utils import get_groundhog_version_spec, path_to_module_name
 
+logger = logging.getLogger(__name__)
+
 
 def escape_braces(text: str) -> str:
     """Escape curly braces for Globus Compute's .format() call.
@@ -44,6 +48,10 @@ def template_shell_command(script_path: str, function_name: str, payload: str) -
         A fully-formed shell command string ready to be executed via Globus
         Compute or local subprocess
     """
+    logger.debug(
+        f"Templating shell command for function '{function_name}' in script '{script_path}'"
+    )
+
     with open(script_path, "r") as f_in:
         user_script = f_in.read()
 
@@ -64,6 +72,7 @@ def template_shell_command(script_path: str, function_name: str, payload: str) -
     outfile_path = f"{script_name}.out"
 
     version_spec = get_groundhog_version_spec()
+    logger.debug(f"Using groundhog version spec: {version_spec}")
 
     # Load runner template
     templates_dir = Path(__file__).parent / "templates"
@@ -81,6 +90,11 @@ def template_shell_command(script_path: str, function_name: str, payload: str) -
         module_name=path_to_module_name(script_path),
     )
 
+    # Read local log level (None if not set)
+    local_log_level = os.getenv("GROUNDHOG_LOG_LEVEL")
+    if local_log_level:
+        logger.debug(f"Propagating log level to remote: {local_log_level}")
+
     # Render shell command
     shell_template = jinja_env.get_template("shell_command.sh.jinja")
     shell_command_string = shell_template.render(
@@ -91,8 +105,11 @@ def template_shell_command(script_path: str, function_name: str, payload: str) -
         script_name=script_name,
         version_spec=version_spec,
         payload=payload,
+        log_level=local_log_level,
     )
 
+    logger.debug(f"Generated shell command ({len(shell_command_string)} chars)")
+
     return shell_command_string
 
 

{groundhog_hpc-0.5.5.dist-info → groundhog_hpc-0.5.7.dist-info}/METADATA

@@ -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.7.dist-info/RECORD

@@ -0,0 +1,34 @@
+groundhog_hpc/__init__.py,sha256=BWOp2bKdV2Oz1Ubd89a-xF6XVEHqB9HZUaSk88T9o_Y,1513
+groundhog_hpc/compute.py,sha256=wQnjfYR4FSo2z2BJLVr99OIXz_AjRbiRy4-6qW0W2uE,4819
+groundhog_hpc/console.py,sha256=lipheM-NECkcqjK-ehzyD_zG-FzyJQrNT__4tGNFMr0,6941
+groundhog_hpc/decorators.py,sha256=XkP3Y2D6tX9KAxxY_P0A8L-zISuwXTupaP7MuSrt19Y,4714
+groundhog_hpc/errors.py,sha256=qDXuKYso6ZPIq64qsuBwL8yY27LGk9fe4rtvu1YlRtc,3933
+groundhog_hpc/function.py,sha256=H0wxI0sdMj6T8jpEW4yb5FUpXAr9Yow7HPCFk_NTaB4,14445
+groundhog_hpc/future.py,sha256=2_zNXAvIIurFwa9kcPW0cDL-W79sHSufIA1qaj1a9gU,7074
+groundhog_hpc/harness.py,sha256=7aCIHzvahwvNOj-vBnzOQ9TV9fpCNnoXiFCa6I3Dkkc,1427
+groundhog_hpc/import_hook.py,sha256=McNT9Lyppp3qriWITrlpCyd0WVJiQsizKM8EGT_VZPg,4241
+groundhog_hpc/logging.py,sha256=_SSI9jw5YYvFXZdIkWqr-P05WvWQ1fm2UPTuwqLh9dQ,1699
+groundhog_hpc/serialization.py,sha256=tbUY0d7mNoLGs_u4-ahyqvfK1kdkjBHli54hwiaLWlE,7642
+groundhog_hpc/templating.py,sha256=HnNQc-b72BcnsK8o7dZ4g5RUOI5XTRbJXeiExXGrgm4,4306
+groundhog_hpc/utils.py,sha256=ig7mEgmhf-JJ_LQq81yUtZzxstk27Ns2I2P-wC3QS5g,7611
+groundhog_hpc/app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundhog_hpc/app/add.py,sha256=zZW0eWnwRWJwpXL8V_Saaeb6X2D3G_y5ws19mDk0v3g,4534
+groundhog_hpc/app/init.py,sha256=7F6qbWJe6cEoAxLdWumqPDNrHHbqFHzSLpvHOXhQdMQ,5005
+groundhog_hpc/app/main.py,sha256=mZRraUNXHl-60r8UFh65lpJ9_7294QwSYZAXfu2IKYc,1146
+groundhog_hpc/app/remove.py,sha256=0BbUqGTy4Xj5PDegr6oAirdZc01GuYxv4CH4hYMRn-4,3872
+groundhog_hpc/app/run.py,sha256=p1EcUl7Ct6d40HRF814X5JmQU3q3PQ697l_oyO3GL6w,4030
+groundhog_hpc/app/utils.py,sha256=3XfES3Vp4l9m2JEmFeADdFXxTj5g1QMakbvaP3XLQP4,5434
+groundhog_hpc/configuration/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundhog_hpc/configuration/defaults.py,sha256=b6JMKI-1rt5u9XZU1APND7BZucIrG4AqIh8gat6hARo,218
+groundhog_hpc/configuration/endpoints.py,sha256=U03eYM5Vjw_HHbe8XnAV5smzzBlzvluRG2e8WNi8FG4,7304
+groundhog_hpc/configuration/models.py,sha256=5KL2NU1NdPycO6uLQQ7U1G-ljfD8CyuHesmj-DLSRyA,4791
+groundhog_hpc/configuration/pep723.py,sha256=TNbd2_UxOb_dMwtKcEJAJq62dC7SFdu_lt-D3m6Dx58,14488
+groundhog_hpc/configuration/resolver.py,sha256=VoYZ0S2X7BF6wOXz9NaxS71vqANYRsVi5pYT1B8fRAE,10326
+groundhog_hpc/templates/groundhog_run.py.jinja,sha256=-MwRi_k9LswYhi7pvnPwR-SzwBXvrugLofBc_-Yteuk,633
+groundhog_hpc/templates/init_script.py.jinja,sha256=O3-DkastzzpFl8XKsfI3EX3eM0fAsDqalPMCZHeULSE,1017
+groundhog_hpc/templates/shell_command.sh.jinja,sha256=CA_7XsLRzQc3xhQ6VcNt_sCRhKpyIQBXdgbZVa9Dtr4,1941
+groundhog_hpc-0.5.7.dist-info/METADATA,sha256=jEQNwFNXcotLHZUzvEUdzpS4tEBG-WScKFfMAJ-XCyM,2234
+groundhog_hpc-0.5.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+groundhog_hpc-0.5.7.dist-info/entry_points.txt,sha256=Dk9LTPJ-3vxm-sGsAaddEawPpIDzhM-ZVuyHKjzUCd0,51
+groundhog_hpc-0.5.7.dist-info/licenses/LICENSE,sha256=4WiSzz3h9qYXwc4sFWWFzc45ws_0HLZJmbT6_69IBjs,1078
+groundhog_hpc-0.5.7.dist-info/RECORD,,

groundhog_hpc-0.5.5.dist-info/RECORD

@@ -1,33 +0,0 @@
-groundhog_hpc/__init__.py,sha256=cWGAeK8kcXuA8Mo_LXTHM7qvoKQ7lCIk3KpkRmr9lVE,1418
-groundhog_hpc/compute.py,sha256=bcscRLKlMkC3RDTNMvSUFBR-ly9wRQUeLUqfvcTXmJM,4172
-groundhog_hpc/console.py,sha256=jzF7WAZofDzP0JVsF8Q0-SFuNxlIEa1lebhOsfBlpaI,6915
-groundhog_hpc/decorators.py,sha256=af9ExJz6YYvxlEM8UKKLcFFtHOSjoPQ64yILmaQ-06Q,4645
-groundhog_hpc/errors.py,sha256=qDXuKYso6ZPIq64qsuBwL8yY27LGk9fe4rtvu1YlRtc,3933
-groundhog_hpc/function.py,sha256=i_Pg_QmCeKq7QFOM_JfHtZuFIPfqcrDWzDG3-w42H6g,13182
-groundhog_hpc/future.py,sha256=NsspZQ0-v1i83Lq9aH3-GsLv-eapOxzgxNW5aBdQ5WM,5713
-groundhog_hpc/harness.py,sha256=7aCIHzvahwvNOj-vBnzOQ9TV9fpCNnoXiFCa6I3Dkkc,1427
-groundhog_hpc/import_hook.py,sha256=McNT9Lyppp3qriWITrlpCyd0WVJiQsizKM8EGT_VZPg,4241
-groundhog_hpc/serialization.py,sha256=pmcubvY5BhfHlXGHKeX8aXpywcJmSjHcIcaMlFuTdFs,6696
-groundhog_hpc/templating.py,sha256=gCYWSMmMAz9QUa92-bjNDXMJY4Q_K0qWvIMcy-sqCpw,3741
-groundhog_hpc/utils.py,sha256=ig7mEgmhf-JJ_LQq81yUtZzxstk27Ns2I2P-wC3QS5g,7611
-groundhog_hpc/app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-groundhog_hpc/app/add.py,sha256=Y5FVJopsnQaVUxbt1iLNWXOj2UbiriWKrP7E1urNReQ,2019
-groundhog_hpc/app/init.py,sha256=8R0_jDI2YDXija2SEsmg-NXrtDOrXHOJwE6w2rJI-pk,3462
-groundhog_hpc/app/main.py,sha256=mZRraUNXHl-60r8UFh65lpJ9_7294QwSYZAXfu2IKYc,1146
-groundhog_hpc/app/remove.py,sha256=6m0cmiebOycCrMcvoZiFyOvgRTNaa2mZxcCCrEqUd6I,1043
-groundhog_hpc/app/run.py,sha256=0sR9Eh42u-4JNo0sbFKXJXrWGywoXY9i80xoz5DvybY,3528
-groundhog_hpc/app/utils.py,sha256=3XfES3Vp4l9m2JEmFeADdFXxTj5g1QMakbvaP3XLQP4,5434
-groundhog_hpc/configuration/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-groundhog_hpc/configuration/defaults.py,sha256=OadDIrkJxYzns0Nd4x242wsahf2x3OJwuv9vNohcE08,192
-groundhog_hpc/configuration/endpoints.py,sha256=HFllc-RDrPjmiqi5AGWUgThUrIRsEpUHMQIUjVD1IRQ,12150
-groundhog_hpc/configuration/models.py,sha256=Xf4GvLmYBLwPnC1oO1s7ygCAjZyk_wjZFfen3UdzQNM,3452
-groundhog_hpc/configuration/pep723.py,sha256=VQVEMo_Z39y2x3W3cVLjPdcU19qrXbBxNsv3jgSMgVg,4360
-groundhog_hpc/configuration/resolver.py,sha256=Fyyk6ZarB_iWo1hHqRBjqWOzE1yrGTkR8OwdLl6ElMw,8660
-groundhog_hpc/templates/groundhog_run.py.jinja,sha256=-MwRi_k9LswYhi7pvnPwR-SzwBXvrugLofBc_-Yteuk,633
-groundhog_hpc/templates/init_script.py.jinja,sha256=vQtlup9SvOUhsCRHrieCb0GZpDnV0eZ_P-0ixyzv6i8,1177
-groundhog_hpc/templates/shell_command.sh.jinja,sha256=RBYj7m45MiYfNTwuzsVBm6PWziL0vtu7EXPXrSzXjVI,1473
-groundhog_hpc-0.5.5.dist-info/METADATA,sha256=xcThaPiPz6XoyJxrR1_-KI3qJkSOxCcMWzTx2TpIt9c,2071
-groundhog_hpc-0.5.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-groundhog_hpc-0.5.5.dist-info/entry_points.txt,sha256=Dk9LTPJ-3vxm-sGsAaddEawPpIDzhM-ZVuyHKjzUCd0,51
-groundhog_hpc-0.5.5.dist-info/licenses/LICENSE,sha256=4WiSzz3h9qYXwc4sFWWFzc45ws_0HLZJmbT6_69IBjs,1078
-groundhog_hpc-0.5.5.dist-info/RECORD,,