powerfunc 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -58,6 +58,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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: powerfunc
-Version: 0.3.0
+Version: 0.4.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
@@ -10,7 +10,7 @@ Requires-Python: >=3.9
 Requires-Dist: cloudpathlib[all]
 Requires-Dist: cloudpickle
 Requires-Dist: fsspec[adl,gcs,s3]
-Requires-Dist: jsonargparse>=4.49.0
+Requires-Dist: jsonargparse[signatures]>=4.49.0
 Requires-Dist: pydantic>=2
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == 'dev'

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

@@ -183,6 +183,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.4.0}/pyproject.toml

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

{powerfunc-0.3.0 → powerfunc-0.4.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.3.0 → powerfunc-0.4.0}/src/powerfunc/compute.py

@@ -1,5 +1,5 @@
 import dataclasses
-from typing import Annotated, Any, Callable, Optional, TypeAlias
+from typing import TYPE_CHECKING, Annotated, Any, Optional, TypeAlias
 
 from pydantic import Field, GetCoreSchemaHandler
 from pydantic.dataclasses import dataclass as pydantic_dataclass
@@ -13,6 +13,9 @@ 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")]
 
+if TYPE_CHECKING:
+    from powerfunc.decorator import PowerFunc
+
 
 class Provider:
     """Base compute provider. Subclass and implement call()."""
@@ -23,7 +26,14 @@ class Provider:
     ) -> core_schema.CoreSchema:
         return core_schema.is_instance_schema(cls)
 
-    def call(self, function: Callable, arguments: dict, spec: "ComputeSpecification") -> Any:
+    def call(self, function: "PowerFunc", arguments: dict, spec: "ComputeSpecification") -> Any:
+        """Run ``function._run_without_parsing(**arguments)`` on the compute, returning its result.
+
+        ``function`` is the powerfunc function itself, picklable by its name.
+        ``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
 
 

powerfunc-0.4.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 cloudpathlib import CloudPath
+from jsonargparse import ArgumentParser
+
+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 CloudPath: 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, CloudPath]
+                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

{powerfunc-0.3.0 → powerfunc-0.4.0}/src/powerfunc/providers/gcp_cloud_run.py

@@ -1,6 +1,7 @@
 import collections.abc
 import contextlib
 import importlib
+import importlib.metadata
 import inspect
 import io
 import json
@@ -14,7 +15,7 @@ import time
 import warnings
 import zipfile
 from dataclasses import dataclass, field
-from typing import Any, Callable, Optional
+from typing import Any, Optional
 
 import cloudpickle as pickle
 from cloudpathlib import AnyPath
@@ -31,6 +32,7 @@ from powerfunc.compute import (
     Provider,
     user_identifier,
 )
+from powerfunc.decorator import PowerFunc
 
 _SUPPORTED_GPUS = {"t4", "a100", "l4", "v100"}
 _MAX_JOB_NAME_LENGTH = 63  # GCP resource name limit (Cloud Run and Batch)
@@ -67,8 +69,10 @@ def _bootstrap_command(job_spec_path: "AnyPath", error_gcs_path: str = "") -> st
         "&& curl -LsSf " + _uv_url + " | sh; }; }"
     )
     # uv run handles everything: ephemeral env, Python download, install, execute.
+    # The remote runs the same powerfunc version as the caller.
+    powerfunc_version = importlib.metadata.version("powerfunc")
     run_cmd = (
-        f'uv run --with powerfunc --with "pydantic>=2" '
+        f'uv run --with "powerfunc=={powerfunc_version}" --with "pydantic>=2" '
         f"python -m powerfunc.providers.gcp_cloud_run {job_spec_path}"
     )
     main_cmd = get_uv + " && " + run_cmd
@@ -250,7 +254,7 @@ class GCPCloudRunProvider(Provider):
             pass
 
     @staticmethod
-    def _extra_sys_paths(function: Callable, repo_root: Optional[pathlib.Path]) -> list[str]:
+    def _extra_sys_paths(function: PowerFunc, repo_root: Optional[pathlib.Path]) -> list[str]:
         """Relative directories that must be added to sys.path on the remote.
 
         Compares the function's source file to its module name to discover
@@ -260,7 +264,7 @@ class GCPCloudRunProvider(Provider):
         if repo_root is None:
             return []
         try:
-            src = pathlib.Path(inspect.getfile(function)).resolve()
+            src = pathlib.Path(inspect.getfile(inspect.unwrap(function))).resolve()
             rel = src.relative_to(repo_root)
         except (TypeError, ValueError):
             return []
@@ -275,7 +279,7 @@ class GCPCloudRunProvider(Provider):
                 return [prefix]
         return []
 
