Add support for specifying env vars for a task

README.rst

@@ -17,11 +17,13 @@ Features
 
 ✅ Task are run in poetry's virtualenv by default
 
-✅ Tasks can be shell commands or references to python functions (like tool.poetry.scripts)
+✅ Tasks can be commands (with or without a shell) or references to python functions (like tool.poetry.scripts)
 
 ✅ Short and sweet commands with extra arguments passed to the task :bash:`poe [options] task [task_args]`
 
-✅ Tasks can reference environmental variables as if they were evaluated by a shell
+✅ Tasks can specify and reference environmental variables as if they were evaluated by a shell
+
+✅ Tasks are self documenting, with optional help messages (just run poe without arguments)
 
 Installation
 ============
@@ -135,7 +137,7 @@ scripts (shell).
     pfwd = { "shell" = "ssh -N -L 0.0.0.0:8080:$STAGING:8080 $STAGING & ssh -N -L 0.0.0.0:5432:$STAGINGDB:5432 $STAGINGDB &" }
     pfwdstop = { "shell" = "kill $(pgrep -f "ssh -N -L .*:(8080|5432)")" }
 
-Extra task configuration
+Task level configuration
 ========================
 
 Task help text
@@ -148,6 +150,19 @@ You can specifiy help text to be shown alongside the task name in the list of av
     [tool.poe.tasks]
     style = {cmd = "black . --check --diff", help = "Check code style"}
 
+Environmental variables
+-----------------------
+
+You can specify arbitrary environmental variables to be set for a task by providing the env key like so:
+
+  .. code-block:: toml
+
+    [tool.poe.tasks]
+    serve.script = "myapp:run"
+    serve.env = { PORT = 9001 }
+
+Notice this exame uses deep keys which can be more convenient but aren't as well supported by some toml implementations.
+
 Project-wide configuration options
 ==================================
 
@@ -205,14 +220,16 @@ TODO
 
 ☐ support declaring specific arguments for a task
 
-☐ support documenting tasks
-
 ☐ command line completion
 
 ☐ support running tasks outside of poetry's virtualenv (or in another?)
 
 ☐ maybe try work well without poetry too
 
+☐ maybe support alternative toml formats (e.g. table arrays)
+
+☐ maybe support third party task types
+
 Licence
 =======
 

poethepoet/task/base.py

@@ -51,7 +51,7 @@ class PoeTask(metaclass=MetaPoeTask):
     options: Dict[str, Any]
 
     __options__: Dict[str, Type]
-    __base_options: Dict[str, Type] = {"help": str}
+    __base_options: Dict[str, Type] = {"help": str, "env": dict}
     __task_types: Dict[str, Type["PoeTask"]] = {}
 
     def __init__(self, name: str, content: str, options: Dict[str, Any], ui: PoeUi):
@@ -95,6 +95,8 @@ def run(
         if env is None:
             env = dict(os.environ)
         env["POE_ROOT"] = str(project_dir)
+        if self.options.get("env"):
+            env = dict(env, **self.options["env"])
 
         if set_cwd:
             previous_wd = os.getcwd()

tests/fixtures/dummy_project/pyproject.toml

@@ -9,8 +9,9 @@ packages = [
 ]
 
 [tool.poe.tasks]
-echo.cmd = "echo POE_ROOT:$POE_ROOT task_args:"
+echo.cmd = "echo POE_ROOT:$POE_ROOT ${BEST_PASSWORD} task_args:"
 echo.help = "It says what you say"
+echo.env.BEST_PASSWORD = "Password1"
 show_env = "env"
 pwd = "pwd"
 greet = { script = "dummy_package:main" }

tests/test_task_running.py

@@ -7,11 +7,11 @@ def test_call_echo_task(run_poe_subproc, dummy_project_path):
     result = run_poe_subproc("echo", "foo", r"\${POE_ROOT} !")
     assert (
         result.capture
-        == f"Poe => echo POE_ROOT:{dummy_project_path} task_args: foo {dummy_project_path} !\n"
+        == f"Poe => echo POE_ROOT:{dummy_project_path} Password1 task_args: foo {dummy_project_path} !\n"
     )
     assert (
         result.stdout
-        == f"POE_ROOT:{dummy_project_path} task_args: foo {dummy_project_path} !\n"
+        == f"POE_ROOT:{dummy_project_path} Password1 task_args: foo {dummy_project_path} !\n"
     )
     assert result.stderr == ""
 
@@ -50,7 +50,7 @@ def test_passing_envvar_str_to_task(
     output_var_ = output_var.replace("dummy_project_path", str(dummy_project_path))
     assert (
         result.capture
-        == f"Poe => echo POE_ROOT:{dummy_project_path} task_args: {output_var_} !\n"
+        == f"Poe => echo POE_ROOT:{dummy_project_path} Password1 task_args: {output_var_} !\n"
     )
     # assert result.stdout == f"POE_ROOT:{dummy_project_path} task_args: {output_var} !\n"
     assert result.stderr == ""