pyallel 2.0.5__tar.gz → 2.1.0__tar.gz

{pyallel-2.0.5 → pyallel-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyallel
-Version: 2.0.5
+Version: 2.1.0
 Summary: Run and handle the output of multiple executables in pyallel (as in parallel)
 Project-URL: Homepage, https://github.com/Danthewaann/pyallel
 Project-URL: Repository, https://github.com/Danthewaann/pyallel
@@ -39,7 +39,7 @@ pipx install pyallel
 Once installed, you can run `pyallel` to see usage information, like so:
 
 ```
-usage: pyallel [-h] [-t] [-n] [-V] [--colour {yes,no,auto}] [commands ...]
+usage: pyallel [-h] [-t] [-n] [-V] [--colour {yes,no,auto}] [--debug] [commands ...]
 
 run and handle the output of multiple executables in pyallel (as in parallel)
 
@@ -98,6 +98,7 @@ options:
   -V, --version         print version and exit
   --colour {yes,no,auto}
                         colour terminal output, defaults to "auto"
+  --debug               enable debug mode, which logs debug info to a "pyallel.log" file in the current directory
 ```
 
 Currently you can provide a variable number of `commands` to run to `pyallel`, like so:
@@ -158,7 +159,7 @@ pipx install uv && \
       before a given command can start)
 - [x] Add support to state how many lines a command can use for it's output in interactive mode
 - [x] Improve printing of output performance by only printing lines that have changed
-- [ ] Add a debug mode that logs debug information to a log file
+- [x] Add a debug mode that logs debug information to a log file
 - [ ] Maybe add support to allow the user to provide stdin for commands that request it
       (such as a REPL)
 - [ ] Add custom parsing of command output to support filtering for errors (like vim's

{pyallel-2.0.5 → pyallel-2.1.0}/README.md

@@ -21,7 +21,7 @@ pipx install pyallel
 Once installed, you can run `pyallel` to see usage information, like so:
 
 ```
-usage: pyallel [-h] [-t] [-n] [-V] [--colour {yes,no,auto}] [commands ...]
+usage: pyallel [-h] [-t] [-n] [-V] [--colour {yes,no,auto}] [--debug] [commands ...]
 
 run and handle the output of multiple executables in pyallel (as in parallel)
 
@@ -80,6 +80,7 @@ options:
   -V, --version         print version and exit
   --colour {yes,no,auto}
                         colour terminal output, defaults to "auto"
+  --debug               enable debug mode, which logs debug info to a "pyallel.log" file in the current directory
 ```
 
 Currently you can provide a variable number of `commands` to run to `pyallel`, like so:
@@ -140,7 +141,7 @@ pipx install uv && \
       before a given command can start)
 - [x] Add support to state how many lines a command can use for it's output in interactive mode
 - [x] Improve printing of output performance by only printing lines that have changed
