Improve the docstrings

* Use Google style parameter syntax, not Sphinx/RST style.
* Use imperative tense, not present tense, for summary lines.

Author: ctrueden

src/appose/__init__.py

@@ -236,7 +236,7 @@ def task_listener(event):
 
 def pixi(source: str | Path | None = None) -> PixiBuilder:
     """
-    Creates a PixiBuilder for Pixi-based environments.
+    Create a PixiBuilder for Pixi-based environments.
 
     Args:
         source: Optional configuration source (file path or URL)
@@ -255,7 +255,7 @@ def pixi(source: str | Path | None = None) -> PixiBuilder:
 
 def mamba(source: str | Path | None = None) -> MambaBuilder:
     """
-    Creates a MambaBuilder for Micromamba-based environments.
+    Create a MambaBuilder for Micromamba-based environments.
 
     Args:
         source: Optional configuration source (file path or URL)
@@ -274,7 +274,7 @@ def mamba(source: str | Path | None = None) -> MambaBuilder:
 
 def uv(source: str | Path | None = None) -> UvBuilder:
     """
-    Creates a UvBuilder for uv-based virtual environments.
+    Create a UvBuilder for uv-based virtual environments.
 
     Args:
         source: Optional configuration source (file path or URL)
@@ -293,7 +293,8 @@ def uv(source: str | Path | None = None) -> UvBuilder:
 
 def file(source: str | Path) -> DynamicBuilder:
     """
-    Creates a DynamicBuilder from a configuration file.
+    Create a DynamicBuilder from a configuration file.
+
     The builder type will be auto-detected from file content.
 
     Args:
@@ -307,7 +308,8 @@ def file(source: str | Path) -> DynamicBuilder:
 
 def url(source: str) -> DynamicBuilder:
     """
-    Creates a DynamicBuilder from a URL.
+    Create a DynamicBuilder from a URL.
+
     The builder type will be auto-detected from content.
 
     Args:
@@ -321,7 +323,8 @@ def url(source: str) -> DynamicBuilder:
 
 def content(content: str) -> DynamicBuilder:
     """
-    Creates a DynamicBuilder from configuration content.
+    Create a DynamicBuilder from configuration content.
+
     The builder type will be auto-detected from content syntax.
 
     Args:
@@ -335,7 +338,7 @@ def content(content: str) -> DynamicBuilder:
 
 def wrap(env_dir: str | Path) -> Environment:
     """
-    Wraps an existing environment directory, auto-detecting its type.
+    Wrap an existing environment directory, auto-detecting its type.
 
     Args:
         env_dir: The directory containing the environment
@@ -362,7 +365,7 @@ def wrap(env_dir: str | Path) -> Environment:
 
 def system(directory: str | Path = Path(".")) -> Environment:
     """
-    Creates a simple environment using system executables.
+    Create a simple environment using system executables.
 
     Args:
         directory: The working directory (defaults to current directory)
@@ -375,7 +378,7 @@ def system(directory: str | Path = Path(".")) -> Environment:
 
 def custom() -> SimpleBuilder:
     """
-    Creates a SimpleBuilder for custom environments without package management.
+    Create a SimpleBuilder for custom environments without package management.
 
     Returns:
         A SimpleBuilder instance

src/appose/environment.py

@@ -52,7 +52,7 @@ def __init__(self, base: Path | str, use_system_path: bool = False):
 
     def base(self) -> str:
         """
-        Returns the base directory of this environment.
+        Return the base directory of this environment.
 
         Returns:
             The absolute path to the base directory
@@ -61,7 +61,7 @@ def base(self) -> str:
 
     def bin_paths(self) -> list[str]:
         """
-        Returns the list of binary directories to search for executables.
+        Return the list of binary directories to search for executables.
 
         Returns:
             List of binary directory paths
@@ -71,7 +71,7 @@ def bin_paths(self) -> list[str]:
 
     def launch_args(self) -> list[str]:
         """
-        Returns the launch arguments to prepend when starting worker processes.
+        Return the launch arguments to prepend when starting worker processes.
 
         Returns:
             List of launch arguments