-    def call(self, function: Callable, arguments: dict, compute: ComputeSpecification) -> Any:
+    def call(self, function: PowerFunc, arguments: dict, compute: ComputeSpecification) -> Any:
         if function.__module__ == "__main__":
             spec = getattr(__main__, "__spec__", None)
             if spec is None:
@@ -378,7 +382,7 @@ if __name__ == "__main__":
             func: Any = importlib.import_module(module_path)
             for part in qualname.split("."):
                 func = getattr(func, part)
-            result = func(**kwargs)
+            result = func._run_without_parsing(**kwargs)
 
         AnyPath(spec["output_path"]).write_bytes(pickle.dumps(result))
     except BaseException as exc:

{powerfunc-0.3.0 → powerfunc-0.4.0}/src/powerfunc/providers/modal.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass, field
-from typing import Any, Callable
+from typing import Any
 
 from pydantic.dataclasses import dataclass as pydantic_dataclass
 
@@ -12,6 +12,7 @@ from powerfunc.compute import (
     MemorySize,
     Provider,
 )
+from powerfunc.decorator import PowerFunc
 
 try:
     import modal
@@ -22,36 +23,38 @@ try:
 
         pip_packages: tuple[str, ...] = ()
 
-        def call(self, function: Callable, arguments: dict, compute: ComputeSpecification) -> Any:
+        def image(self, compute: ComputeSpecification) -> modal.Image:
+            """The image the function runs in: ``compute.image`` or Debian slim, with
+            ``pip_packages`` installed. Override to build one another way, e.g. from a
+            conda environment, or with the local codebase added."""
             image = modal.Image.debian_slim()
             if compute.image:
                 image = modal.Image.from_registry(compute.image)
             if self.pip_packages:
                 image = image.pip_install(*self.pip_packages)
+            return image
+
+        def secrets(self) -> list[modal.Secret]:
+            """Modal secrets to expose to the function as environment variables."""
+            return []
+
+        def call(self, function: PowerFunc, arguments: dict, compute: ComputeSpecification) -> Any:
             app = modal.App(name=f"powerfunc-{function.__name__}")
 
             @app.function(
-                image=image,
+                image=self.image(compute),
                 cpu=compute.cpu,
                 memory=compute.memory,
                 gpu=compute.gpu,
+                timeout=int(compute.timeout),
+                secrets=self.secrets(),
                 serialized=True,
             )
-            def runner(fn: Callable, args: dict) -> Any:
-                return fn(**args)
-
-            output_path = arguments.pop("output_path", None)
+            def runner(fn: PowerFunc, args: dict) -> Any:
+                return fn._run_without_parsing(**args)
 
             with app.run():
-                result = runner.remote(function, arguments)
-
-            if output_path is not None:
-                from powerfunc.conversions import write
-
-                write(result, output_path)
-                return output_path
-
-            return result
+                return runner.remote(function, arguments)
 
     @pydantic_dataclass
     class ModalCpuSmall(ComputeSpecification):

{powerfunc-0.3.0/tests/powerfunc_tests/gcp → powerfunc-0.4.0/tests/powerfunc_tests}/conftest.py

@@ -1,5 +1,3 @@
-"""Shared pytest fixtures for GCP provider tests."""
-
 import json
 import os
 import tempfile
@@ -9,16 +7,19 @@ import pytest
 
 @pytest.fixture(scope="module")
 def gcp_credentials():
-    """Validate the service-account JSON and expose it via ADC."""
-    api_key = os.environ["GOOGLE_CLOUD_API_KEY"]
+    """Validate the service-account JSON in ``GOOGLE_CLOUD_API_KEY`` and expose it
+    via ADC (``GOOGLE_APPLICATION_CREDENTIALS``) for the duration of the module.
 
+    Fails (does not skip) if the provided key is not a service-account JSON: GCP
+    Batch, Cloud Run Jobs and GCS need service-account credentials, not a bare API
+    key.
+    """
     try:
-        info = json.loads(api_key)
+        info = json.loads(os.environ["GOOGLE_CLOUD_API_KEY"])
     except json.JSONDecodeError as error:
         raise ValueError(
             "GOOGLE_CLOUD_API_KEY is set but is not valid JSON. It must be a GCP "
-            "service-account JSON key (GCP providers require "
-            "service-account credentials, not a bare API key)."
+            "service-account JSON key."
         ) from error
 
     if not isinstance(info, dict) or info.get("type") != "service_account":

powerfunc-0.4.0/tests/powerfunc_tests/core/__init__.py

@@ -0,0 +1,12 @@
+"""Test package for powerfunc.
+
+``cli_example`` is imported here, as a package's ``__init__`` commonly
+imports its modules, so that ``python -m powerfunc_tests.core.cli_example``
+runs it as ``__main__`` while the same file is also loaded under its package
+name. ``enable_cli`` must still register the command line in that case: it
+reads ``__name__`` from the calling module's globals, which is ``"__main__"``
+for the module being run, rather than asking ``inspect.getmodule``, which would
+return the package-named copy.
+"""
+
+from . import cli_example  # noqa: F401