-- [ ] Add a debug mode that logs debug information to a log file
+- [x] Add a debug mode that logs debug information to a log file
 - [ ] Maybe add support to allow the user to provide stdin for commands that request it
       (such as a REPL)
 - [ ] Add custom parsing of command output to support filtering for errors (like vim's

{pyallel-2.0.5 → pyallel-2.1.0}/benchmark_process.py

@@ -1,6 +1,4 @@
-"""
-Ad-hoc benchmark comparing Process's stdout reading approach against two
-scenarios:
+"""Ad-hoc benchmark comparing Process's stdout reading approach against two scenarios.
 
 1. A chatty command that produces a lot of output while it's running.
 2. A quick command that exits almost immediately, followed by a period of
@@ -26,9 +24,7 @@ def cpu_time() -> float:
     return usage.ru_utime + usage.ru_stime
 
 
-def run_scenario(
-    name: str, command: str, poll_seconds: float, extra_idle_seconds: float
-) -> None:
+def run_scenario(name: str, command: str, poll_seconds: float, extra_idle_seconds: float) -> None:
     process = Process(1, command)
 
     start_wall = time.perf_counter()
@@ -49,10 +45,7 @@ def run_scenario(
     end_wall = time.perf_counter()
     end_cpu = cpu_time()
 
-    print(
-        f"{name:12} wall={end_wall - start_wall:6.3f}s  "
-        f"cpu={end_cpu - start_cpu:6.3f}s  bytes={total_bytes}"
-    )
+    print(f"{name:12} wall={end_wall - start_wall:6.3f}s  cpu={end_cpu - start_cpu:6.3f}s  bytes={total_bytes}")
 
 
 def main() -> None:

pyallel-2.1.0/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "pyallel"
+version = "2.1.0"
+description = "Run and handle the output of multiple executables in pyallel (as in parallel)"
+authors = [{ name = "Daniel Black", email = "danielcrblack@gmail.com" }]
+requires-python = ">=3.8"
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "parallel",
+    "command",
+    "runner",
+    "executable",
+    "shell",
+    "terminal",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+]
+
+[project.urls]
+Homepage = "https://github.com/Danthewaann/pyallel"
+Repository = "https://github.com/Danthewaann/pyallel"
+
+[project.scripts]
+pyallel = "pyallel.main:entry_point"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.4.3,<8",
+    "mypy>=1.7.0,<2",
+    "pyinstaller==6.11.0",
+    "ruff>=0.15.20",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.mypy]
+strict = true
+show_error_codes = true
+
+[tool.pytest.ini_options]
+addopts = "-vvv"
+
+[tool.ruff]
+# Allow lines to be as long as 120 columns
+line-length = 120
+
+[tool.ruff.lint]
+# Ruff linting rules are listed within: https://beta.ruff.rs/docs/rules
+#
+# Globally enable all rules by default. We ignore ones we don't want below
+select = [
+    "ALL"
+]
+# Rules to ignore globally
+ignore = [
+    "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed
+    "BLE001",  # Do not catch blind exceptions
+    "B904",    # Within an except* clause, raise exceptions with raise ... from err or raise ... from None
+    "COM812",  # Trailing comma missing
+    "COM819",  # Trailing comma prohibited
+    "D1",      # pydocstyle: undocumented code
+    "D203",    # pydocstyle: 1 blank line required before class docstring
+    "D213",    # pydocstyle: Multi-line docstring summary should start at the second line
+    "D401",    # pydocstyle: First line of docstring should be in imperative mood
+    "D413",    # pydocstyle: Missing blank line after last section
+    "E501",    # Line too long
+    "EM",      # flake8-errmsg: https://docs.astral.sh/ruff/rules/#flake8-errmsg-em
+    "FIX002",  # Line contains TODO, consider resolving the issue
+    "PLR0912", # Too many branches
+    "S106",    # Possible hardcoded password assigned to argument
+    "S603",    # subprocess call: check for execution of untrusted input
+    "S604",    # Function call with shell=True parameter identified, security issue
+    "T20",     # flake8-print: https://docs.astral.sh/ruff/rules/#flake8-print-t20
+    "TD002",   # Missing author in TODO
+    "TRY003",  # Avoid specifying long messages outside the exception class
+    "TRY201",  # Use raise without specifying exception name
+    "TRY400",  # Use logging.exception instead of logging.error
+    "PLR0913", # Too many arguments in function definition (> 5)
+]
+
+# Rules to ignore on a per file basis
+[tool.ruff.lint.per-file-ignores]
+"**/{tests}/*" = [
+    "D",       # ignore pydocstyle docstring rules in tests
+    "FBT",     # flake8-boolean-trap: https://docs.astral.sh/ruff/rules/#flake8-boolean-trap-fbt
+    "INP001",  # File is part of an implicit namespace package. Add an __init__.py
+    "N801",    # Class name should use CapWords convention
+    "PLR0913", # Too many arguments in function definition
+    "PLR2004", # Magic value used in comparison, consider replacing with a constant variable
+    "PT019",   # Fixture without value is injected as parameter, use @pytest.mark.usefixtures instead
+    "S101",    # Use of assert detected
+    "S104",    # Possible binding to all interfaces
+    "SLF001",  # Private member accessed
+    "S108",    # Probable insecure usage of temporary file or directory
+    "S607",    # Starting a process with a partial executable path
+]
+
+# Linter plugin configurations
+#
+# From: https://docs.astral.sh/ruff/settings
+[tool.ruff.lint.flake8-tidy-imports]
+# Disallow all relative imports.
+ban-relative-imports = "all"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+force-wrap-aliases = true
+known-first-party = ["pizzabox", "tests"]
+
+[tool.ruff.lint.mccabe]
+# The maximum function complexity to allow before triggering C901 errors
+max-complexity = 20
+
+# Configure the ruff formatter
+[tool.ruff.format]
+# Like Black, use double quotes for strings
+quote-style = "double"
+# Like Black, indent with spaces, rather than tabs
+indent-style = "space"
+# Like Black, respect magic trailing commas
+skip-magic-trailing-comma = false
+# Like Black, automatically detect the appropriate line ending
+line-ending = "auto"
+# Enable reformatting of code snippets in docstrings
+docstring-code-format = true

