powerfunc 0.3.0__tar.gz → 0.5.0__tar.gz

{powerfunc-0.3.0 → powerfunc-0.5.0}/.github/workflows/ci.yml

@@ -47,6 +47,14 @@ jobs:
           GCP_BUCKET: gs://powerfunc-temporary-348293
           GCP_REGION: europe-west4
         run: uvx --with tox-uv tox run -e gcp
+      # Runs even when the tests fail or the run is cancelled, so a killed test
+      # cannot leave a job (and its GPU quota) running behind later runs.
+      - name: Delete leftover cloud jobs
+        if: always()
+        env:
+          GOOGLE_CLOUD_API_KEY: ${{ secrets.GOOGLE_CLOUD_API_KEY }}
+          GCP_REGION: europe-west4
+        run: uv run --no-project --with google-cloud-batch --with google-cloud-run python tests/powerfunc_tests/cleanup.py
 
   test-modal:
     runs-on: ubuntu-latest
@@ -58,6 +66,8 @@ jobs:
           enable-cache: true
       - name: Run Modal tests
         env:
+          GOOGLE_CLOUD_API_KEY: ${{ secrets.GOOGLE_CLOUD_API_KEY }}
+          GCP_BUCKET: gs://powerfunc-temporary-348293
           MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
           MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
         run: uvx --with tox-uv tox run -e modal

{powerfunc-0.3.0 → powerfunc-0.5.0}/.gitignore

@@ -16,3 +16,6 @@ venv/
 
 # OS
 .DS_Store
+
+# Tests
+.powerfunc_test_secrets/

{powerfunc-0.3.0 → powerfunc-0.5.0}/PKG-INFO

@@ -1,17 +1,18 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: powerfunc
-Version: 0.3.0
+Version: 0.5.0
 Summary: Make functions run however you like — CLI, pipeline, or remote compute
 Project-URL: Homepage, https://github.com/ddrakard/powerfunc
 Project-URL: Repository, https://github.com/ddrakard/powerfunc
 Project-URL: Documentation, https://github.com/ddrakard/powerfunc/blob/main/documentation/readme.md
 License-File: LICENSE.txt
 Requires-Python: >=3.9
-Requires-Dist: cloudpathlib[all]
 Requires-Dist: cloudpickle
+Requires-Dist: cryptography
 Requires-Dist: fsspec[adl,gcs,s3]
-Requires-Dist: jsonargparse>=4.49.0
+Requires-Dist: jsonargparse[signatures]>=4.49.0
 Requires-Dist: pydantic>=2
+Requires-Dist: universal-pathlib>=0.2
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'

{powerfunc-0.3.0 → powerfunc-0.5.0}/documentation/providers/gcp.md

