Docs build 2024-11-16

en/latest/_sources/facts/apt.rst.txt

@@ -46,3 +46,15 @@ Returns a list of installed apt sources:
         },
     ]
 
+
+.. _facts:apt.SimulateOperationWillChange:
+
+:code:`apt.SimulateOperationWillChange`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+    host.get_fact(SimulateOperationWillChange, command)
+
+Simulate an 'apt-get' operation and try to detect if any changes would be performed.
+

en/latest/_sources/operations/apt.rst.txt

@@ -5,7 +5,7 @@ Apt Operations
 Manage apt packages and repositories.
 
 
-Facts used in these operations: :ref:`facts:apt.AptKeys`, :ref:`facts:apt.AptSources`, :ref:`facts:server.Date`, :ref:`facts:deb.DebPackage`, :ref:`facts:deb.DebPackages`, :ref:`facts:files.File`, :ref:`facts:gpg.GpgKey`.
+Facts used in these operations: :ref:`facts:apt.AptKeys`, :ref:`facts:apt.AptSources`, :ref:`facts:server.Date`, :ref:`facts:deb.DebPackage`, :ref:`facts:deb.DebPackages`, :ref:`facts:files.File`, :ref:`facts:gpg.GpgKey`, :ref:`facts:apt.SimulateOperationWillChange`.
 
 .. _operations:apt.deb:
 
@@ -46,12 +46,6 @@ URL sources with ``present=False``:
 :code:`apt.dist_upgrade`
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. admonition:: Stateless operation
-    :class: important
-
-    This operation will always execute commands and is not idempotent.
-
-
 Updates all apt packages, employing dist-upgrade.
 
 .. code:: python
@@ -262,12 +256,6 @@ Updates apt repositories.
 :code:`apt.upgrade`
 ~~~~~~~~~~~~~~~~~~~
 
-.. admonition:: Stateless operation
-    :class: important
-
-    This operation will always execute commands and is not idempotent.
-
-
 Upgrades all apt packages.
 
 .. code:: python

en/latest/apidoc/pyinfra.api.deploy.html

@@ -168,7 +168,7 @@ <h3>Navigation</h3>
 creation (eg pyinfra-openstack).</p>
 <dl class="py function">
 <dt class="sig sig-object py" id="pyinfra.api.deploy.add_deploy">
-<code class="sig-prename descclassname"><span class="pre">pyinfra.api.deploy.</span></code><code class="sig-name descname"><span class="pre">add_deploy</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">state</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="pyinfra.api.state.html#pyinfra.api.state.State" title="pyinfra.api.state.State"><span class="pre">State</span></a></span></em>, <em><span class="n"><span class="pre">deploy_func</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">...</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span></span></em>, <em><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.api.deploy.add_deploy" title="Permalink to this definition">¶</a></dt>
+<code class="sig-prename descclassname"><span class="pre">pyinfra.api.deploy.</span></code><code class="sig-name descname"><span class="pre">add_deploy</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">state</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="pyinfra.api.state.html#pyinfra.api.state.State" title="pyinfra.api.state.State"><span class="pre">State</span></a></span></em>, <em><span class="n"><span class="pre">deploy_func</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">...</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span></span></em>, <em><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#pyinfra.api.deploy.add_deploy" title="Permalink to this definition">¶</a></dt>
 <dd><p>Prepare &amp; add an deploy to pyinfra.state by executing it on all hosts.</p>
 <dl class="docutils field-list" frame="void" rules="none">
 <dt class="field-name">Parameters</dt><dd class="field-body"><ul class="first last simple">
