runall 0.1.0__py3-none-any.whl

runall/__init__.py

@@ -0,0 +1,20 @@
+"""Run shell commands over a set of input files with a terminal progress display.
+
+The ``runall`` package lets a user register Python functions with the
+:func:`runthat` decorator. Each registered function receives the path of an
+input file and returns a shell command. The command is executed for every
+input file that matches a glob pattern, while a Textual-based terminal user
+interface (:class:`runall.tui.RunAllApp`) displays one progress bar per
+registered function and a running list of the processed files.
+
+Public names:
+    CONFIG: A default configuration dictionary.
+    discover_input_files: Resolves the input files described by a configuration.
+    runthat: Decorator that registers a function in a configuration.
+"""
+
+from .config import CONFIG
+from .processor import discover_input_files
+from .tui import runthat
+
+__all__ = ["CONFIG", "discover_input_files", "runthat"]

runall/config.py

@@ -0,0 +1,28 @@
+"""Default configuration for the ``runall`` package.
+
+A configuration is a plain dictionary. The same structure may be defined by
+the user and passed to :func:`runall.tui.runthat` and
+:class:`runall.tui.RunAllApp`.
+"""
+
+CONFIG = {
+    "runthat": {},
+    "input_dir": "instances/ht0_*.txt",
+    "output_dir": "output",
+    "output_preffix": "out_",
+    "output_header": "execucao,arquivo",
+    "err_dir": "err",
+}
+"""Default configuration dictionary.
+
+Keys:
+    runthat: Registry that maps function names to the wrapped callables. It is
+        populated by the :func:`runall.tui.runthat` decorator.
+    input_dir: Glob pattern that selects the input files.
+    output_dir: Directory that receives the standard output of each command.
+    output_preffix: Prefix of every output file name. The key name keeps its
+        historical spelling.
+    output_header: Header line written once at the top of each new output file.
+    err_dir: Directory that receives the executed commands and their standard
+        error output.
+"""

runall/processor.py

@@ -0,0 +1,22 @@
+"""Discovery of the input files that ``runall`` processes."""
+
+import glob
+
+from .config import CONFIG
+
+
+def discover_input_files(config: dict | None = None) -> list[str]:
+    """Return the input files that match the configured glob pattern.
+
+    Args:
+        config: Configuration dictionary whose ``"input_dir"`` entry holds the
+            glob pattern. When ``None``, the default
+            :data:`runall.config.CONFIG` is used.
+
+    Returns:
+        The matching paths in lexicographic order. The list is empty when no
+        file matches the pattern.
+    """
+    if config is None:
+        config = CONFIG
+    return sorted(glob.glob(config["input_dir"]))

runall/tui.py