@@ -8,6 +8,7 @@ powerfunc supports two GCP execution backends: [Cloud Run Jobs](https://cloud.go
 - [Setup and configuration](#setup-and-configuration)
 - [Cloud Run](#cloud-run)
 - [Batch](#batch)
+- [The remote environment](#the-remote-environment)
 - [Environment variables](#environment-variables)
 - [Predefined configurations](#predefined-configurations)
 - [Supported GPUs](#supported-gpus)
@@ -116,6 +117,32 @@ result = sum_col("gs://bucket/data.csv", compute=compute)
 `machine_type` is optional — Batch selects a machine from the requested CPU/memory when it
 is not given. For GPUs, a compatible `machine_type` is usually required.
 
+## The remote environment
+
+A job runs in three stages inside the container image given by `image`:
+
+1. A bootstrap that needs nothing from the image: it obtains [uv](https://docs.astral.sh/uv/) and uses it to start powerfunc's setup stage (`python -m powerfunc.providers.internal.generic_setup_entrypoint`).
+2. The setup stage unpacks your codebase (the git-tracked files of your repository) into the container's working directory (the image's `WORKDIR`, over any files already there — so an image that already contains your project and its environment gets just your current changes laid on top) and runs the provider's `setup_command`, a shell command, there.
+3. The function is run with `python -m powerfunc.providers.internal.generic_execute_entrypoint` using the `python` found on `PATH` after the setup command.
+
+By default (`setup_command` empty, as in the predefined configurations) the image must already provide `python` with powerfunc and your dependencies installed; otherwise `setup_command` has to produce it. Ready-made commands live in `powerfunc.compute`: `UV_PROJECT_SETUP` (`uv sync --locked && . .venv/bin/activate`) treats the codebase as a [uv project](https://docs.astral.sh/uv/guides/projects/); `PIXI_PROJECT_SETUP` installs [pixi](https://pixi.sh), runs `pixi install --locked` and activates the environment; `PIP_PYPROJECT_SETUP` and `PIP_REQUIREMENTS_TXT_SETUP` make a `.venv` with the image's Python and `pip install` the codebase's `pyproject.toml` or `requirements.txt` into it. Any environment manager works the same way as long as it leaves `python` on `PATH`:
+
+```yaml
+compute:
+  class_path: powerfunc.providers.gcp_cloud_run.GcpCloudRunCpuSmall
+  init_args:
+    timeout: 600
+    provider:
+      class_path: powerfunc.providers.gcp_cloud_run.GCPCloudRunProvider
+      init_args:
+        project: my-project
+        region: us-central1
+        temporary_bucket_path: gs://my-bucket/powerfunc-tmp
+        setup_command: "python -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt"
+```
+
+Leave `setup_command` empty when the image already has everything installed.
+
 ## Environment variables
 
 Both Cloud Run and Batch support passing environment variables to the remote container via the `environment_variables` provider option:
@@ -138,6 +165,12 @@ provider:
       MY_API_KEY: secret123
 ```
 
+Note that these are part of the job definition, so visible to anyone who can view the job in the project while it exists. Whole directories of credentials or other files go by `secret_directories=["config/"]`, as described in the [readme](../readme.md#cloud-providers-and-remote-execution): only the encrypted archive is uploaded to the bucket, and only the decryption key is in the job's environment.
+
+## Shared buckets
+
+Set the provider's `user_identifier` (e.g. `user_identifier="alice"`) to prefix the job artifacts in `temporary_bucket_path` with it, so you can tell whose jobs are whose.
+
 ## Supported GPUs
 
 Both Cloud Run and Batch support: `t4`, `a100`, `l4`, `v100`.
@@ -151,7 +184,7 @@ Both Cloud Run and Batch support: `t4`, `a100`, `l4`, `v100`.
 | `GcpBatchCpuSmall` | Batch | 1 vCPU | 2GB | `python:3.12-slim` | — |
 | `GcpBatchGpu` | Batch | 4 vCPU | 16GB | `nvidia/cuda:12.1.0-base-ubuntu22.04` | L4 |
 
-All presets require a `timeout` argument (in seconds), e.g. `GcpCloudRunCpuSmall(timeout=600)` or `GcpBatchCpuSmall(timeout=600)`.
+All presets expect the image to provide `python` with powerfunc and your dependencies, unless a `setup_command` is given (see [the remote environment](#the-remote-environment)), and require a `timeout` argument (in seconds), e.g. `GcpCloudRunCpuSmall(timeout=600)` or `GcpBatchCpuSmall(timeout=600)`.
 
 ## Known limitations
 

powerfunc-0.5.0/documentation/providers/modal.md

@@ -0,0 +1,89 @@
+# Modal
+
+This page describes how to execute powerfunc functions remotely on [Modal](https://modal.com).
+
+## Contents
+
+- [Installation](#installation)
+- [Basic usage](#basic-usage)
+- [The remote environment](#the-remote-environment)
+- [Presets](#presets)
+
+## Installation
+
+Make sure to install with the `modal` option.
+
+```sh
+pip install 'powerfunc[modal]'
+```
+
+or
+
+```sh
+uv add 'powerfunc[modal]'
+```
+
+You must have a Modal account. Then authenticate to Modal:
+
+```sh
+python -m modal setup
+```
+
+## Basic usage
+
+```python
+from powerfunc import powerfunc
+from powerfunc.providers.modal import ModalCpuSmall
+
+@powerfunc
+def sum_col(df: pd.DataFrame) -> float:
+    return float(df["value"].sum())
+
+result = sum_col("data.csv", compute=ModalCpuSmall(timeout=600))
+```
+
+Or set a default in `powerfunc.yaml` so all calls run on Modal without passing `compute=`:
+
+```yaml
+compute:
+  class_path: powerfunc.providers.modal.ModalCpuSmall
+  init_args:
+    timeout: 600
+```
+
+## The remote environment
+
+The container image is `image` — a registry image, or Modal's `debian_slim` when empty — built once and cached by Modal. Your codebase (your repository minus `.git` and whatever git ignores) is not built into it but mounted when the container starts, onto the image's working directory (its `WORKDIR`, over any files already there — so an image that already contains your project and its environment gets just your current changes laid on top); Modal uploads only the files it has not seen before, so editing your code costs neither an image build nor a full upload. `setup_command` then runs there, on every call, and the function runs with `python -m powerfunc.providers.internal.generic_execute_entrypoint` using the `python` the setup command left on `PATH`, so the same `setup_command` works here and on GCP. By default (`setup_command` empty, as in the predefined configurations) the image must already have `python` with powerfunc and your dependencies:
+
+```python
+from powerfunc.providers.modal import ModalCpuSmall
+
+compute = ModalCpuSmall(timeout=600, image="ghcr.io/me/my-project:latest")
+result = sum_col("data.csv", compute=compute)
+```
+
+Otherwise the provider's `setup_command` has to produce it; `powerfunc.compute.UV_PROJECT_SETUP` (`uv sync --locked && . .venv/bin/activate`) treats the codebase as a uv project, `PIXI_PROJECT_SETUP` does the same with pixi, `PIP_PYPROJECT_SETUP`/`PIP_REQUIREMENTS_TXT_SETUP` pip-install the codebase's `pyproject.toml`/`requirements.txt` into a fresh `.venv`, or use any command that leaves `python` on `PATH`. In `powerfunc.yaml`:
+
+```yaml
+compute:
+  class_path: powerfunc.providers.modal.ModalCpuSmall
+  init_args:
+    timeout: 600
+    provider:
+      class_path: powerfunc.providers.modal.ModalProvider
+      init_args:
+        setup_command: "python -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt"
+```
+
+The command runs verbatim: anything it needs, such as `uv` itself, must be in the image or installed by the command. Since it runs on every call, a dependency install there is paid each time — for anything heavy, put the environment in `image` instead.
+
+`ModalProvider(environment_variables={"NAME": "value"})` sets environment variables of the running function. For example, to read `gs://` paths with a service-account key rather than ADC, give the key JSON as [fsspec configuration](https://filesystem-spec.readthedocs.io/en/latest/features.html#configuration): `environment_variables={"FSSPEC_GCS_TOKEN": key_json}`. `secret_directories=["config/"]` sends whole directories (relative to the repository root, git-ignored or not) encrypted, as described in the [readme](../readme.md#cloud-providers-and-remote-execution), rather than in the image.
+
+## Presets
+
+| Class | CPU | Memory | GPU |
+|---|---|---|---|
+| `ModalCpuSmall` | 1 vCPU | 1GB | — |
+| `ModalGpuA100` | 8 vCPU | 80GB | A100 |
+
+All presets require a `timeout` argument (in seconds), e.g. `ModalCpuSmall(timeout=600)`.

{powerfunc-0.3.0 → powerfunc-0.5.0}/documentation/readme.md

@@ -142,6 +142,8 @@ Each compute provider has its own setup process. See the individual pages for pr
 - [GCP](providers/gcp.md)
 - [Modal](providers/modal.md)
 
+The codebase — the git repository holding your function — is sent along with the job so the function can be imported there; files git ignores are not. To send credentials or other ignored files too, name their directories (relative to the repository root) in the provider's `secret_directories`, e.g. `ModalProvider(secret_directories=["config/"])`: they are left out of the codebase upload (even if git tracks them), zipped and encrypted with a key made for that call, the key reaching the container only as an environment variable (never stored with the job's other artifacts or in an image), and are decrypted into the codebase at the same paths before the function runs.
+
 The [configuration](#configuration) section is useful for working with compute providers, including configuring a default provider.
 
 ## Configuration
@@ -183,6 +185,13 @@ When using the CLI, pass a config file with `--config`:
 python my_script.py sum_col data.csv --config my_config.yaml
 ```
 
+The command line always reads the configuration files. A call from Python reads none unless asked, with `config`, the same option as `--config`: a path to a file, or `True` for the default files.
+
+```python
+sum_col("data.csv", config=True)
+sum_col("data.csv", config="my_config.yaml")
+```
+
 ## Supported formats
 
 | Type | Formats |

{powerfunc-0.3.0 → powerfunc-0.5.0}/pyproject.toml

@@ -4,16 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "powerfunc"
-version = "0.3.0"
+version = "0.5.0"
 description = "Make functions run however you like — CLI, pipeline, or remote compute"
 readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
     "pydantic>=2",
-    "cloudpathlib[all]",
+    "universal-pathlib>=0.2",
     "fsspec[gcs,s3,adl]",
-    "jsonargparse>=4.49.0",
+    "jsonargparse[signatures]>=4.49.0",
     "cloudpickle",
+    "cryptography",
 ]
 
 [project.optional-dependencies]

{powerfunc-0.3.0 → powerfunc-0.5.0}/src/powerfunc/command_line.py

@@ -1,5 +1,6 @@
 import inspect
 import sys
+from collections.abc import Callable
 
 from jsonargparse import CLI
 
@@ -10,8 +11,8 @@ class ExpectedException(Exception):
     """Raised for known user errors that should display just the message, not a traceback."""
 
 
-cli_functions: list[tuple] = []
-_cli_active = False
+# Each function's parsed-arguments entry, by the function's name: the command's.
+cli_functions: dict[str, Callable] = {}
 
 
 def enable_cli():
@@ -20,17 +21,15 @@ def enable_cli():
         frame = inspect.currentframe()
         if frame is None or frame.f_back is None:
             raise ExpectedException("Frame inspection not supported by this Python implementation.")
-        caller_module = inspect.getmodule(frame.f_back)
-        if caller_module is None or caller_module.__name__ != "__main__":
+        # By the frame's globals, not inspect.getmodule: under ``python -m`` the same
+        # file is often imported by its package name too, and getmodule finds that one.
+        if frame.f_back.f_globals.get("__name__") != "__main__":
             return
         if not cli_functions:
             raise ExpectedException("No @powerfunc functions registered for CLI.")
 
-        global _cli_active
-        wrappers = [wrapper for wrapper, _ in cli_functions]
-        _cli_active = True
         result = CLI(
-            wrappers[0] if len(wrappers) == 1 else wrappers,
+            next(iter(cli_functions.values())) if len(cli_functions) == 1 else cli_functions,
             default_config_files=configuration_paths,
         )
         if result is not None:

powerfunc-0.5.0/src/powerfunc/compute.py

@@ -0,0 +1,90 @@
+import dataclasses
+from typing import TYPE_CHECKING, Annotated, Any, Optional, TypeAlias
+
+from pydantic import Field, GetCoreSchemaHandler
+from pydantic.dataclasses import dataclass as pydantic_dataclass
+from pydantic_core import core_schema
+
+from powerfunc.command_line import ExpectedException
+
+Timeout: TypeAlias = Annotated[float, Field(gt=0, description="Maximum job duration in seconds")]
+CpuCount: TypeAlias = Annotated[float, Field(gt=0, description="Number of vCPUs")]
+MemorySize: TypeAlias = Annotated[int, Field(gt=0, description="RAM in MB")]
+DockerImageUri: TypeAlias = Annotated[str, Field(description="Container image URI")]
+GpuModel: TypeAlias = Annotated[
+    Optional[str], Field(description="GPU model name, as the provider names it (e.g. 'l4', 'a100')")
+]
+
+UV_PROJECT_SETUP = "uv sync --locked && . .venv/bin/activate"
+"""Setup command for a codebase that is a uv project."""
+
+_PIXI_URL = "https://pixi.sh/install.sh"
+PIXI_PROJECT_SETUP = (
+    'export PATH="$HOME/.pixi/bin:$PATH"; { command -v pixi >/dev/null 2>&1 || '
+    "{ command -v curl >/dev/null 2>&1 && curl -fsSL "
+    + _PIXI_URL
+    + " || wget -qO- "
+    + _PIXI_URL
+    + "; }"
+    ' | PIXI_HOME="$HOME/.pixi" sh; } && pixi install --locked && eval "$(pixi shell-hook)"'
+)
+"""Setup command for a codebase that is a pixi project."""
+
+_PIP_VENV = "python -m venv .venv && . .venv/bin/activate"
+PIP_PYPROJECT_SETUP = _PIP_VENV + " && pip install -q ."
+"""Setup command for a codebase that is a pip-installable project (``pyproject.toml``)."""
+PIP_REQUIREMENTS_TXT_SETUP = _PIP_VENV + " && pip install -q -r requirements.txt"
+"""Setup command for a codebase with a pip ``requirements.txt``."""
+
+if TYPE_CHECKING:
+    from powerfunc.decorator import PowerFunc
+
+
+class Provider:
+    """Base compute provider. Subclass and implement call()."""
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        return core_schema.is_instance_schema(cls)
+
+    def call(self, function: "PowerFunc", arguments: dict, compute: "ComputeSpecification") -> Any:
+        """Run ``function._run_without_parsing(**arguments)`` on the compute, returning its result.
+
+        ``function`` is the powerfunc function itself, named in the job by module and qualname.
+        ``arguments`` have already been parsed and merged with the configuration
+        files, so the compute does neither; there, ``_run_without_parsing`` opens
+        the files given for parameters and writes the result to ``output_path``.
+        """
+        raise NotImplementedError
+
+
+class UndefinedProvider(Provider):
+    """Sentinel — raises ExpectedException when called if no provider has been configured."""
+
+    def call(self, function, arguments, compute):
+        raise ExpectedException(
+            "No provider configured. Set compute.provider in powerfunc.yaml or pass compute="
+        )
+
+
+@pydantic_dataclass
+class ComputeSpecification:
+    """Specifies compute resources for remote execution."""
+
+    timeout: Timeout
+    cpu: CpuCount
+    memory: MemorySize
+    image: DockerImageUri = ""
+    provider: Provider = dataclasses.field(default_factory=UndefinedProvider)
+    gpu: GpuModel = None
+
+
+@pydantic_dataclass
+class CpuSmall(ComputeSpecification):
+    """1 vCPU, 2GB RAM, Python 3.12 slim."""
+
+    cpu: CpuCount = 1.0
+    memory: MemorySize = 2048
+    image: DockerImageUri = "python:3.12-slim"

{powerfunc-0.3.0 → powerfunc-0.5.0}/src/powerfunc/conversions.py

@@ -1,8 +1,11 @@
-import os
 import pathlib
-from contextlib import contextmanager, nullcontext
+import tempfile
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, contextmanager, nullcontext
 
-from cloudpathlib import AnyPath, CloudPath
+from upath import UPath
+
+_LOCAL_PROTOCOLS = frozenset({"", "file", "local"})
 
 # (type_, extension) -> {"reader": ..., "writer": ..., "native_protocols": ...}
 _registry: dict[tuple, dict] = {}
@@ -40,33 +43,43 @@ def as_context(function):
     return wrapper
 
 
-def read(value, type_):
+Reader = Callable[[str | pathlib.Path], AbstractContextManager[object]]
+
+
+def read(value: object, type_: type) -> AbstractContextManager[object]:
     """Convert a path or URI to the target type, returning a context manager.
 
     If no reader is registered for the type and file extension, the value is
     returned unchanged. Cloud URIs are streamed directly if the reader declares
-    the scheme as native, otherwise downloaded locally via cloudpathlib first.
+    the scheme as native, otherwise downloaded to a temporary local file first.
     """
-    if not isinstance(value, (str, pathlib.Path, CloudPath)):
+    if not isinstance(value, (str, pathlib.Path, UPath)):
         return nullcontext(value)
-    path = AnyPath(str(value))
+    path = UPath(str(value))
     suffix = path.suffix
     entry = _registry.get((type_, suffix))
     if entry is None or entry["reader"] is None:
         return nullcontext(value)
     reader = entry["reader"]
-    native_protocols = entry["native_protocols"]
-    if isinstance(path, CloudPath):
-        scheme = type(path).cloud_prefix.replace("://", "")
-        if scheme in native_protocols:
-            return reader(str(path))
-        return reader(pathlib.Path(os.fspath(path)))
-    return reader(pathlib.Path(value))
+    if path.protocol in _LOCAL_PROTOCOLS:
+        return reader(pathlib.Path(path.path))
+    if path.protocol in entry["native_protocols"]:
+        return reader(str(path))
+    return _temporary_copy_reader(reader, path)
+
+
+@contextmanager
+def _temporary_copy_reader(reader: Reader, path: UPath) -> Iterator[object]:
+    with tempfile.TemporaryDirectory() as directory:
+        local = pathlib.Path(directory) / path.name
+        local.write_bytes(path.read_bytes())
+        with reader(local) as value:
+            yield value
 
 
 def write(value, path):
     """Write value to path using the registered writer based on file extension."""
-    path = AnyPath(str(path))
+    path = UPath(str(path))
     suffix = path.suffix
     entry = _registry.get((type(value), suffix))
     if entry is None or entry["writer"] is None:

powerfunc-0.5.0/src/powerfunc/decorator.py

@@ -0,0 +1,207 @@
+import functools
+import inspect
+import pathlib
+import sys
+from collections.abc import Callable
+from contextlib import ExitStack
+from typing import Any, Optional, Protocol, TypeVar, Union, overload
+
+from jsonargparse import ArgumentParser
+from upath import UPath
+
+import powerfunc.command_line as command_line
+from powerfunc.command_line import ExpectedException
+from powerfunc.compute import ComputeSpecification
+from powerfunc.configuration import configuration_paths
+from powerfunc.conversions import is_readable, read, write
+
+_EXTRA_PARAMETERS = [
+    inspect.Parameter(
+        "compute",
+        inspect.Parameter.KEYWORD_ONLY,
+        default=None,
+        annotation=Optional[ComputeSpecification],
+    ),
+    inspect.Parameter(
+        "output_path",
+        inspect.Parameter.KEYWORD_ONLY,
+        default=None,
+        annotation=Optional[str],
+    ),
+]
+# The same option as the command line's ``--config``: a configuration file to
+# merge the arguments with, or True for the default files, which the command
+# line reads unless told another. A Python call reads none unless asked.
+_CONFIGURATION_PARAMETER = inspect.Parameter(
+    "config",
+    inspect.Parameter.KEYWORD_ONLY,
+    default=None,
+    annotation=Union[str, pathlib.Path, bool, None],
+)
+
+
+def _configuration_files(config) -> list[str]:
+    if config is None or config is False:
+        return []
+    if config is True:
+        return configuration_paths
+    return [str(config)]
+
+
+R = TypeVar("R", covariant=True)
+
+
+class PowerFunc(Protocol[R]):
+    """What :func:`powerfunc` makes of a function.
+
+    Called as the function was, plus ``compute`` to run it elsewhere and
+    ``output_path`` to write what it returns to a file; the function's own
+    parameters are read from its signature at run time, so they are not checked
+    statically here.
+    """
+
+    def __call__(
+        self,
+        *args: Any,
+        compute: Optional[ComputeSpecification] = None,
+        output_path: Optional[str] = None,
+        config: Union[str, pathlib.Path, bool, None] = None,
+        **kwargs: Any,
+    ) -> R: ...
+
+    def snakemake(self) -> Any:
+        """Run this function bound to the surrounding Snakemake rule."""
+        ...
+
+    def _run_without_parsing(self, **arguments: Any) -> R:
+        """Run with arguments already parsed: by the command line, or before dispatch to compute."""
+        ...
+
+
+def optional_arguments_decorator(decorator):
+    """Allows a decorator to be applied with or without argument parentheses."""
+
+    @functools.wraps(decorator)
+    def wrapper(function=None, **kwargs):
+        if function is not None:
+            return decorator(function, **kwargs)
+        return functools.partial(decorator, **kwargs)
+
+    return wrapper
+
+
+@overload
+def powerfunc(function: Callable[..., R], *, cli: bool = True) -> PowerFunc[R]: ...
+@overload
+def powerfunc(
+    function: None = None, *, cli: bool = True
+) -> Callable[[Callable[..., R]], PowerFunc[R]]: ...
+@optional_arguments_decorator
+def powerfunc(function=None, *, cli=True):
+    """Decorator to turn a function into a powerfunc function.
+
+    Applied bare, ``@powerfunc``, or with arguments, ``@powerfunc(cli=False)``.
+    """
+    # eval_str=True required for `from __future__ import annotations`
+    signature = inspect.signature(function, eval_str=True)
+    reserved = {param.name for param in [*_EXTRA_PARAMETERS, _CONFIGURATION_PARAMETER]}
+    taken = reserved & signature.parameters.keys()
+    if taken:
+        raise TypeError(
+            f"{function.__name__} has parameters powerfunc adds itself: {', '.join(sorted(taken))}."
+        )
+    modified_signature = signature.replace(
+        parameters=[
+            param.replace(
+                # str must precede pathlib.Path and UPath: jsonargparse resolves Union
+                # subtypes in order and pathlib.Path accepts any string without error, so it
+                # would win and mangle "gs://bucket/file" into PosixPath("gs:/bucket/file").
+                annotation=Union[param.annotation, str, pathlib.Path, UPath]
+                if is_readable(param.annotation)
+                else param.annotation
+            )
+            for param in signature.parameters.values()
+        ]
+        + _EXTRA_PARAMETERS
+    )
+
+    # Two entry points: wrapper takes a Python call's arguments as they are,
+    # filling in from a configuration file if one is named, then
+    # _run_without_parsing dispatches to compute if asked, else reads the path
+    # arguments, calls the function and writes the result. The command line,
+    # having parsed argv and the default configuration files with jsonargparse,
+    # and the compute provider, given arguments without ``compute``, both enter
+    # at _run_without_parsing.
+    calling_signature = modified_signature.replace(
+        parameters=[*modified_signature.parameters.values(), _CONFIGURATION_PARAMETER]
+    )
+
+    def _from_configuration(files, given):
+        """The arguments the configuration ``files`` hold, other than those ``given``."""
+
+        def dummy():
+            pass
+
+        dummy.__signature__ = modified_signature
+        parser = ArgumentParser(exit_on_error=False, default_config_files=files)
+        parser.add_function_arguments(dummy)
+        try:
+            return {
+                name: value
+                for name, value in vars(parser.instantiate(parser.get_defaults())).items()
+                if name not in given
+            }
+        except Exception as e:
+            raise ExpectedException(str(e)) from e
+
+    @functools.wraps(function)
+    def wrapper(*args, **kwargs):
+        """Run with the arguments as given, and ``config``'s for the rest."""
+        arguments = dict(calling_signature.bind_partial(*args, **kwargs).arguments)
+        files = _configuration_files(arguments.pop(_CONFIGURATION_PARAMETER.name, None))
+        if files:
+            arguments.update(_from_configuration(files, arguments))
+        try:
+            bound = modified_signature.bind(**arguments)
+        except TypeError as e:
+            raise ExpectedException(str(e)) from e
+        bound.apply_defaults()
+        return _run_without_parsing(**bound.arguments)
+
+    def _run_without_parsing(**arguments):
+        """Run on the compute asked for, or here: read the files given, write the result."""
+        compute = arguments.pop("compute", None)
+        if compute is not None:
+            return compute.provider.call(wrapper, arguments, compute)
+        output_path = arguments.pop("output_path", None)
+        with ExitStack() as stack:
+            kwargs = {
+                name: stack.enter_context(read(arguments[name], param.annotation))
+                for name, param in signature.parameters.items()
+            }
+            result = function(**kwargs)
+        if output_path is not None:
+            write(result, output_path)
+            return output_path
+        return result
+
+    wrapper.__signature__ = calling_signature
+    # The CLI parses by this entry's signature and describes it by its docstring
+    # (else by its repr, which would name this entry, not the function).
+    _run_without_parsing.__doc__ = function.__doc__ or function.__name__
+    _run_without_parsing.__signature__ = modified_signature
+    wrapper._run_without_parsing = _run_without_parsing
+
+    def snakemake():
+        """Run this function bound to the surrounding Snakemake rule."""
+        from powerfunc.integrations import snakemake as snakemake_integration
+
+        frame = sys._getframe(1)
+        return snakemake_integration.run(wrapper, frame)
+
+    wrapper.snakemake = snakemake
+
+    if cli and function.__module__ == "__main__":
+        command_line.cli_functions[function.__name__] = _run_without_parsing
+
+    return wrapper