ppqs 1.0__tar.gz

ppqs-1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,124 @@
+# 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/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ppqs"
+version = "1.0"
+description = "Python project quick scripts"
+authors = [
+    { name = "Karl Wette", email = "karl.wette@anu.edu.au" },
+]
+requires-python = ">=3.9"
+dependencies = [
+    "tomli>=1.1.0; python_version<'3.11'"
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/kwwette/ppqs"
+Issues = "https://github.com/kwwette/ppqs/issues"
+
+[project.scripts]
+ppqs = "py_proj_quick_scripts:cli"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "--cov=py_proj_quick_scripts --cov-report=term-missing --cov-fail-under=100"
+testpaths = ["test"]
+
+[tool.ppqs.scripts.init]
+description = "Initialise project"
+print_header = true
+script = """
+python -m pip install -r requirements-dev.txt
+pre-commit install
+python -m pip install -e .
+"""
+
+[tool.ppqs.scripts.lint]
+description = "Perform linting checks"
+script = """
+pre-commit run -a
+"""
+
+[tool.ppqs.scripts.build]
+description = "Build project"
+script = """
+git clean -Xdf
+python -m build
+"""
+
+[tool.ppqs.scripts.test]
+description = "Run tests"
+script = """
+pytest ...
+"""
+
+[tool.ppqs.scripts.clean]
+description = "Clean up build files"
+script = "git clean -Xdf"

ppqs-1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ppqs-1.0/src/ppqs.egg-info/PKG-INFO

@@ -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/src/ppqs.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/ppqs.egg-info/PKG-INFO
+src/ppqs.egg-info/SOURCES.txt
+src/ppqs.egg-info/dependency_links.txt
+src/ppqs.egg-info/entry_points.txt
+src/ppqs.egg-info/requires.txt
+src/ppqs.egg-info/top_level.txt
+src/py_proj_quick_scripts/__init__.py
+test/test_cli.py
+test/test_find_pyproject.py
+test/test_parse_scripts.py

ppqs-1.0/src/ppqs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ppqs-1.0/src/ppqs.egg-info/entry_points.txt

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

ppqs-1.0/src/ppqs.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[:python_version < "3.11"]
+tomli>=1.1.0

ppqs-1.0/src/ppqs.egg-info/top_level.txt

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

ppqs-1.0/src/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)

ppqs-1.0/test/test_cli.py

@@ -0,0 +1,73 @@
+import pytest
+
+from py_proj_quick_scripts import InvalidScriptError, cli
+
+from . import in_dir, write_file
+
+
+@pytest.fixture
+def pyproject_path(tmp_path):
+    """
+    Write pyproject.toml for command-line tests.
+    """
+
+    pyproject_path = tmp_path / "pyproject.toml"
+    pyproject_toml = """
+    [project]
+    name = "test"
+    [tool.ppqs.scripts.exit]
+    description = "Exits"
+    print_header = true
+    script = "python -c 'import sys; sys.exit(1)'"
+    [tool.ppqs.scripts.echo]
+    description = "Echoes"
+    script = [
+        ["python", "-c", "import sys; print(*sys.argv[1:])", "..."],
+    ]
+    """
+
+    write_file(pyproject_path, pyproject_toml)
+
+    return pyproject_path
+
+
+def test_help(pyproject_path):
+    """
+    Test command line help.
+    """
+
+    with in_dir(pyproject_path.parent):
+        with pytest.raises(SystemExit):
+            cli("--help")
+
+
+def test_notest(pyproject_path):
+    """
+    Test a non-existent test.
+    """
+
+    with in_dir(pyproject_path.parent):
+        with pytest.raises(InvalidScriptError):
+            cli("notest")
+
+
+def test_exit(pyproject_path):
+    """
+    Test exit() script.
+    """
+
+    with in_dir(pyproject_path.parent):
+        with pytest.raises(SystemExit):
+            cli("exit")
+
+
+def test_echo(pyproject_path, capfd):
+    """
+    Test echo() script.
+    """
+
+    with in_dir(pyproject_path.parent):
+        cli("echo", "Hello")
+        captured = capfd.readouterr()
+        assert captured.out == "Hello\n"
+        assert captured.err == ""

ppqs-1.0/test/test_find_pyproject.py

@@ -0,0 +1,30 @@
+import pytest
+
+from py_proj_quick_scripts import (
+    MissingPyProjectError,
+    find_pyproject,
+)
+
+from . import in_dir, write_file
+
+
+def test_find_pyproject(tmp_path):
+    """
+    Test find_pyproject().
+    """
+
+    with in_dir(tmp_path):
+        with pytest.raises(MissingPyProjectError):
+            find_pyproject()
+
+    pyproject_path = tmp_path / "pyproject.toml"
+    write_file(pyproject_path, "[tool.ppqs.scripts]")
+
+    with in_dir(pyproject_path.parent):
+        assert find_pyproject() == pyproject_path
+
+    with in_dir(pyproject_path.parent / "subdir"):
+        assert find_pyproject() == pyproject_path
+
+    with in_dir(pyproject_path.parent / "subdir" / "subdir"):
+        assert find_pyproject() == pyproject_path

ppqs-1.0/test/test_parse_scripts.py