{pyallel-2.0.5 → pyallel-2.1.0}/src/pyallel/colours.py

@@ -21,7 +21,7 @@ class Colours:
     def from_colour(cls, colour: Literal["yes", "no", "auto"]) -> Colours:
         colours = cls()
 
-        if colour == "no" or colour == "auto" and not constants.IN_TTY:
+        if colour == "no" or (colour == "auto" and not constants.IN_TTY):
             for field in fields(colours):
                 setattr(colours, field.name, "")
 

{pyallel-2.0.5 → pyallel-2.1.0}/src/pyallel/constants.py

@@ -12,18 +12,18 @@ ANSI_ESCAPE = re.compile(r"(\x9B|\x1B\[|\x1B\()[0-?]*[ -\/]*[@-~]")
 
 if IN_TTY:
 
-    def COLUMNS() -> int:
+    def columns() -> int:
         return shutil.get_terminal_size().columns
 
-    def LINES() -> int:
+    def lines() -> int:
         return shutil.get_terminal_size().lines
 
 else:
 
-    def COLUMNS() -> int:
+    def columns() -> int:
         return sys.maxsize
 
-    def LINES() -> int:
+    def lines() -> int:
         return sys.maxsize
 
 

{pyallel-2.0.5 → pyallel-2.1.0}/src/pyallel/errors.py

@@ -1,10 +1,10 @@
 class PyallelError(Exception):
-    """Base error for issues raised by pyallel"""
+    """Base error for issues raised by pyallel."""
 
 
 class InvalidLinesModifierError(PyallelError):
-    """Raised when the lines modifier is invalid"""
+    """Raised when the lines modifier is invalid."""
 
 
 class NoCommandsForProcessGroupError(PyallelError):
-    """Raised when no commands have been provided for a process group"""
+    """Raised when no commands have been provided for a process group."""

pyallel-2.1.0/src/pyallel/logging.py

@@ -0,0 +1,14 @@
+import logging
+import os
+
+
+def configure_logging(*, debug: bool = False) -> None:
+    if debug:
+        logging.basicConfig(
+            filename="pyallel.log",
+            format="%(asctime)s:%(name)s:%(lineno)d:%(message)s",
+            datefmt="%Y-%m-%dT%H:%M:%S",
+            level=logging.DEBUG,
+        )
+    else:
+        logging.basicConfig(handlers=[logging.StreamHandler(stream=open(os.devnull, "w"))])  # noqa: PTH123, SIM115

{pyallel-2.0.5 → pyallel-2.1.0}/src/pyallel/main.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import importlib.metadata
+import logging
 import sys
 import time
 import traceback
@@ -8,6 +9,7 @@ import traceback
 from pyallel import constants
 from pyallel.colours import Colours
 from pyallel.errors import PyallelError
