Docs build 2024-11-16

Author: github-actions

en/latest/_sources/using-operations.rst.txt

@@ -227,6 +227,37 @@ Including files can be used to break out operations across multiple files. Files
     # Include & call all the operations in tasks/install_something.py
     local.include("tasks/install_something.py")
 
+Additional data can be passed across files via the ``data`` param to parameterize tasks and is available in ``host.data``. For example `tasks/create_user.py` could look like:
+
+.. code:: python
+
+    from getpass import getpass
+
+    from pyinfra import host
+    from pyinfra.operations import server
+
+    group = host.data.get("group")
+    user = host.data.get("user")
+
+    server.group(
+        name=f"Ensure {group} is present",
+        group=group,
+    )
+    server.user(
+        name=f"Ensure {user} is present",
+        user=user,
+        group=group,
+    )
+
+And and be called by other deploy scripts or tasks:
+
+.. code:: python
+
+    from pyinfra import local
+
+    for group, user in (("admin", "Bob"), ("admin", "Joe")):
+        local.include("tasks/create_user.py", data={"group": group, "user": user})
+
 See more in :doc:`examples: groups & roles <./examples/groups_roles>`.
 
 

en/latest/apidoc/pyinfra.local.html

@@ -165,7 +165,7 @@ <h3>Navigation</h3>
 <span id="pyinfra-local-module"></span><h1>pyinfra.local module<a class="headerlink" href="#module-pyinfra.local" title="Permalink to this heading">¶</a></h1>
 <dl class="py function">
 <dt class="sig sig-object py" id="pyinfra.local.include">
-<code class="sig-prename descclassname"><span class="pre">pyinfra.local.</span></code><code class="sig-name descname"><span class="pre">include</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">filename</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.local.include" title="Permalink to this definition">¶</a></dt>
+<code class="sig-prename descclassname"><span class="pre">pyinfra.local.</span></code><code class="sig-name descname"><span class="pre">include</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">filename</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.local.include" title="Permalink to this definition">¶</a></dt>
 <dd><p>Executes a local python file within the <code class="docutils literal notranslate"><span class="pre">pyinfra.state.cwd</span></code>
 directory.</p>
 </dd></dl>

en/latest/searchindex.js

@@ -350,6 +350,33 @@ <h2>Include Multiple Files<a class="headerlink" href="#include-multiple-files" t
 <span class="n">local</span><span class="o">.</span><span class="n">include</span><span class="p">(</span><span class="s2">&quot;tasks/install_something.py&quot;</span><span class="p">)</span>
 </pre></div>
 </div>
