Add POE_PROJECT_DIR env var as default for -C option (#215)

Also add page to docs for environment variables.

docs/env_vars.rst

@@ -0,0 +1,21 @@
+Environment variables
+=====================
+
+Internal Environment variables
+------------------------------
+
+The following environment variables are used by Poe the Poet internally, and can be accessed from within configuration and tasks.
+
+- ``POE_ROOT``: path to the parent directory of the main tasks file (e.g. pyproject.toml).
+- ``POE_PWD``: the current working directory of the poe process (unless overriden programmatically).
+- ``POE_CONF_DIR``: the path to the parent directory of the config file that defines the running task or the :ref:`cwd option<Setting a working directory for included tasks>` set when including that config.
+- ``POE_ACTIVE``: identifies the active PoeExecutor, so that Poe the Poet can tell when it is running recursively.
+
+External Environment variables
+------------------------------
+
+The following environment variables can be set to modify Poe the Poet's behavior.
+
+- ``POE_PROJECT_DIR``: used as the default value for the ``--directory`` global argument.
+- ``NO_COLOR``: disables ansi colors in output (unless the --ansi argument is provided).
+- ``POE_DEBUG``: can be set to ``1`` to enable printing debug messages to stdout.

docs/index.rst

@@ -7,6 +7,7 @@
    global_options
    tasks/index
    guides/index
+   env_vars
    license
 
 **************************

poethepoet/env/cache.py

@@ -7,7 +7,7 @@
 if TYPE_CHECKING:
     from .ui import PoeUi
 
-POE_DEBUG = environ.get("POE_DEBUG")
+POE_DEBUG = environ.get("POE_DEBUG", "0") == 1
 
 
 class EnvFileCache:

poethepoet/ui.py

@@ -119,7 +119,7 @@ def build_parser(self) -> "ArgumentParser":
             dest="project_root",
             metavar="PATH",
             type=str,
-            default=None,
+            default=os.environ.get("POE_PROJECT_DIR", None),
             help="Specify where to find the pyproject.toml",
         )
 
@@ -274,7 +274,7 @@ def print_help(
             else:
                 result.append("<h2-dim>NO TASKS CONFIGURED</h2-dim>")
 
-        if error and os.environ.get("POE_DEBUG", "0").lower() == "1":
+        if error and os.environ.get("POE_DEBUG", "0") == "1":
             import traceback
 
             result.append("".join(traceback.format_exception(error)).strip())
@@ -308,7 +308,7 @@ def print_error(self, error: Union[PoeException, ExecutionError]):
         for line in self._format_error_lines(error_lines):
             self._print(line)
 
-        if os.environ.get("POE_DEBUG", "0").lower() == "1":
+        if os.environ.get("POE_DEBUG", "0") == "1":
             import traceback
 
             self._print("".join(traceback.format_exception(error)).strip())

tests/test_cli.py

@@ -25,8 +25,23 @@ def test_call_with_directory(run_poe, projects):
         "\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
+        "CONFIGURED TASKS\n"
+        "  echo                 It says what you say" in result.capture
+    ), "echo task should be in help"
+
+
+def test_call_with_directory_set_via_env(run_poe_subproc, projects):
+    result = run_poe_subproc(env={"POE_PROJECT_DIR": 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"
 
 
@@ -41,8 +56,8 @@ def test_call_with_root(run_poe, projects):
         "\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
+        "CONFIGURED TASKS\n"
+        "  echo                 It says what you say" in result.capture
     ), "echo task should be in help"