Fix docs publishing workflow 0133c42

_sources/tasks/task_types/cmd.rst.txt

@@ -26,6 +26,7 @@ It is important to understand that ``cmd`` tasks are executed without a shell (t
 
 .. _ref_env_vars:
 
+
 Referencing environment variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -50,6 +51,29 @@ Parameter expansion can also can be disabled by escaping the $ with a backslash
   greet = "echo Hello \\$USER"  # the backslash itself needs escaping for the toml parser
 
 
+Parameter expansion operators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When referencing an environment variable in a cmd task you can use the ``:-`` operator from bash to specify a *default value*, to be used in case the variable is unset. Similarly the ``:+`` operator can be used to specify an *alternate value* to use in place of the environment variable if it *is* set.
+
+In the following example, if ``AWS_REGION`` has a value then it will be used, otherwise ``us-east-1`` will be used as a fallback.
+
+.. code-block:: toml
+
+  [tool.poe.tasks]
+  tables = "aws dynamodb list-tables --region ${AWS_REGION:-us-east-1}"
+
+The ``:+`` or *alternate value* operator is especially useful in cases such as the following where you might want to control whether some CLI options are passed to the command.
+
+.. code-block:: toml
+
+  [tool.poe.tasks.aws-identity]
+  cmd = "aws sts get-caller-identity ${ARN_ONLY:+ --no-cli-pager --output text --query 'Arn'}"
+  args = [{ name = "ARN_ONLY", options = ["--arn-only"], type = "boolean" }]
+
+In this example we declare a boolean argument with no default, so if the ``--arn-only`` flag is provided to the task then three additional CLI options will be included in the task content.
+
+
 Glob expansion
 ~~~~~~~~~~~~~~
 
@@ -78,7 +102,7 @@ Here's an example of task using a recursive glob pattern:
 
 .. seealso::
 
-  Much like in bash, the glob pattern can be escaped by wrapping it in quotes, or preceding it with a backslash.
+  Just like in bash, the glob pattern can be escaped by wrapping it in quotes, or preceding it with a backslash.
 
 
 .. |glob_link| raw:: html

_static/documentation_options.js

@@ -1,5 +1,5 @@
 const DOCUMENTATION_OPTIONS = {
-    VERSION: '0.31.1',
+    VERSION: '0.32.0',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

contributing.html

@@ -428,7 +428,7 @@ <h3>How to create release<a class="headerlink" href="#how-to-create-release" tit
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

env_vars.html

@@ -350,7 +350,7 @@ <h2>External Environment variables<a class="headerlink" href="#external-environm
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

genindex.html

@@ -288,7 +288,7 @@ <h2>R</h2>
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

global_options.html

@@ -488,7 +488,7 @@ <h2>Run poe from anywhere<a class="headerlink" href="#run-poe-from-anywhere" tit
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

guides/args_guide.html

@@ -574,7 +574,7 @@ <h2>Passing free arguments in addition to named arguments<a class="headerlink" h
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/composition_guide.html

@@ -391,7 +391,7 @@ <h1>Composing tasks<a class="headerlink" href="#composing-tasks" title="Link to
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/global_tasks.html

@@ -353,7 +353,7 @@ <h2>Shell completions for global tasks<a class="headerlink" href="#shell-complet
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/help_guide.html

@@ -340,7 +340,7 @@ <h1>Documenting tasks<a class="headerlink" href="#documenting-tasks" title="Link
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/include_guide.html

@@ -381,7 +381,7 @@ <h2>Including files relative to the git repo<a class="headerlink" href="#includi
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/index.html

@@ -314,7 +314,7 @@ <h1>Guides<a class="headerlink" href="#guides" title="Link to this heading">¶</
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/library_guide.html

@@ -255,7 +255,7 @@ <h1>Using poethepoet as a library<a class="headerlink" href="#using-poethepoet-a
 <p>The <a class="reference external" href="https://github.com/nat-n/poethepoet/blob/main/poethepoet/app.py">PoeThePoet</a> class accepts various optional arguments to customize its behavior as described below.</p>
 <dl class="py class">
 <dt class="sig sig-object py" id="poethepoet.app.PoeThePoet">
-<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">poethepoet.app.</span></span><span class="sig-name descname"><span class="pre">PoeThePoet</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cwd:</span> <span class="pre">~pathlib.Path</span> <span class="pre">|</span> <span class="pre">str</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">config:</span> <span class="pre">~collections.abc.Mapping[str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">~typing.Any]</span> <span class="pre">|</span> <span class="pre">PoeConfig</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">output:</span> <span class="pre">~typing.IO</span> <span class="pre">=</span> <span class="pre">&lt;_io.TextIOWrapper</span> <span class="pre">name='&lt;stdout&gt;'</span> <span class="pre">mode='w'</span> <span class="pre">encoding='utf-8'&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">poetry_env_path:</span> <span class="pre">str</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">config_name:</span> <span class="pre">str</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">program_name:</span> <span class="pre">str</span> <span class="pre">=</span> <span class="pre">'poe'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#poethepoet.app.PoeThePoet" title="Link to this definition">¶</a></dt>
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">poethepoet.app.</span></span><span class="sig-name descname"><span class="pre">PoeThePoet</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cwd:</span> <span class="pre">~pathlib.Path</span> <span class="pre">|</span> <span class="pre">str</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">config:</span> <span class="pre">~collections.abc.Mapping[str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">~typing.Any]</span> <span class="pre">|</span> <span class="pre">PoeConfig</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">output:</span> <span class="pre">~typing.IO</span> <span class="pre">=</span> <span class="pre">&lt;_io.TextIOWrapper</span> <span class="pre">name='&lt;stdout&gt;'</span> <span class="pre">mode='w'</span> <span class="pre">encoding='utf-8'&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">poetry_env_path:</span> <span class="pre">str</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">config_name:</span> <span class="pre">str</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">program_name:</span> <span class="pre">str</span> <span class="pre">=</span> <span class="pre">'poe'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">env:</span> <span class="pre">~collections.abc.Mapping[str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">str]</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#poethepoet.app.PoeThePoet" title="Link to this definition">¶</a></dt>
 <dd><dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><ul class="simple">
@@ -274,6 +274,8 @@ <h1>Using poethepoet as a library<a class="headerlink" href="#using-poethepoet-a
 poe_tasks.toml poe_tasks.yaml poe_tasks.json</p></li>
 <li><p><strong>program_name</strong> (<em>str</em><em>, </em><em>optional</em>) – The name of the program that is being run. This is used primarily when
 outputting help messages, defaults to “poe”</p></li>
+<li><p><strong>env</strong> (<em>dict</em><em>, </em><em>optional</em>) – Optionally provide an alternative base environment for tasks to run with.
+If no mapping is provided then <code class="docutils literal notranslate"><span class="pre">os.environ</span></code> is used.</p></li>
 </ul>
 </dd>
 </dl>
@@ -361,7 +363,7 @@ <h1>Using poethepoet as a library<a class="headerlink" href="#using-poethepoet-a
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/running_guide.html

@@ -386,7 +386,7 @@ <h2>Passing arguments<a class="headerlink" href="#passing-arguments" title="Link
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/toml_guide.html

@@ -284,7 +284,7 @@ <h1>Using toml syntax<a class="headerlink" href="#using-toml-syntax" title="Link
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

guides/without_poetry.html

@@ -384,7 +384,7 @@ <h3>Usage with with json or yaml instead of toml<a class="headerlink" href="#usa
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

index.html

@@ -357,7 +357,7 @@ <h2>Run poe from anywhere<a class="headerlink" href="#run-poe-from-anywhere" tit
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

installation.html

@@ -422,7 +422,7 @@ <h2>Supported python versions<a class="headerlink" href="#supported-python-versi
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

license.html

@@ -310,7 +310,7 @@ <h1>Licence<a class="headerlink" href="#licence" title="Link to this heading">¶
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

poetry_plugin.html

@@ -410,7 +410,7 @@ <h2>Known limitations<a class="headerlink" href="#known-limitations" title="Link
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

search.html

@@ -273,7 +273,7 @@
 
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=72479337"></script>
+</div><script src="_static/documentation_options.js?v=4440c9c5"></script>
     <script src="_static/doctools.js?v=9a2dae69"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=32e29ea5"></script>

tasks/index.html

@@ -368,7 +368,7 @@ <h2>Types of task<a class="headerlink" href="#types-of-task" title="Link to this
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>

tasks/options.html

@@ -461,7 +461,7 @@ <h2>Defining tasks that run via exec instead of a subprocess<a class="headerlink
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=72479337"></script>
+</div><script src="../_static/documentation_options.js?v=4440c9c5"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=32e29ea5"></script>