+from pyallel.logging import configure_logging
 from pyallel.parser import Arguments, create_parser
 from pyallel.printer import (
     InteractiveConsolePrinter,
@@ -16,6 +18,8 @@ from pyallel.printer import (
 )
 from pyallel.process_group_manager import ProcessGroupManager
 
+logger = logging.getLogger(__name__)
+
 
 def entry_point(*args: str) -> int:
     args = args or tuple(sys.argv[1:])
@@ -31,6 +35,8 @@ def entry_point(*args: str) -> int:
         parser.print_help()
         return 2
 
+    configure_logging(debug=parsed_args.debug)
+
     colours = Colours.from_colour(parsed_args.colour)
     printer: Printer
     if not parsed_args.interactive or not constants.IN_TTY:
@@ -41,28 +47,27 @@ def entry_point(*args: str) -> int:
     try:
         process_group_manager = ProcessGroupManager.from_args(*parsed_args.commands)
     except PyallelError as e:
-        print(f"{colours.red_bold}Error: {str(e)}{colours.reset_colour}")
+        print(f"{colours.red_bold}Error: {e!s}{colours.reset_colour}")
         return 1
 
+    logger.debug("starting run with arguments:\n%s", parsed_args)
     try:
         exit_code = run(process_group_manager, printer)
     except Exception:
-        print(
-            f"{colours.red_bold}Error: {traceback.format_exc()}{colours.reset_colour}"
-        )
+        logger.exception("failed run with arguments:\n%s", parsed_args)
+        print(f"{colours.red_bold}Error: {traceback.format_exc()}{colours.reset_colour}")
         return 1
 
     if exit_code == 1:
+        logger.error("failed run with arguments:\n%s", parsed_args)
         process_group = process_group_manager.get_cur_process_group_output()
-        print(
-            f"\n{colours.red_bold}ERROR: the following commands failed{colours.reset_colour}"
-        )
+        print(f"\n{colours.red_bold}ERROR: the following commands failed{colours.reset_colour}")
         for process_output in process_group.processes:
             process_poll = process_output.process.poll()
             if process_poll and process_poll > 0:
-                print(
-                    f"   {colours.red_bold}{process_output.process.command}{colours.reset_colour}"
-                )
+                print(f"   {colours.red_bold}{process_output.process.command}{colours.reset_colour}")
+    else:
+        logger.debug("finished run with arguments:\n%s", parsed_args)
 
     return exit_code
 

{pyallel-2.0.5 → pyallel-2.1.0}/src/pyallel/parser.py

@@ -10,13 +10,16 @@ class Arguments:
     interactive: bool
     timer: bool
     version: bool
+    debug: bool
 
     def __repr__(self) -> str:
-        msg = "Arguments:\n"
+        msg = ""
         padding = len(sorted(self.__dict__.keys(), key=len, reverse=True)[0]) + 1
         for field, value in self.__dict__.items():
-            msg += f"    {field: <{padding}}: {value}\n"
-        return msg
+            if field == "commands":
+                value = " ".join(value)  # noqa: PLW2901
+            msg += f"{field: <{padding}}: {value}\n"
+        return msg.strip()
 
 
 DESCRIPTION = r"""run and handle the output of multiple executables in %(prog)s (as in parallel)
@@ -24,11 +27,11 @@ DESCRIPTION = r"""run and handle the output of multiple executables in %(prog)s
 RUNNING COMMANDS
 ================
 to run multiple commands you must separate them using the command separator symbol (::)
-    
+
   %(prog)s mypy . :: black .
 
-if you want to provide options to a command you need to use the double dash symbol (--) to indicate that 
-any options provided after this symbol should not be interpreted by %(prog)s 
+if you want to provide options to a command you need to use the double dash symbol (--) to indicate that
+any options provided after this symbol should not be interpreted by %(prog)s
 
   %(prog)s -n -- mypy -V :: black --version
 
@@ -45,7 +48,7 @@ modifiers can also be set for commands to augment their behaviour using the comm
 
 lines (only used in interactive mode):
   the lines modifier allows you to specify how many lines the command output can take up on the screen
-        
+
     %(prog)s lines=90 :::: echo running long command... :: echo running other command...
 
   90 is expressed as a percentage value, which must be between 1 and 100 inclusive
@@ -54,7 +57,7 @@ SHELL SYNTAX
 ============
 each command is executed inside its own shell, this means shell syntax is supported.
 it is important to note that certain shell syntax must be escaped using backslashes (\)
-or wrapped in single quotes (''), otherwise it will be evaluated in your current 
+or wrapped in single quotes (''), otherwise it will be evaluated in your current
 shell immediately instead of the shell that your command will run within.
 
 some examples of using shell syntax are below (single quotes are used only if required)
@@ -108,5 +111,11 @@ def create_parser() -> ArgumentParser:
         choices=("yes", "no", "auto"),
         default="auto",
     )
+    parser.add_argument(
+        "--debug",
+        help='enable debug mode, which logs debug info to a "pyallel.log" file in the current directory',
+        action="store_true",
+        default=False,
+    )
 
     return parser