@@ -0,0 +1,280 @@
+"""Command registration and terminal user interface for ``runall``.
+
+This module provides the :func:`runthat` decorator, which registers functions
+that build shell commands, and :class:`RunAllApp`, a Textual application that
+runs every registered function over every input file while it displays
+progress.
+"""
+
+import asyncio
+import functools
+import pathlib
+import subprocess
+
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.widgets import Label, ProgressBar
+
+# from .config import CONFIG
+from .processor import discover_input_files
+
+
+def _output_path(config: dict, label: str) -> pathlib.Path:
+    """Build the path of the output file for a registered function.
+
+    Args:
+        config: Configuration dictionary.
+        label: Name of the registered function.
+
+    Returns:
+        The path ``<output_dir>/<output_preffix><label>.csv``.
+    """
+    return pathlib.Path(config["output_dir"]) / f"{config['output_preffix']}{label}.csv"
+
+
+def _err_path(config: dict, label: str) -> pathlib.Path:
+    """Build the path of the error log file for a registered function.
+
+    Args:
+        config: Configuration dictionary.
+        label: Name of the registered function.
+
+    Returns:
+        The path ``<err_dir>/<output_preffix><label>.csv``.
+    """
+    return pathlib.Path(config["err_dir"]) / f"{config['output_preffix']}{label}.csv"
+
+
+def _redirect_output(
+    config: dict, label: str, proc: subprocess.CompletedProcess, cmd: str
+) -> None:
+    """Persist the result of a command to the output and error files.
+
+    The standard output is appended to the output file. When that file does
+    not exist yet, it is created with the configured header line first. The
+    executed command and its standard error output are appended to the error
+    file. Missing directories are created as needed.
+
+    Args:
+        config: Configuration dictionary.
+        label: Name of the registered function that produced the command.
+        proc: Completed process whose streams are persisted.
+        cmd: Shell command that was executed.
+    """
+    out_path = _output_path(config, label)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    if not out_path.exists():
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(f"{config['output_header']}\n")
+    with open(out_path, "a", encoding="utf-8") as f:
+        f.write(proc.stdout)
+
+    err_path = _err_path(config, label)
+    err_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(err_path, "a", encoding="utf-8") as f:
+        f.write(f"$ {cmd}\n")
+        if proc.stderr:
+            f.write(proc.stderr)
+
+
+def runthat(config: dict):
+    """Create a decorator that registers a command-building function.
+
+    The decorated function receives the path of an input file and must return
+    a shell command as a string. The returned wrapper executes that command
+    through the shell, writes its output through :func:`_redirect_output`, and
+    returns the completed process. The wrapper is stored in
+    ``config["runthat"]`` under the name of the decorated function.
+
+    The command runs with ``shell=True``. Input file names are therefore
+    interpolated into a shell command line, and the function must quote them
+    when they may contain special characters. The exit status of the command
+    is recorded in the returned process but is not treated as an error.
+
+    Args:
+        config: Configuration dictionary. It must contain a ``"runthat"``
+            dictionary, which receives the registered wrapper.
+
+    Returns:
+        A decorator that registers a function and returns its wrapper.
+    """
+
+    def decorator(func):
+        """Wrap and register a command-building function.
+
+        Args:
+            func: Function that maps an input file path to a shell command.
+
+        Returns:
+            The wrapper that executes the command for a given input file.
+        """
+
+        @functools.wraps(func)
+        def wrapper(filename: str) -> subprocess.CompletedProcess:
+            """Execute the command built for an input file.
+
+            Args:
+                filename: Path of the input file.
+
+            Returns:
+                The completed process with captured text output.
+            """
+            cmd = func(filename)
+            proc = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+            _redirect_output(config, func.__name__, proc, cmd)
+            return proc
+
+        config["runthat"][func.__name__] = wrapper
+        return wrapper
+
+    return decorator
+
+
+CSS = """
+#ls {
+    height: 75%;
+    width: 90%;
+}
+
+#ls .fn-row {
+    height: 1;
+    padding: 0;
+    align: left middle;
+}
+
+#ls .fn-label {
+    width: 12;
+}
+
+#ls ProgressBar {
+    width: 1fr;
+}
+
+Bar > .bar--bar {
+    color: $primary;
+}
+
+Bar.running > .bar--bar {
+    color: #ffa500;
+}
+
+Bar.done > .bar--bar {
+    color: $success;
+}
+
+#li {
+    height: 15;
+    max-height: 25%;
+    margin: 0 1;
+    border: round $primary;
+    background: $surface;
+}
+
+#li Label {
+    padding: 0 1;
+}
+"""
+"""Textual stylesheet of the application.
+
+The progress bar of the function that is currently running is drawn in orange.
+"""
+
+
+class RunAllApp(App):
+    """Textual application that runs registered functions over input files.
+
+    The interface shows one progress bar per registered function and a scrolling
+    list of the input files in the order in which they are processed. For each
+    input file, every registered function runs in registration order. The
+    application exits when all files have been processed.
+
+    Attributes:
+        config: Configuration dictionary shared with the registered functions.
+        files: Input files to process. It is assigned when the application is
+            mounted.
+    """
+
+    TITLE = "RunAll"
+    CSS = CSS
+
+    def __init__(self, config: dict, **kwargs: object) -> None:
+        """Initialize the application.
+
+        Args:
+            config: Configuration dictionary. Its ``"runthat"`` entry holds the
+                registered functions and its ``"input_dir"`` entry selects the
+                input files.
+            **kwargs: Additional keyword arguments forwarded to
+                :class:`textual.app.App`.
+        """
+        super().__init__(**kwargs)
+        self.config = config
+
+    def compose(self) -> ComposeResult:
+        """Build the widget tree.
+
+        Yields:
+            One labeled progress bar for each registered function, followed by
+            a scrollable container that lists the processed files.
+        """
+        total = len(discover_input_files(self.config))
+        with Vertical(id="ls"):
+            for label in self.config["runthat"]:
+                with Horizontal(id=f"fn-row-{label}", classes="fn-row"):
+                    yield Label(label, classes="fn-label")
+                    yield ProgressBar(
+                        total=total,
+                        show_percentage=True,
+                        show_eta=False,
+                        id=f"bar-{label}",
+                    )
+        with VerticalScroll(id="li"):
+            yield Label("")
+
+    def on_mount(self) -> None:
+        """Start processing once the interface is mounted.
+
+        The application exits with a message, without processing anything,
+        when no function is registered or no input file matches the configured
+        pattern.
+        """
+        if not self.config["runthat"]:
+            self.exit(message="Nenhuma função registrada com @runthat.")
+            return
+        self.files = discover_input_files(self.config)
+        if not self.files:
+            self.exit(message=f"Nenhum arquivo encontrado: {self.config['input_dir']}")
+            return
+        self.run_worker(self.process_all())
+
+    async def process_all(self) -> None:
+        """Run every registered function over every input file.
+
+        Files are processed sequentially. For each file, the registered
+        functions run one after another in a worker thread so that the
+        interface stays responsive. The progress bar of the running function is
+        highlighted and advances when the function finishes. The application
+        exits after the last file.
+        """
+        total = len(self.files)
+        for index, filename in enumerate(self.files, start=1):
+            await self._add_file_line(index, total, filename)
+            for label in self.config["runthat"]:
+                pb = self.query_one(f"#bar-{label}", ProgressBar)
+                bar = pb.query_one("#bar")
+                bar.set_class(True, "running")
+                await asyncio.to_thread(self.config["runthat"][label], filename)
+                bar.set_class(False, "running")
+                pb.advance(1)
+        self.exit(message="Processamento concluído.")
+
+    async def _add_file_line(self, index: int, total: int, filename: str) -> None:
+        """Append a line for the file being processed to the file list.
+
+        Args:
+            index: One-based position of the file.
+            total: Total number of input files.
+            filename: Path of the file.
+        """
+        line = Label(f"[{index}/{total}] {filename}")
+        await self.query_one("#li", VerticalScroll).mount(line)