@@ -0,0 +1,248 @@
+from contextlib import nullcontext
+from pathlib import Path
+
+import pytest
+
+from py_proj_quick_scripts import (
+    InvalidScriptError,
+    parse_scripts,
+)
+
+from . import in_dir, write_file
+
+
+@pytest.mark.parametrize(
+    "script_toml,expectation",
+    [
+        pytest.param(
+            """
+            [some.section]
+            """,
+            pytest.raises(
+                InvalidScriptError, match=r"non-empty '\[tool.ppqs.scripts\]' section"
+            ),
+            id="missing section",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            """,
+            pytest.raises(
+                InvalidScriptError, match=r"non-empty '\[tool.ppqs.scripts\]' section"
+            ),
+            id="empty section",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            init = 123
+            """,
+            pytest.raises(
+                InvalidScriptError, match="either a string or a list of lists"
+            ),
+            id="wrong type",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            init = "pip install -r requirements.txt"
+            """,
+            nullcontext(
+                {
+                    "init": {
+                        "description": "Run init script",
+                        "print_header": False,
+                        "commands": [["pip", "install", "-r", "requirements.txt"]],
+                    }
+                }
+            ),
+            id="string script",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            init = '''
+            pip install -r requirements.txt
+            pre-commit install
+            '''
+            """,
+            nullcontext(
+                {
+                    "init": {
+                        "description": "Run init script",
+                        "print_header": False,
+                        "commands": [
+                            ["pip", "install", "-r", "requirements.txt"],
+                            ["pre-commit", "install"],
+                        ],
+                    }
+                }
+            ),
+            id="multi-line string script",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            -invalid-name = "something"
+            """,
+            pytest.raises(InvalidScriptError, match="may not start with '-'"),
+            id="script name starts with dash",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            name_contains-2-invalid-characters = "something"
+            """,
+            pytest.raises(InvalidScriptError, match="may not contain characters '_2'"),
+            id="script name invalid characters",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            some-script = { description = "something", another_key = "invalid"}
+            """,
+            pytest.raises(
+                InvalidScriptError, match="may not contain keys 'another_key'"
+            ),
+            id="script invalid keys",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts.init]
+            description = "Initialise project"
+            script = "pip install -r requirements.txt"
+            """,
+            nullcontext(
+                {
+                    "init": {
+                        "description": "Initialise project",
+                        "print_header": False,
+                        "commands": [["pip", "install", "-r", "requirements.txt"]],
+                    }
+                }
+            ),
+            id="string script with description",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts.init]
+            description = "Initialise project"
+            script = [
+                "some_commands",
+            ]
+            """,
+            pytest.raises(
+                InvalidScriptError, match="either a string or a list of lists"
+            ),
+            id="script is not list of lists",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            init = [
+                ["pip", "install", "-r", "requirements.txt"],
+            ]
+            """,
+            nullcontext(
+                {
+                    "init": {
+                        "description": "Run init script",
+                        "print_header": False,
+                        "commands": [["pip", "install", "-r", "requirements.txt"]],
+                    }
+                }
+            ),
+            id="list script",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts.init]
+            description = "Initialise project"
+            print_header = true
+            script = [
+                ["pip", "install", "-r", "requirements.txt"],
+            ]
+            """,
+            nullcontext(
+                {
+                    "init": {
+                        "description": "Initialise project",
+                        "print_header": True,
+                        "commands": [["pip", "install", "-r", "requirements.txt"]],
+                    }
+                }
+            ),
+            id="list script with description",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts.init]
+            description = "Initialise project"
+            script = [
+                ["pip", "install", "-r", "requirements.txt"],
+                ["pre-commit", "install"],
+            ]
+            """,
+            nullcontext(
+                {
+                    "init": {
+                        "description": "Initialise project",
+                        "print_header": False,
+                        "commands": [
+                            ["pip", "install", "-r", "requirements.txt"],
+                            ["pre-commit", "install"],
+                        ],
+                    }
+                }
+            ),
+            id="multi-line list script with description",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            paths = [
+                ["echo", ["/tmp"]],
+            ]
+            """,
+            pytest.raises(InvalidScriptError, match="must be a relative path"),
+            id="list script with absolute path",
+        ),
+        pytest.param(
+            """
+            [tool.ppqs.scripts]
+            paths = [
+                ["echo", ["a", "b"]],
+            ]
+            """,
+            nullcontext(
+                {
+                    "paths": {
+                        "description": "Run paths script",
+                        "print_header": False,
+                        "commands": [["echo", str(Path("a", "b"))]],
+                    }
+                }
+            ),
+            id="list script with relative path",
+        ),
+    ],
+)
+def test_parse_scripts(tmp_path, script_toml, expectation):
+    """
+    Test parse_scripts().
+    """
+
+    pyproject_path = tmp_path / "pyproject.toml"
+    pyproject_toml = f"""
+    [project]
+    name = "test"
+    {script_toml}
+    """
+
+    write_file(pyproject_path, pyproject_toml)
+
+    with in_dir(tmp_path):
+        with expectation as expected_result:
+            project_name, scripts = parse_scripts(pyproject_path)
+            assert project_name == "test"
+            assert scripts == expected_result