powerfunc-0.4.0/tests/powerfunc_tests/core/cli_example.py

@@ -0,0 +1,40 @@
+"""Command line of three functions: two reading a file, one showing its defaults' layering."""
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+from powerfunc import powerfunc
+
+
+@powerfunc
+def sum_col(df: pd.DataFrame) -> float:
+    return float(df["value"].sum())
+
+
+@powerfunc
+def mean_col(df: pd.DataFrame) -> float:
+    return float(df["value"].mean())
+
+
+@powerfunc(cli=False)
+def ignored(df: pd.DataFrame) -> float:
+    return 0.0
+
+
+@dataclass
+class Spec:
+    cpu: int = 1
+    memory: int = 2
+
+
+DEFAULT_SPEC = Spec(cpu=3)
+DEFAULT_RANGES = {"a": 1.0}
+
+
+@powerfunc
+def show(spec: Spec = DEFAULT_SPEC, ranges: dict[str, float] = DEFAULT_RANGES) -> str:
+    return f"{spec.cpu} {spec.memory} {type(ranges).__name__} {dict(ranges)}"
+
+
+powerfunc.enable_cli()

powerfunc-0.4.0/tests/powerfunc_tests/core/test_configuration.py

@@ -0,0 +1,95 @@
+"""Defaults, then configuration file, then what the call gives, from either entry point.
+
+The command line reads ``configuration/powerfunc.yaml`` and ``powerfunc.yaml``
+from the working directory, or ``--config`` instead, and argv overwrites fields
+and keys of what they hold. A call from Python reads no file unless ``config``
+names one, or is True for those defaults -- else a stray file in the working
+directory would change any call's arguments -- and its own arguments win.
+"""
+
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+from powerfunc import powerfunc
+
+SCRIPT = pathlib.Path(__file__).parent / "cli_example.py"
+
+
+def run(*args):
+    result = subprocess.run([sys.executable, SCRIPT, "show", *args], capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr
+    return result.stdout.strip()
+
+
+def test_defaults():
+    assert run() == "3 2 dict {'a': 1.0}"
+
+
+def test_command_line_overwrites_dataclass_field_of_default():
+    assert run("--spec.memory", "8") == "3 8 dict {'a': 1.0}"
+
+
+def test_command_line_overwrites_dict_key_of_default():
+    assert run("--ranges.b", "2") == "3 2 dict {'a': 1.0, 'b': 2.0}"
+
+
+def test_config_file_then_command_line(tmp_path):
+    config = tmp_path / "config.yaml"
+    config.write_text("spec:\n  cpu: 5\nranges:\n  a: 3.0\n  c: 4.0\n")
+    assert run("--config", str(config)) == "5 2 dict {'a': 3.0, 'c': 4.0}"
+    assert run("--config", str(config), "--spec.memory", "8", "--ranges.a", "9") == (
+        "5 8 dict {'a': 9.0, 'c': 4.0}"
+    )
+
+
+def test_runs_as_a_module_its_package_already_imported():
+    result = subprocess.run(
+        [sys.executable, "-m", "powerfunc_tests.core.cli_example", "show", "--ranges.b", "2"],
+        capture_output=True,
+        text=True,
+        cwd=SCRIPT.parents[2],
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "3 2 dict {'a': 1.0, 'b': 2.0}"
+
+
+@powerfunc
+def scaled(value: float, *, scale: float = 1.0) -> float:
+    return value * scale
+
+
+@pytest.fixture
+def default_configuration(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "powerfunc.yaml").write_text("scale: 10\n")
+    return tmp_path
+
+
+def test_python_call_ignores_default_files(default_configuration):
+    assert scaled(2.0) == 2.0
+
+
+def test_python_call_config_true_reads_default_files(default_configuration):
+    assert scaled(2.0, config=True) == 20.0
+
+
+def test_python_call_config_path_reads_that_file(tmp_path):
+    configuration = tmp_path / "elsewhere.yaml"
+    configuration.write_text("scale: 3\n")
+    assert scaled(2.0, config=configuration) == 6.0
+    assert scaled(2.0, config=str(configuration)) == 6.0
+
+
+def test_python_call_arguments_win_over_the_file(default_configuration):
+    assert scaled(2.0, scale=5.0, config=True) == 10.0
+
+
+def test_a_function_may_not_name_a_parameter_powerfunc_adds():
+    with pytest.raises(TypeError, match="config"):
+
+        @powerfunc
+        def clashing(config: str) -> str:
+            return config