nat-n / poethepoet

A task runner that works well with poetry.
https://poethepoet.natn.io/
MIT License
1.46k stars 59 forks source link

Error executing the task when the documentation has multiple lines #239

Closed taconi closed 1 month ago

taconi commented 2 months ago

Description of the bug

When I create a task that has its documentation (help) with more than one line, no error is displayed when listing the tasks configured with the poe --help command, but when executing this task an error appears, preventing your concussion.

Error displayed

Error: Invalid task 'fmt'
     | Help messages must not contain line breaks

How to reproduce the the bug ?

Dependencies

The following versions were used for testing:

dependency version
python 3.12.5
poetry 1.8.3
poethepoet 0.26.1 - 0.27.0 - 0.28.0
pyproject.toml file with the fmt task that has documentation with more than one line ``` toml [tool.poetry] package-mode = false [tool.poetry.dependencies] python = "3.12.5" poethepoet = "^0.28.0" black = "^24.8.0" [tool.poe.tasks.fmt] cmd = "black -S -l 79 $PATH" help = """\n Use "poe fmt" to format the code. Examples: # Format all files poe fmt """ [tool.poe.tasks.fmt.args.PATH] options = ["-p", "--path"] default = "." help = """\n Change the path that will be formatted. Examples: # Formatting a specific path poe fmt -p tests """ [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api" ```

Steps

  1. Install project dependencies:
poetry install
  1. List the successfully configured tasks:
poetry run poe --help
Full output of poetry run poe --help command ``` shell Poe the Poet - A task runner that works well with poetry. version 0.28.0 Usage: poe [global options] task [task arguments] Global options: -h, --help Show this help page and exit --version Print the version and exit -v, --verbose Increase command output (repeatable) -q, --quiet Decrease command output (repeatable) -d, --dry-run Print the task contents but don't actually run it -C PATH, --directory PATH Specify where to find the pyproject.toml -e EXECUTOR, --executor EXECUTOR Override the default task executor --ansi Force enable ANSI output --no-ansi Force disable ANSI output Configured tasks: fmt Use "poe fmt" to format the code. Examples: # Format all files poe fmt -p, --path Change the path that will be formatted. Examples: # Formatting a specific path poe fmt -p tests [default: .] ```
  1. Running task with error:
poetry run poe fmt
Full error output from poe fmt command ``` shell Poe the Poet - A task runner that works well with poetry. version 0.28.0 Error: Invalid task 'fmt' | Help messages must not contain line breaks Usage: poe [global options] task [task arguments] Global options: -h, --help Show this help page and exit --version Print the version and exit -v, --verbose Increase command output (repeatable) -q, --quiet Decrease command output (repeatable) -d, --dry-run Print the task contents but don't actually run it -C PATH, --directory PATH Specify where to find the pyproject.toml -e EXECUTOR, --executor EXECUTOR Override the default task executor --ansi Force enable ANSI output --no-ansi Force disable ANSI output Configured tasks: fmt Use "poe fmt" to format the code. Examples: # Format all files poe fmt -p, --path Change the path that will be formatted. Examples: # Formatting a specific path poe fmt -p tests [default: .] ```
taconi commented 2 months ago

Looking at the source code I found where this exception is raised.

https://github.com/nat-n/poethepoet/blob/c5841bc3ef14dab3aeea71dc89f93690948e9191/poethepoet/task/base.py#L182-L189

Since this is an explicit action, what would be the reason why a task cannot have help with line breaks, would it have to do with some other problem or would it be to be able to standardize the formatting of the output?

nat-n commented 2 months ago

Hi @taconi, thanks for the feedback and your attention on this issue. The rule about single line help messages was something I implemented quite early on, mostly because splitting help messages across multiple lines seemed like a bad idea that offended my aesthetics. Then it seems this rule got misplaced in a later refactor so it only applies lazily when initializing a task 🤦.

That said the way you're using multiline messages doesn't look too awful... so I think dropping this validation rule would be OK. Making poe strip whitespace from the help message before printing it would probably be an improvement.

nat-n commented 1 month ago

The fix is out in 0.29.0 🚀