Use -C and --directory for pyproject.toml directory path (#213)

Update Poe to use args -C and --directory to find the path to the directory
with pyproject.toml. This better aligns with Poetry (which also uses -C and
--directory). 

Keep the --root argument as a hidden parameter for backwards compatibility.

docs/global_options.rst

@@ -175,7 +175,7 @@ Run poe from anywhere
 
 By default poe will detect when you're inside a project with a pyproject.toml in the
 root. However if you want to run it from elsewhere then that is supported by using the
-:bash:`--root` option to specify an alternate location for the toml file. The task will
+:bash:`-C` option to specify an alternate location for the toml file. The task will
 run with the given location as the current working directory.
 
 In all cases the path to project root (where the pyproject.toml resides) will be

docs/guides/help_guide.rst

@@ -23,20 +23,21 @@ This help text will be displayed alongside the task name in the list of configur
 
   $ poe --help
   Poe the Poet - A task runner that works well with poetry.
-  version 0.19.0
+  version 0.25.1
 
   USAGE
-    poe [-h] [-v | -q] [--root PATH] [--ansi | --no-ansi] task [task arguments]
+    poe [-h] [-v | -q] [-C PATH] [--ansi | --no-ansi] 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
-    --root PATH    Specify where to find the pyproject.toml
-    --ansi         Force enable ANSI output
-    --no-ansi      Force disable ANSI output
+    -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
+    --ansi                Force enable ANSI output
+    --no-ansi             Force disable ANSI output
 
   CONFIGURED TASKS
     test           Run the test suite

docs/index.rst

@@ -117,7 +117,7 @@ If no virtualenv is found then poe will run tasks without any special environmen
 Run poe from anywhere
 =====================
 
-By default poe will detect when you're inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the :sh:`--root` option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.
+By default poe will detect when you're inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the :sh:`-C` option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.
 
 In all cases the path to project root (where the pyproject.toml resides) will be available as :sh:`$POE_ROOT` within the command line and process. The variable :sh:`$POE_PWD` contains the original working directory from which poe was run.
 

poethepoet/ui.py

@@ -114,14 +114,26 @@ def build_parser(self) -> "ArgumentParser":
         )
 
         parser.add_argument(
-            "--root",
+            "-C",
+            "--directory",
             dest="project_root",
             metavar="PATH",
             type=str,
             default=None,
             help="Specify where to find the pyproject.toml",
         )
 