+<p>Additional data can be passed across files via the <code class="docutils literal notranslate"><span class="pre">data</span></code> param to parameterize tasks and is available in <code class="docutils literal notranslate"><span class="pre">host.data</span></code>. For example <cite>tasks/create_user.py</cite> could look like:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">getpass</span> <span class="kn">import</span> <span class="n">getpass</span>
+
+<span class="kn">from</span> <span class="nn">pyinfra</span> <span class="kn">import</span> <span class="n">host</span>
+<span class="kn">from</span> <span class="nn">pyinfra.operations</span> <span class="kn">import</span> <span class="n">server</span>
+
+<span class="n">group</span> <span class="o">=</span> <span class="n">host</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;group&quot;</span><span class="p">)</span>
+<span class="n">user</span> <span class="o">=</span> <span class="n">host</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;user&quot;</span><span class="p">)</span>
+
+<span class="n">server</span><span class="o">.</span><span class="n">group</span><span class="p">(</span>
+    <span class="n">name</span><span class="o">=</span><span class="sa">f</span><span class="s2">&quot;Ensure </span><span class="si">{</span><span class="n">group</span><span class="si">}</span><span class="s2"> is present&quot;</span><span class="p">,</span>
+    <span class="n">group</span><span class="o">=</span><span class="n">group</span><span class="p">,</span>
+<span class="p">)</span>
+<span class="n">server</span><span class="o">.</span><span class="n">user</span><span class="p">(</span>
+    <span class="n">name</span><span class="o">=</span><span class="sa">f</span><span class="s2">&quot;Ensure </span><span class="si">{</span><span class="n">user</span><span class="si">}</span><span class="s2"> is present&quot;</span><span class="p">,</span>
+    <span class="n">user</span><span class="o">=</span><span class="n">user</span><span class="p">,</span>
+    <span class="n">group</span><span class="o">=</span><span class="n">group</span><span class="p">,</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+<p>And and be called by other deploy scripts or tasks:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pyinfra</span> <span class="kn">import</span> <span class="n">local</span>
+
+<span class="k">for</span> <span class="n">group</span><span class="p">,</span> <span class="n">user</span> <span class="ow">in</span> <span class="p">((</span><span class="s2">&quot;admin&quot;</span><span class="p">,</span> <span class="s2">&quot;Bob&quot;</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;admin&quot;</span><span class="p">,</span> <span class="s2">&quot;Joe&quot;</span><span class="p">)):</span>
+    <span class="n">local</span><span class="o">.</span><span class="n">include</span><span class="p">(</span><span class="s2">&quot;tasks/create_user.py&quot;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;group&quot;</span><span class="p">:</span> <span class="n">group</span><span class="p">,</span> <span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">})</span>
+</pre></div>
+</div>
 <p>See more in <a class="reference internal" href="examples/groups_roles.html"><span class="doc">examples: groups &amp; roles</span></a>.</p>
 </div>
 <div class="section" id="the-config-object">

en/latest/using-operations.html

@@ -227,6 +227,37 @@ Including files can be used to break out operations across multiple files. Files
     # Include & call all the operations in tasks/install_something.py
     local.include("tasks/install_something.py")
 
+Additional data can be passed across files via the ``data`` param to parameterize tasks and is available in ``host.data``. For example `tasks/create_user.py` could look like:
+
+.. code:: python
+
+    from getpass import getpass
+
+    from pyinfra import host
+    from pyinfra.operations import server
+
+    group = host.data.get("group")
+    user = host.data.get("user")
+
+    server.group(
+        name=f"Ensure {group} is present",
+        group=group,
+    )
+    server.user(
+        name=f"Ensure {user} is present",
+        user=user,
+        group=group,
+    )
+
+And and be called by other deploy scripts or tasks:
+
+.. code:: python
+
+    from pyinfra import local
+
+    for group, user in (("admin", "Bob"), ("admin", "Joe")):
+        local.include("tasks/create_user.py", data={"group": group, "user": user})
+
 See more in :doc:`examples: groups & roles <./examples/groups_roles>`.
 
 

en/next/_sources/using-operations.rst.txt

@@ -165,7 +165,7 @@ <h3>Navigation</h3>
 <span id="pyinfra-local-module"></span><h1>pyinfra.local module<a class="headerlink" href="#module-pyinfra.local" title="Permalink to this heading">¶</a></h1>
 <dl class="py function">
 <dt class="sig sig-object py" id="pyinfra.local.include">
-<code class="sig-prename descclassname"><span class="pre">pyinfra.local.</span></code><code class="sig-name descname"><span class="pre">include</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">filename</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.local.include" title="Permalink to this definition">¶</a></dt>
+<code class="sig-prename descclassname"><span class="pre">pyinfra.local.</span></code><code class="sig-name descname"><span class="pre">include</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">filename</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.local.include" title="Permalink to this definition">¶</a></dt>
 <dd><p>Executes a local python file within the <code class="docutils literal notranslate"><span class="pre">pyinfra.state.cwd</span></code>
 directory.</p>
 </dd></dl>

en/next/apidoc/pyinfra.local.html

@@ -350,6 +350,33 @@ <h2>Include Multiple Files<a class="headerlink" href="#include-multiple-files" t
 <span class="n">local</span><span class="o">.</span><span class="n">include</span><span class="p">(</span><span class="s2">&quot;tasks/install_something.py&quot;</span><span class="p">)</span>
 </pre></div>
 </div>
+<p>Additional data can be passed across files via the <code class="docutils literal notranslate"><span class="pre">data</span></code> param to parameterize tasks and is available in <code class="docutils literal notranslate"><span class="pre">host.data</span></code>. For example <cite>tasks/create_user.py</cite> could look like:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">getpass</span> <span class="kn">import</span> <span class="n">getpass</span>
+
+<span class="kn">from</span> <span class="nn">pyinfra</span> <span class="kn">import</span> <span class="n">host</span>
+<span class="kn">from</span> <span class="nn">pyinfra.operations</span> <span class="kn">import</span> <span class="n">server</span>
+
+<span class="n">group</span> <span class="o">=</span> <span class="n">host</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;group&quot;</span><span class="p">)</span>
+<span class="n">user</span> <span class="o">=</span> <span class="n">host</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;user&quot;</span><span class="p">)</span>
+
+<span class="n">server</span><span class="o">.</span><span class="n">group</span><span class="p">(</span>
+    <span class="n">name</span><span class="o">=</span><span class="sa">f</span><span class="s2">&quot;Ensure </span><span class="si">{</span><span class="n">group</span><span class="si">}</span><span class="s2"> is present&quot;</span><span class="p">,</span>
+    <span class="n">group</span><span class="o">=</span><span class="n">group</span><span class="p">,</span>
+<span class="p">)</span>
+<span class="n">server</span><span class="o">.</span><span class="n">user</span><span class="p">(</span>
+    <span class="n">name</span><span class="o">=</span><span class="sa">f</span><span class="s2">&quot;Ensure </span><span class="si">{</span><span class="n">user</span><span class="si">}</span><span class="s2"> is present&quot;</span><span class="p">,</span>
+    <span class="n">user</span><span class="o">=</span><span class="n">user</span><span class="p">,</span>
+    <span class="n">group</span><span class="o">=</span><span class="n">group</span><span class="p">,</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+<p>And and be called by other deploy scripts or tasks:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pyinfra</span> <span class="kn">import</span> <span class="n">local</span>
+
+<span class="k">for</span> <span class="n">group</span><span class="p">,</span> <span class="n">user</span> <span class="ow">in</span> <span class="p">((</span><span class="s2">&quot;admin&quot;</span><span class="p">,</span> <span class="s2">&quot;Bob&quot;</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;admin&quot;</span><span class="p">,</span> <span class="s2">&quot;Joe&quot;</span><span class="p">)):</span>
+    <span class="n">local</span><span class="o">.</span><span class="n">include</span><span class="p">(</span><span class="s2">&quot;tasks/create_user.py&quot;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;group&quot;</span><span class="p">:</span> <span class="n">group</span><span class="p">,</span> <span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">})</span>
+</pre></div>
+</div>
 <p>See more in <a class="reference internal" href="examples/groups_roles.html"><span class="doc">examples: groups &amp; roles</span></a>.</p>
 </div>
 <div class="section" id="the-config-object">