@@ -183,7 +183,7 @@ <h3>Navigation</h3>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pyinfra.api.deploy.deploy">
-<code class="sig-prename descclassname"><span class="pre">pyinfra.api.deploy.</span></code><code class="sig-name descname"><span class="pre">deploy</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</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>, <em><span class="n"><span class="pre">data_defaults</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.api.deploy.deploy" title="Permalink to this definition">¶</a></dt>
+<code class="sig-prename descclassname"><span class="pre">pyinfra.api.deploy.</span></code><code class="sig-name descname"><span class="pre">deploy</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</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>, <em><span class="n"><span class="pre">data_defaults</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> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">P</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference internal" href="pyinfra.api.arguments_typed.html#pyinfra.api.arguments_typed.PyinfraOperation" title="pyinfra.api.arguments_typed.PyinfraOperation"><span class="pre">PyinfraOperation</span></a><span class="p"><span class="pre">[</span></span><span class="pre">P</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></span><a class="headerlink" href="#pyinfra.api.deploy.deploy" title="Permalink to this definition">¶</a></dt>
 <dd><p>Decorator that takes a deploy function (normally from a pyinfra_* package)
 and wraps any operations called inside with any deploy-wide kwargs/data.</p>
 </dd></dl>

en/latest/apidoc/pyinfra.api.host.html

@@ -316,12 +316,12 @@ <h3>Navigation</h3>
 
 <dl class="py method">
 <dt class="sig sig-object py" id="pyinfra.api.host.Host.log">
-<code class="sig-name descname"><span class="pre">log</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">message</span></span></em>, <em><span class="n"><span class="pre">log_func=&lt;bound</span> <span class="pre">method</span> <span class="pre">Logger.info</span> <span class="pre">of</span> <span class="pre">&lt;Logger</span> <span class="pre">pyinfra</span> <span class="pre">(WARNING)&gt;&gt;</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.api.host.Host.log" title="Permalink to this definition">¶</a></dt>
+<code class="sig-name descname"><span class="pre">log</span></code><span class="sig-paren">(</span><em><span class="pre">message:</span> <span class="pre">str,</span> <span class="pre">log_func:</span> <span class="pre">~typing.Callable[[str],</span> <span class="pre">~typing.Any]</span> <span class="pre">=</span> <span class="pre">&lt;bound</span> <span class="pre">method</span> <span class="pre">Logger.info</span> <span class="pre">of</span> <span class="pre">&lt;Logger</span> <span class="pre">pyinfra</span> <span class="pre">(WARNING)&gt;&gt;</span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#pyinfra.api.host.Host.log" title="Permalink to this definition">¶</a></dt>
 <dd></dd></dl>
 
 <dl class="py method">
 <dt class="sig sig-object py" id="pyinfra.api.host.Host.log_styled">
-<code class="sig-name descname"><span class="pre">log_styled</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">message</span></span></em>, <em><span class="n"><span class="pre">log_func=&lt;bound</span> <span class="pre">method</span> <span class="pre">Logger.info</span> <span class="pre">of</span> <span class="pre">&lt;Logger</span> <span class="pre">pyinfra</span> <span class="pre">(WARNING)&gt;&gt;</span></span></em>, <em><span class="n"><span class="pre">**kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.api.host.Host.log_styled" title="Permalink to this definition">¶</a></dt>
+<code class="sig-name descname"><span class="pre">log_styled</span></code><span class="sig-paren">(</span><em><span class="pre">message:</span> <span class="pre">str,</span> <span class="pre">log_func:</span> <span class="pre">~typing.Callable[[str],</span> <span class="pre">~typing.Any]</span> <span class="pre">=</span> <span class="pre">&lt;bound</span> <span class="pre">method</span> <span class="pre">Logger.info</span> <span class="pre">of</span> <span class="pre">&lt;Logger</span> <span class="pre">pyinfra</span> <span class="pre">(WARNING)&gt;&gt;,</span> <span class="pre">**kwargs</span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#pyinfra.api.host.Host.log_styled" title="Permalink to this definition">¶</a></dt>
 <dd></dd></dl>
 
 <dl class="py method">
@@ -341,7 +341,7 @@ <h3>Navigation</h3>
 
 <dl class="py method">
 <dt class="sig sig-object py" id="pyinfra.api.host.Host.noop">
-<code class="sig-name descname"><span class="pre">noop</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">description</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyinfra.api.host.Host.noop" title="Permalink to this definition">¶</a></dt>
+<code class="sig-name descname"><span class="pre">noop</span></code><span class="sig-paren">(</span><em><span class="n"><span class="pre">description</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> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#pyinfra.api.host.Host.noop" title="Permalink to this definition">¶</a></dt>
 <dd><p>Log a description for a noop operation.</p>
 </dd></dl>
 

en/latest/facts.html

@@ -225,6 +225,7 @@ <h1>Facts Index<a class="headerlink" href="#facts-index" title="Permalink to thi
 <li class="toctree-l1"><a class="reference internal" href="facts/apt.html">Apt Facts</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="facts/apt.html#apt-aptkeys"><code class="code docutils literal notranslate"><span class="pre">apt.AptKeys</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="facts/apt.html#apt-aptsources"><code class="code docutils literal notranslate"><span class="pre">apt.AptSources</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="facts/apt.html#apt-simulateoperationwillchange"><code class="code docutils literal notranslate"><span class="pre">apt.SimulateOperationWillChange</span></code></a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="facts/brew.html">Brew Facts</a><ul>

en/latest/facts/apt.html

@@ -104,6 +104,7 @@ <h3>Navigation</h3>
 <li class="toctree-l2 current"><a class="current reference internal" href="#">Apt Facts</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#apt-aptkeys"><code class="code docutils literal notranslate"><span class="pre">apt.AptKeys</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="#apt-aptsources"><code class="code docutils literal notranslate"><span class="pre">apt.AptSources</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="#apt-simulateoperationwillchange"><code class="code docutils literal notranslate"><span class="pre">apt.SimulateOperationWillChange</span></code></a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="brew.html">Brew Facts</a></li>
@@ -217,6 +218,13 @@ <h1>Apt Facts<a class="headerlink" href="#apt-facts" title="Permalink to this he
 </pre></div>
 </div>
 </div>
+<div class="section" id="apt-simulateoperationwillchange">
+<span id="facts-apt-simulateoperationwillchange"></span><h2><code class="code docutils literal notranslate"><span class="pre">apt.SimulateOperationWillChange</span></code><a class="headerlink" href="#apt-simulateoperationwillchange" title="Permalink to this heading">¶</a></h2>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">host</span><span class="o">.</span><span class="n">get_fact</span><span class="p">(</span><span class="n">SimulateOperationWillChange</span><span class="p">,</span> <span class="n">command</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Simulate an ‘apt-get’ operation and try to detect if any changes would be performed.</p>
+</div>
 </div>
 
 

en/latest/operations/apt.html

@@ -190,7 +190,7 @@ <h3>Navigation</h3>
   <div class="section" id="apt-operations">
 <h1>Apt Operations<a class="headerlink" href="#apt-operations" title="Permalink to this heading">¶</a></h1>
 <p>Manage apt packages and repositories.</p>
-<p>Facts used in these operations: <a class="reference internal" href="../facts/apt.html#facts-apt-aptkeys"><span class="std std-ref">apt.AptKeys</span></a>, <a class="reference internal" href="../facts/apt.html#facts-apt-aptsources"><span class="std std-ref">apt.AptSources</span></a>, <a class="reference internal" href="../facts/server.html#facts-server-date"><span class="std std-ref">server.Date</span></a>, <a class="reference internal" href="../facts/deb.html#facts-deb-debpackage"><span class="std std-ref">deb.DebPackage</span></a>, <a class="reference internal" href="../facts/deb.html#facts-deb-debpackages"><span class="std std-ref">deb.DebPackages</span></a>, <a class="reference internal" href="../facts/files.html#facts-files-file"><span class="std std-ref">files.File</span></a>, <a class="reference internal" href="../facts/gpg.html#facts-gpg-gpgkey"><span class="std std-ref">gpg.GpgKey</span></a>.</p>
+<p>Facts used in these operations: <a class="reference internal" href="../facts/apt.html#facts-apt-aptkeys"><span class="std std-ref">apt.AptKeys</span></a>, <a class="reference internal" href="../facts/apt.html#facts-apt-aptsources"><span class="std std-ref">apt.AptSources</span></a>, <a class="reference internal" href="../facts/server.html#facts-server-date"><span class="std std-ref">server.Date</span></a>, <a class="reference internal" href="../facts/deb.html#facts-deb-debpackage"><span class="std std-ref">deb.DebPackage</span></a>, <a class="reference internal" href="../facts/deb.html#facts-deb-debpackages"><span class="std std-ref">deb.DebPackages</span></a>, <a class="reference internal" href="../facts/files.html#facts-files-file"><span class="std std-ref">files.File</span></a>, <a class="reference internal" href="../facts/gpg.html#facts-gpg-gpgkey"><span class="std std-ref">gpg.GpgKey</span></a>, <a class="reference internal" href="../facts/apt.html#facts-apt-simulateoperationwillchange"><span class="std std-ref">apt.SimulateOperationWillChange</span></a>.</p>
 <div class="section" id="apt-deb">
 <span id="operations-apt-deb"></span><h2><code class="code docutils literal notranslate"><span class="pre">apt.deb</span></code><a class="headerlink" href="#apt-deb" title="Permalink to this heading">¶</a></h2>
 <p>Add/remove <code class="docutils literal notranslate"><span class="pre">.deb</span></code> file packages.</p>
@@ -219,10 +219,6 @@ <h1>Apt Operations<a class="headerlink" href="#apt-operations" title="Permalink
 </div>
 <div class="section" id="apt-dist-upgrade">
 <span id="operations-apt-dist-upgrade"></span><h2><code class="code docutils literal notranslate"><span class="pre">apt.dist_upgrade</span></code><a class="headerlink" href="#apt-dist-upgrade" title="Permalink to this heading">¶</a></h2>
-<div class="important admonition">
-<p class="first admonition-title">Stateless operation</p>
-<p class="last">This operation will always execute commands and is not idempotent.</p>
-</div>
 <p>Updates all apt packages, employing dist-upgrade.</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">apt</span><span class="o">.</span><span class="n">dist_upgrade</span><span class="p">()</span>
 </pre></div>
@@ -390,10 +386,6 @@ <h1>Apt Operations<a class="headerlink" href="#apt-operations" title="Permalink
 </div>
 <div class="section" id="apt-upgrade">
 <span id="operations-apt-upgrade"></span><h2><code class="code docutils literal notranslate"><span class="pre">apt.upgrade</span></code><a class="headerlink" href="#apt-upgrade" title="Permalink to this heading">¶</a></h2>
-<div class="important admonition">
-<p class="first admonition-title">Stateless operation</p>
-<p class="last">This operation will always execute commands and is not idempotent.</p>
-</div>
 <p>Upgrades all apt packages.</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">apt</span><span class="o">.</span><span class="n">upgrade</span><span class="p">(</span><span class="n">auto_remove</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
 </pre></div>

en/next/_sources/facts/apt.rst.txt

@@ -46,3 +46,15 @@ Returns a list of installed apt sources:
         },
     ]
 
+
+.. _facts:apt.SimulateOperationWillChange:
+
+:code:`apt.SimulateOperationWillChange`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+    host.get_fact(SimulateOperationWillChange, command)
+
+Simulate an 'apt-get' operation and try to detect if any changes would be performed.
+