@@ -81,7 +81,7 @@ def launch_args(self) -> list[str]:
 
     def env_vars(self) -> dict[str, str]:
         """
-        Returns environment variables to set when launching worker processes.
+        Return environment variables to set when launching worker processes.
 
         Returns:
             Dictionary of environment variable names to values
@@ -117,9 +117,14 @@ def python(self) -> Service:
         Python scripts asynchronously on its linked process running a
         `python_worker`.
 
-        :return: The newly created service.
-        :see: groovy() To create a service for Groovy script execution.
-        :raises IOError: If something goes wrong starting the worker process.
+        Returns:
+            The newly created service.
+
+        Raises:
+            IOError: If something goes wrong starting the worker process.
+
+        See Also:
+            groovy(): To create a service for Groovy script execution.
         """
         python_exes = [
             "python",
@@ -140,24 +145,30 @@ def groovy(
         jvm_args: list[str] | None = None,
     ) -> Service:
         """
-        Create a Groovy script service. Groovy (https://groovy-lang.org/)
-        is a script language for the JVM, capable of running Java bytecode
-        conveniently and succinctly, as well as downloading and importing
-        dependencies dynamically at runtime using its Grape subsystem
-        (https://groovy-lang.org/Grape).
+        Create a Groovy script service.
+
+        Groovy (https://groovy-lang.org/) is a script language for the JVM,
+        capable of running Java bytecode conveniently and succinctly, as well
+        as downloading and importing dependencies dynamically at runtime using
+        its Grape subsystem (https://groovy-lang.org/Grape).
 
         This is a *high level* way to create a service, enabling execution of
         Groovy scripts asynchronously on its linked process running a
         `GroovyWorker`.
 
-        :param class_path:
-            Additional classpath elements to pass to the JVM
-            via its `-cp` command line option.
-        :param jvm_args:
-            Command line arguments to pass to the JVM invocation (e.g. `-Xmx4g`).
-        :return: The newly created service.
-        :see: python() To create a service for Python script execution.
-        :raises IOError: If something goes wrong starting the worker process.
+        Args:
+            class_path: Additional classpath elements to pass to the JVM
+                via its `-cp` command line option.
+            jvm_args: Command line arguments to pass to the JVM invocation (e.g. `-Xmx4g`).
+
+        Returns:
+            The newly created service.
+
+        Raises:
+            IOError: If something goes wrong starting the worker process.
+
+        See Also:
+            python(): To create a service for Python script execution.
         """
         return self.java(
             "org.apposed.appose.GroovyWorker", class_path=class_path, jvm_args=jvm_args
@@ -208,14 +219,17 @@ def service(self, exes: list[str], *args) -> Service:
         meaning it accepts requests on stdin and produces responses on
         stdout, both formatted according to Appose's assumptions.
 
-        :param exes:
-            List of executables to try for launching the worker process.
-        :param args:
-            Command line arguments to pass to the worker process
-            (e.g. ["-v", "--enable-everything"]).
-        :return: The newly created service.
-        :see: groovy() To create a service for Groovy script execution.
-        :see: python() To create a service for Python script execution.
+        Args:
+            exes: List of executables to try for launching the worker process.
+            args: Command line arguments to pass to the worker process
+                (e.g. ["-v", "--enable-everything"]).
+
+        Returns:
+            The newly created service.
+
+        See Also:
+            groovy(): To create a service for Groovy script execution.
+            python(): To create a service for Python script execution.
         """
         if not exes:
             raise ValueError("No executable given")

src/appose/service.py

@@ -82,11 +82,11 @@ def __init__(self, cwd: str | Path, args: list[str]) -> None:
 
     def debug(self, debug_callback: Callable[[Any], Any]) -> None:
         """
-        Register a callback function to receive messages
-        describing current service/worker activity.
+        Register a callback function to receive messages describing current
+        service/worker activity.
 
-        :param debug_callback:
-            A function that accepts a single string argument.
+        Args:
+            debug_callback: A function that accepts a single string argument.
         """
         self._debug_callback = debug_callback
 
@@ -130,31 +130,35 @@ def task(
     ) -> "Task":
         """
         Create a new task, passing the given script to the worker for execution.
-        :param script:
-            The script for the worker to execute in its environment.
-        :param inputs:
-            Optional list of key/value pairs to feed into the script as inputs.
-        :param queue:
-            Optional queue target. Pass "main" to queue to worker's main thread.
+
+        Args:
+            script: The script for the worker to execute in its environment.
+            inputs: Optional list of key/value pairs to feed into the script as inputs.
+            queue: Optional queue target. Pass "main" to queue to worker's main thread.
         """
         self.start()
         return Task(self, script, inputs, queue)
 
     def syntax(self, syntax: str | ScriptSyntax) -> Service:
         """
-        Declares the script syntax of this service.
+        Declare the script syntax of this service.
 
-        This value determines which {@link ScriptSyntax} implementation is used
+        This value determines which ScriptSyntax implementation is used
         for generating language-specific scripts.
 
         This method is called directly by Environment.python() and
         Environment.groovy() when creating services of those types.
         It can also be called manually to support custom languages with
         registered ScriptSyntax plugins.
 
-        :param syntax: The type identifier (e.g., "python", "groovy").
-        :return: This service object, for chaining method calls.
-        :raises: ValueError If no syntax plugin is found for the given type.
+        Args:
+            syntax: The type identifier (e.g., "python", "groovy").
+
+        Returns:
+            This service object, for chaining method calls.
+
+        Raises:
+            ValueError: If no syntax plugin is found for the given type.
         """
         self._syntax = (
             syntax if isinstance(syntax, ScriptSyntax) else syntax_from_name(syntax)
@@ -163,7 +167,7 @@ def syntax(self, syntax: str | ScriptSyntax) -> Service:
 
     def get_var(self, name: str) -> Any:
         """
-        Retrieves a variable's value from the worker process's global scope.
+        Retrieve a variable's value from the worker process's global scope.
 
         The variable must have been previously exported using task.export()
         to be accessible across tasks.
@@ -186,7 +190,7 @@ def get_var(self, name: str) -> Any:
 
     def put_var(self, name: str, value: Any) -> None:
         """
-        Sets a variable in the worker process's global scope and exports it
+        Set a variable in the worker process's global scope and export it
         for future use across tasks.
 
         Args:
@@ -205,8 +209,8 @@ def put_var(self, name: str, value: Any) -> None:
 
     def call(self, function: str, *args: Any) -> Any:
         """
-        Calls a function in the worker process with the given arguments and
-        returns the result.
+        Call a function in the worker process with the given arguments and
+        return the result.
 
         The function must be accessible in the worker's global scope (either
         built-in or previously defined/imported).
@@ -236,7 +240,7 @@ def call(self, function: str, *args: Any) -> Any:
 
     def proxy(self, var: str, api: type, queue: str | None = None) -> Any:
         """
-        Creates a proxy object providing strongly typed access to a remote
+        Create a proxy object providing strongly typed access to a remote
         object in this service's worker process.
 
         Method calls on the proxy are transparently forwarded to the remote
@@ -518,7 +522,7 @@ def wait_for(self) -> "Task":
 
     def result(self) -> Any:
         """
-        Returns the result of this task.
+        Return the result of this task.
 
         This is a convenience method that returns outputs["result"].
         For tasks that return a single value (e.g., from an expression),

src/appose/shm.py

@@ -53,17 +53,15 @@ def __init__(self, name: str | None = None, create: bool = False, rsize: int = 0
         """
         Create a new shared memory block, or attach to an existing one.
 
-        :param name:
-            The unique name for the requested shared memory, specified as a
-            string. If create is True (i.e. a new shared memory block) and
-            no name is given, a novel name will be generated.
-        :param create:
-            Whether a new shared memory block is created (True)
-            or an existing one is attached to (False).
-        :param rsize:
-            Requested size in bytes. The true allocated size will be at least
-            this much, but may be rounded up to the next block size multiple,
-            depending on the running platform.
+        Args:
+            name: The unique name for the requested shared memory, specified as a
+                string. If create is True (i.e. a new shared memory block) and
+                no name is given, a novel name will be generated.
+            create: Whether a new shared memory block is created (True)
+                or an existing one is attached to (False).
+            rsize: Requested size in bytes. The true allocated size will be at least
+                this much, but may be rounded up to the next block size multiple,
+                depending on the running platform.
         """
         super().__init__(name=name, create=create, size=rsize)
         self.rsize: int = rsize
@@ -149,10 +147,12 @@ class NDArray:
     def __init__(self, dtype: str, shape: list[int], shm: SharedMemory | None = None):
         """
         Create an NDArray.
-        :param dtype: The type of the data elements; e.g. int8, uint8, float32, float64.
-        :param shape: The dimensional extents; e.g. a stack of 7 image planes
-                      with resolution 512x512 would have shape [7, 512, 512].
-        :param shm: The SharedMemory containing the array data, or None to create it.
+
+        Args:
+            dtype: The type of the data elements; e.g. int8, uint8, float32, float64.
+            shape: The dimensional extents; e.g. a stack of 7 image planes
+                with resolution 512x512 would have shape [7, 512, 512].
+            shm: The SharedMemory containing the array data, or None to create it.
         """
         self.dtype: str = dtype
         self.shape: list[int] = shape

src/appose/util/environment.py

@@ -12,7 +12,8 @@
 
 def env_vars(*keys: str) -> dict[str, str]:
     """
-    Retrieves the specified environment variables from the current process.
+    Retrieve the specified environment variables from the current process.
+
     Only variables that are set will be included in the returned map.
 
     Args:
@@ -32,7 +33,7 @@ def env_vars(*keys: str) -> dict[str, str]:
 
 def system_path() -> list[str]:
     """
-    Returns the current process's system PATH as a list of directory paths.
+    Return the current process's system PATH as a list of directory paths.
 
     This splits the PATH environment variable on the platform-specific separator
     (colon on Unix-like systems, semicolon on Windows).

src/appose/util/filepath.py

@@ -16,7 +16,7 @@
 
 def location(c: type) -> Path | None:
     """
-    Gets the path to the module file containing the given class/type.
+    Get the path to the module file containing the given class/type.
 
     Args:
         c: The class/type whose file path should be discerned.
@@ -239,7 +239,8 @@ def ensure_directory(file: Path) -> None:
 
 def appose_envs_dir() -> str:
     """
-    Gets the top-level directory for Appose-managed environments.
+    Get the top-level directory for Appose-managed environments.
+
     Defaults to ~/.local/share/appose but can be overridden by setting
     the APPOSE_ENVS_DIR environment variable.