ppqs 1.0__py3-none-any.whl

ppqs-1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: ppqs
+Version: 1.0
+Summary: Python project quick scripts
+Author-email: Karl Wette <karl.wette@anu.edu.au>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kwwette/ppqs
+Project-URL: Issues, https://github.com/kwwette/ppqs/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Dynamic: license-file
+
+# Python project quick scripts
+
+**Define simple development scripts in `pyproject.toml`**
+
+Developing a Python project usually involves many tasks: setting up, installing
+prerequisites, building, testing, cleaning up build products, etc. It can be
+difficult to remember which program to run to perform a given task for a given
+project, particularly when many different tools are being used.
+
+**ppqs** defines simple (*"quick"*) scripts in `pyproject.toml`, and provides a
+command-line utility -- `ppqs` -- to run them. In this way **ppqs** hides the
+details of whatever dependency/virtual environment manager, build front-end,
+test harness, etc. the project uses behind a simple interface.
+
+Here is an example of **ppqs** being used for its own project:
+
+```bash
+$ ppqs --help
+Quick scripts for Python project: ppqs
+
+Usage: ppqs {init,lint,build,test,clean}
+
+Scripts:
+  init   Initialise project
+  lint   Perform linting checks
+  build  Build project
+  test   Run tests
+  clean  Clean up build files
+```
+
+Scripts are always run from the project root directory, i.e. the directory
+containing `pyproject.toml`. `ppqs` traverses back through parent directories
+until it finds the root directory. It is therefore safe to run `ppqs` from any
+sub-directory within the project directory tree.
+
+## Script definition in `pyproject.toml`
+
+**ppqs** scripts are simple lists of commands which are run in sequence. If a
+command errors, the remainder of the script is aborted.
+
+Scripts are defined in `pyproject.toml` under the `[tool.ppqs.scripts]`
+section. Script names may contain only lowercase letters (`[a-z]`) and dashes
+(`-`). Scripts may be single or multi-line strings: commands are separated by
+newlines, and command arguments are separated by spaces.
+
+```toml
+[tool.ppqs.scripts]
+init = "command"
+lint = """
+command
+"""
+build = """
+command1 -v
+command2 -q
+"""
+```
+
+Scripts may also be defined as lists of lists, i.e. a list of commands, each of
+which is a list of arguments:
+
+```toml
+[tool.ppqs.scripts]
+test = [
+    ["command1"],
+    ["command2", "-vv"],
+]
+clean = [
+    ["command"],
+]
+```
+
+If a script contains an ellipsis (`...`) it is replaced with any additional
+arguments passed to `ppqs`. For example, the following script:
+
+```toml
+[tool.ppqs.scripts]
+print-something = "echo ..."
+```
+
+may be run as
+```bash
+$ ppqs print-something Hi
+Hi
+```
+
+Scripts may also be defined in their own section, which permit a few options:
+
+```toml
+[tool.ppqs.scripts.init]
+description = "Initialise project"
+print_header = true
+script = """
+command
+"""
+
+[tool.ppqs.scripts.build]
+# default description = "Run build script"
+# default print_header = false
+script = [
+    ["command1", "-v"],
+    ["command2", "-q"],
+]
+"""
+
+```
+
+where:
+
+* `description` [optional]: description of the script which appears in `ppqs
+  --help`. Default is `Run {name} script` where `name` is the script name.
+
+* `print_header` [optional]: If true, print a header before running each command
+  in the script. The header consists of the command to be run, centred on the
+  console and padded with `*`s. Default is false.
+
+Commands are *not* parsed to the shell, so e.g. wildcards are not expanded. If
+the features of a shell script are needed (wildcards, conditional statements,
+etc.), one can write a helper script, e.g. `scripts/lots-to-do.py`, which may
+then be called by `ppqs` as:
+
+```toml
+[tool.ppqs.scripts]
+lots-to-do = [["python", "scripts/lots-to-do.py"]]
+```

ppqs-1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ppqs-1.0.dist-info/licenses/LICENSE,sha256=eGcCXI2x3rBIZftKoQK1TGM8N0zvxcO1BST6hmUQUEw,1058
+py_proj_quick_scripts/__init__.py,sha256=MFkaVsUeR-hEe_nJU66dHyRYW5psE-V3FAilmty0wT8,8276
+ppqs-1.0.dist-info/METADATA,sha256=BL_M0pKpddsD4-D0sdO1Nr_nKvmUbdFCKPOfBSkzKzQ,3959
+ppqs-1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ppqs-1.0.dist-info/entry_points.txt,sha256=P-MsiSlLTTFGJD6XLQmARAch2MBh9NA0rtwKSa3Ro8Q,51
+ppqs-1.0.dist-info/top_level.txt,sha256=SMckK8lcW3XcfBV0cZ2JTZW5lKt58wwlILx8di4XbfA,22
+ppqs-1.0.dist-info/RECORD,,