+        # legacy --root parameter, keep for backwards compatability but help output is
+        # suppressed
+        parser.add_argument(
+            "--root",
+            dest="project_root",
+            metavar="PATH",
+            type=str,
+            default=None,
+            help=argparse.SUPPRESS,
+        )
+
         ansi_group = parser.add_mutually_exclusive_group()
         ansi_group.add_argument(
             "--ansi",
@@ -206,7 +218,7 @@ def print_help(
                 (
                     "<h2>USAGE</h2>",
                     f"  <u>{self.program_name}</u>"
-                    " [-h] [-v | -q] [--root PATH] [--ansi | --no-ansi]"
+                    " [-h] [-v | -q] [-C PATH] [--ansi | --no-ansi]"
                     " task [task arguments]",
                 )
             )

tests/test_api.py

@@ -33,7 +33,7 @@ def test_customize_config_name_with_json(run_poe, projects, capsys):
     assert result.stderr == ""
 
     result = run_poe(
-        "--root",
+        "-C",
         str(projects["custom_config"]),
         "hello",
         config_name="tasks.json",

tests/test_cli.py

@@ -15,6 +15,22 @@ def test_call_no_args(run_poe):
     assert "CONFIGURED TASKS\n  echo" in result.capture, "echo task should be in help"
 
 
+def test_call_with_directory(run_poe, projects):
+    result = run_poe("--directory", str(projects["example"]), cwd=".")
+    assert result.code == 1, "Expected non-zero result"
+    assert result.capture.startswith(
+        "Poe the Poet - A task runner that works well with poetry."
+    ), "Output should start with poe header line"
+    assert (
+        "\nResult: No task specified.\n" in result.capture
+    ), "Output should include status message"
+    assert (
+        "CONFIGURED TASKS\n  echo                 It says what you say"
+        in result.capture
+    ), "echo task should be in help"
+
+
+# Test legacy --root parameter (replaced by -C, --directory)
 def test_call_with_root(run_poe, projects):
     result = run_poe("--root", str(projects["example"]), cwd=".")
     assert result.code == 1, "Expected non-zero result"

tests/test_cmd_tasks.py

@@ -173,7 +173,7 @@ def test_cmd_task_with_with_glob_arg_and_cwd(
 
 def test_cmd_with_capture_stdout(run_poe_subproc, projects, poe_project_path):
     result = run_poe_subproc(
-        "--root",
+        "-C",
         str(projects["cmds"]),
         "meeseeks",
         project="cmds",

tests/test_envfile.py

@@ -20,7 +20,7 @@ def test_task_envfile_and_default(run_poe_subproc):
 
 def test_multiple_envfiles(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["envfile/multiple_envfiles"]}', "show_me_the_vals"
+        f'-C={projects["envfile/multiple_envfiles"]}', "show_me_the_vals"
     )
 
     assert (

tests/test_includes.py

@@ -27,7 +27,7 @@ def test_run_task_not_included_from_toml_file(run_poe_subproc):
 
 def test_docs_for_multiple_includes(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["includes/multiple_includes"]}',
+        f'-C={projects["includes/multiple_includes"]}',
     )
     assert (
         "CONFIGURED TASKS\n"
@@ -44,7 +44,7 @@ def test_docs_for_multiple_includes(run_poe_subproc, projects):
 
 def test_running_from_multiple_includes(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["includes/multiple_includes"]}',
+        f'-C={projects["includes/multiple_includes"]}',
         "echo",
         "Whirl!",
         project="includes",
@@ -54,23 +54,21 @@ def test_running_from_multiple_includes(run_poe_subproc, projects):
     assert result.stderr == ""
 
     result = run_poe_subproc(
-        f'--root={projects["includes/multiple_includes"]}', "greet", "Whirl!"
+        f'-C={projects["includes/multiple_includes"]}', "greet", "Whirl!"
     )
     assert result.capture == "Poe => poe_test_echo Hello 'Whirl!'\n"
     assert result.stdout == "Hello Whirl!\n"
     assert result.stderr == ""
 
-    result = run_poe_subproc(
-        f'--root={projects["includes/multiple_includes"]}', "laugh"
-    )
+    result = run_poe_subproc(f'-C={projects["includes/multiple_includes"]}', "laugh")
     assert result.capture == "Poe => poe_test_echo $ONE_LAUGH | tr a-z A-Z\n"
     assert result.stdout == "LOL\n"
     assert result.stderr == ""
 
 
 def test_reference_peer_include(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["includes/multiple_includes"]}', "reference_peer_include"
+        f'-C={projects["includes/multiple_includes"]}', "reference_peer_include"
     )
     assert (
         result.capture
@@ -82,7 +80,7 @@ def test_reference_peer_include(run_poe_subproc, projects):
 
 def test_docs_for_only_includes(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["includes/only_includes"]}',
+        f'-C={projects["includes/only_includes"]}',
     )
     assert (
         "CONFIGURED TASKS\n"
@@ -171,7 +169,7 @@ def test_monorepo_runs_each_task_with_expected_cwd(
     assert result.stderr == ""
 
     result = run_poe_subproc(
-        "--root",
+        "-C",
         str(projects["monorepo/subproject_3"]),
         "get_cwd_3",
         cwd=projects["example"],

tests/test_script_tasks.py

@@ -207,7 +207,7 @@ def test_required_args(run_poe_subproc):
 
 def test_script_task_bad_type(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["scripts/bad_type"]}',
+        f'-C={projects["scripts/bad_type"]}',
         "bad-type",
         "--greeting=hello",
     )
@@ -223,7 +223,7 @@ def test_script_task_bad_type(run_poe_subproc, projects):
 
 def test_script_task_bad_content(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["scripts/bad_content"]}',
+        f'-C={projects["scripts/bad_content"]}',
         "bad-content",
         "--greeting=hello",
     )

tests/test_shell_task.py

@@ -93,7 +93,7 @@ def test_interpreter_python(run_poe_subproc):
 
 def test_bad_interpreter_config(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["shells/bad_interpreter"]}',
+        f'-C={projects["shells/bad_interpreter"]}',
         "bad-interpreter",
     )
     assert (
@@ -108,7 +108,7 @@ def test_bad_interpreter_config(run_poe_subproc, projects):
 
 def test_global_interpreter_config(run_poe_subproc, projects):
     result = run_poe_subproc(
-        f'--root={projects["shells/shell_interpreter_config"]}',
+        f'-C={projects["shells/shell_interpreter_config"]}',
         "echo_python",
     )
     assert result.capture == "Poe => import sys\nprint(sys.version_info)\n"