runall-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: runall
+Version: 0.1.0
+Summary: Run functions registered by @runthat decorator with a set of progress bars.
+Project-URL: Homepage, https://github.com/tavaresneto/pyrunall
+Project-URL: Repository, https://github.com/tavaresneto/pyrunall
+Project-URL: Issues, https://github.com/tavaresneto/pyrunall/issues
+Author: Roberto Fernandes Tavares Neto
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: textual>=8.2.8
+Description-Content-Type: text/markdown
+
+# runall
+
+`runall` is a Python package that runs shell commands over a set of input files
+and displays the progress in a terminal user interface (TUI). Commands are
+declared as ordinary Python functions registered with the `@runthat` decorator.
+For every function, the interface shows a progress bar (the bar of the function
+that is currently running is highlighted in orange) and a scrolling list of the
+files that have been processed.
+
+## Features
+
+- Registers any number of command-building functions with a single decorator.
+- Selects input files with a glob pattern.
+- Displays one progress bar per function and a running list of processed files.
+- Writes the standard output of every command to a CSV file per function.
+- Logs each executed command and its standard error output to a separate file.
+
+## Requirements
+
+- Python 3.10 or later
+- [Textual](https://textual.textualize.io/) 8.2.8 or later (installed automatically)
+- [uv](https://docs.astral.sh/uv/) (recommended for development)
+
+## Installation
+
+```sh
+pip install runall
+```
+
+```sh
+uv add runall
+```
+
+## Usage
+
+1. Create a configuration dictionary (see [Configuration](#configuration)).
+2. Decorate one or more functions with `@runthat(config=config)`. Each function
+   receives the path of an input file and returns the shell command to execute.
+3. Start the interface with `RunAllApp(config).run()`.
+
+For every input file, `runall` executes each registered function in the order in
+which it was defined. The commands run sequentially.
+
+### Example
+
+The complete example below is available in `examples/demo.py`. It registers three
+functions that each wait five seconds and then print one line:
+
+```python
+# from runall.config import CONFIG
+from runall.tui import RunAllApp, runthat
+
+config = {
+    "runthat": {},
+    "input_dir": "instances/ht0_*.txt",
+    "output_dir": "output",
+    "output_preffix": "out_",
+    "output_header": "execucao,arquivo",
+    "err_dir": "err",
+}
+
+@runthat(config=config)
+def exec1(filename: str) -> str:
+    return f'sleep 5;echo "[1] {filename}"'
+
+
+@runthat(config=config)
+def exec2(filename: str) -> str:
+    return f'sleep 5;echo "[2] {filename}"'
+
+
+@runthat(config=config)
+def exec3(filename: str) -> str:
+    return f'sleep 5;echo "[3] {filename}"'
+
+
+def main() -> None:
+    RunAllApp(config).run()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+Run it from the repository root, so that the relative paths in the configuration
+resolve correctly:
+
+```sh
+uv run python examples/demo.py
+```
+
+## Configuration
+
+The configuration is a plain dictionary with the following keys:
+
+| Key              | Description                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| `runthat`        | Registry of decorated functions. Start it as an empty dictionary; `@runthat` fills it in.    |
+| `input_dir`      | Glob pattern that selects the input files, for example `instances/ht0_*.txt`.                |
+| `output_dir`     | Directory that receives the standard output of each function.                                |
+| `output_preffix` | Prefix of every output file name. The key keeps its original spelling.                       |
+| `output_header`  | Header line written once at the top of each newly created output file.                       |
+| `err_dir`        | Directory that receives the executed commands and their standard error output.               |
+
+A default configuration is also available as `runall.CONFIG`.
+
+## Output files
+
+For a function named `exec1` and the configuration above, `runall` writes:
+
+- `output/out_exec1.csv`: the header line followed by the standard output of every
+  execution of `exec1`.
+- `err/out_exec1.csv`: for every execution, the line `$ <command>` followed by
+  the standard error output of the command, if any.
+
+Both files are opened in append mode, so results accumulate across runs. Remove
+the output directories before a run to start from a clean state. Commands should
+print lines that match the columns of `output_header`.
+
+## Security considerations
+
+Commands are executed through the shell (`shell=True`), and the file name is
+inserted into the command string that your function returns. Quote file names
+(for example with `shlex.quote`) if they may contain spaces or shell
+metacharacters, and never register commands built from untrusted input.
+
+The exit status of a command is not treated as an error: a failing command is
+recorded in the error log and processing continues with the next command.
+
+## Project layout
+
+```text
+src/runall/
+├── __init__.py    Public API: CONFIG, discover_input_files, runthat
+├── config.py      Default configuration
+├── processor.py   Input file discovery
+└── tui.py         The @runthat decorator and the RunAllApp interface
+examples/
+└── demo.py        Complete usage example
+instances/         Sample input files used by the example
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
+for details.

runall-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+runall/__init__.py,sha256=8jbxNNSIvsT0-T-hlXxhAGYlviiqnLLR5SdxHdchqiw,885
+runall/config.py,sha256=mi0h46cIIDtf7TSnmtmOlqe3PGPCG-GU2xIHxUSd3-A,1024
+runall/processor.py,sha256=CwC4DWn_Fl5g1Gk_DhwkW-v1OP28C0fM_JxBB6No0Ck,665
+runall/tui.py,sha256=GjtBhPKwghBbePDRr1it6HCtE8ZHwOKcgpTgPTL3CcA,9242
+runall-0.1.0.dist-info/METADATA,sha256=fJ7iQzIk0YpkiCGeihk-YLWcY1ku25aoftkPfrnqS5Q,5615
+runall-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+runall-0.1.0.dist-info/licenses/LICENSE,sha256=Ty-96cRm7x4TchIZBW3ES6B_1OC8YX-32EfqozKmL5Q,1087
+runall-0.1.0.dist-info/RECORD,,

runall-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

runall-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberto Fernandes Tavares Neto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.