ppqs-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ppqs-1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ppqs = py_proj_quick_scripts:cli

ppqs-1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2025 Karl Wette
+
+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.

ppqs-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+py_proj_quick_scripts

py_proj_quick_scripts/__init__.py

@@ -0,0 +1,281 @@
+import os
+import re
+import shutil
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+if sys.version_info >= (3, 11):  # pragma: no cover
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+__author__ = "Karl Wette"
+__version__ = "1.0"
+
+
+class MissingPyProjectError(Exception):
+    """
+    Raise if 'pyproject.toml' could not be found.
+    """
+
+    pass
+
+
+class InvalidScriptError(Exception):
+    """
+    Raise for invalid 'pyproject.toml' script errors.
+    """
+
+    def __init__(self, pyproject_path, msg):
+        self.pyproject_path = pyproject_path
+        self.msg = msg
+        super().__init__(self.msg)
+
+    def __str__(self):
+        return f"{self.pyproject_path}: {self.msg}"
+
+
+def find_pyproject():
+    """
+    Look for pyproject.toml in current/parent directories.
+    """
+
+    # Start in the current directory
+    current_dir = starting_dir = Path.cwd()
+
+    # Traverse down directory parents until just before root
+    while len(current_dir.parts) > 1:
+
+        # Stop when user no longer has write access to parent directory
+        # - excludes any pyproject.toml in home directory, /tmp, etc.
+        if not os.access(current_dir.parent, os.W_OK):
+            break
+
+        # If pyproject.toml is in this directory, return its path
+        pyproject_path = current_dir / "pyproject.toml"
+        if os.access(pyproject_path, os.F_OK | os.R_OK):
+            return pyproject_path
+
+        # Look in parent directory
+        current_dir = current_dir.parent
+
+    msg = f"'pyproject.toml' could not be found in '{starting_dir}' or its parent directories"
+    raise MissingPyProjectError(msg)
+
+
+def parse_scripts(pyproject_path):
+    """
+    Parse scripts from pyproject.toml.
+    """
+
+    # Read pyproject.toml
+    pyproject_toml = tomllib.load(pyproject_path.open("rb"))
+    project_name = pyproject_toml["project"]["name"]
+    try:
+        scripts_toml = pyproject_toml["tool"]["ppqs"]["scripts"]
+    except KeyError:
+        scripts_toml = {}
+    if not scripts_toml:
+        msg = "does not contain a non-empty '[tool.ppqs.scripts]' section"
+        raise InvalidScriptError(pyproject_path, msg)
+
+    # Parse scripts
+    scripts = {}
+    for script_name, script_toml in scripts_toml.items():
+
+        # Check name
+        if script_name.startswith("-"):
+            msg = "script name '{script_name}' may not start with '-'"
+            raise InvalidScriptError(pyproject_path, msg)
+        invalid_chars = re.sub(r"[a-z-]", "", script_name)
+        if len(invalid_chars) > 0:
+            msg = f"script name '{script_name}' may not contain characters '{invalid_chars}'"
+            raise InvalidScriptError(pyproject_path, msg)
+
+        # Create default description
+        script_description = f"Run {script_name} script"
+        script_print_header = False
+        script_commands_toml = script_toml
+
+        if isinstance(script_toml, dict):
+
+            # Check for invalid keys
+            invalid_keys = [
+                k
+                for k in script_toml.keys()
+                if k not in ("description", "print_header", "script")
+            ]
+            if len(invalid_keys) > 0:
+                invalid_keys_str = "', '".join(invalid_keys)
+                msg = (
+                    f"script '{script_name}' may not contain keys '{invalid_keys_str}'"
+                )
+                raise InvalidScriptError(pyproject_path, msg)
+
+            script_description = str(script_toml.get("description", script_description))
+            script_print_header = bool(
+                script_toml.get("print_header", script_print_header)
+            )
+            script_commands_toml = script_toml["script"]
+
+        msg = f"script '{script_name}' may be either a string or a list of lists"
+        if isinstance(script_commands_toml, str):
+
+            # Parse a script as a string
+            script_commands = [
+                line.split()
+                for line in script_commands_toml.splitlines()
+                if len(line.strip()) > 0
+            ]
+
+        elif isinstance(script_commands_toml, list):
+
+            # Parse a script as a list of lists
+            script_commands = []
+            for line in script_commands_toml:
+                if not isinstance(line, list):
+                    raise InvalidScriptError(pyproject_path, msg)
+                script_line = []
+                for arg in line:
+                    if isinstance(arg, list):
+
+                        # List arguments are treated as paths
+                        arg_path = Path(*arg)
+                        if arg_path.is_absolute():
+                            msg2 = f"path argument '{arg_path}' must be a relative path"
+                            raise InvalidScriptError(pyproject_path, msg2)
+
+                        script_line.append(str(arg_path))
+
+                    else:
+                        script_line.append(arg)
+
+                script_commands.append(script_line)
+
+        else:
+            raise InvalidScriptError(pyproject_path, msg)
+
+        scripts[script_name] = {
+            "description": script_description,
+            "print_header": script_print_header,
+            "commands": script_commands,
+        }
+
+    return project_name, scripts
+
+
+def print_help(project_name, scripts):
+    """
+    Print help.
+    """
+    script_names = ",".join(scripts.keys())
+    max_script_name_len = max(len(script_name) for script_name in scripts)
+    list_of_scripts = "\n".join(
+        "  "
+        + script_name.ljust(max_script_name_len, " ")
+        + "  "
+        + script["description"][0].upper()
+        + script["description"][1:]
+        for script_name, script in scripts.items()
+    )
+    print(
+        textwrap.dedent(
+            f"""\
+            Quick scripts for Python project: {project_name}
+
+            Usage: ppqs {{{script_names}}}
+
+            Scripts:
+            """
+        )
+        + list_of_scripts
+    )
+
+
+def run_script(script, argv, cwd):
+    """
+    Run a script.
+    """
+    col_width = shutil.get_terminal_size().columns
+    for command in script["commands"]:
+        cmd = []
+
+        # Replace "..." in command with arguments
+        for arg in command:
+            if arg == "...":
+                cmd.extend(argv)
+            else:
+                cmd.append(arg)
+
+        # Print header
+        if script["print_header"]:
+            cmd_str = " ".join(cmd)
+            print(f" {cmd_str} ".center(col_width, "*"))
+
+        # Run command
+        retn = subprocess.run(cmd, stdin=subprocess.DEVNULL, shell=False, cwd=cwd)
+        if retn.returncode != 0:
+            raise SystemExit(retn.returncode)
+
+
+def regular_cli(argv):
+    """
+    Parse regular command line.
+    """
+
+    # Parse scripts
+    pyproject_path = find_pyproject()
+    project_name, scripts = parse_scripts(pyproject_path)
+
+    # Parse command line
+    if argv[0] in ("-h", "-help", "--help"):
+        print_help(project_name, scripts)
+        raise SystemExit(1)
+    elif argv[0] not in scripts:
+        msg = f"unknown script '{argv[0]}'"
+        raise InvalidScriptError(pyproject_path, msg)
+    else:
+        cwd = pyproject_path.parent
+        run_script(scripts[argv[0]], argv[1:], cwd)
+
+
+def cli(*argv):
+    """
+    Parse command line.
+    """
+
+    argv = [str(a) for a in (argv or sys.argv[1:] or ["--help"])]
+
+    if argv[0] == "--bash-completion":  # pragma: no cover
+
+        # Perform Bash completion
+        # - suppress any error output
+        try:
+            pyproject_path = find_pyproject()
+            _, scripts = parse_scripts(pyproject_path)
+            line = os.environ["COMP_LINE"]
+            words = line.split()
+            if line.endswith(" ") and len(words) == 1:
+
+                # Complete full script name, e.g.:
+                # $ ppqs <TAB><TAB>
+                for script_name in scripts:
+                    print(script_name)
+
+            if not line.endswith(" ") and len(words) == 2:
+
+                # Complete partial script name, e.g.:
+                # $ ppqs nam<TAB>
+                for script_name in scripts:
+                    if script_name.startswith(words[-1]):
+                        print(script_name)
+
+        except Exception:
+            pass
+
+    else:
+
+        # Parse regular command line
+        regular_cli(argv)