Docs build 2025-04-07

Author: github-actions

en/latest/_sources/api/connectors.md.txt

@@ -45,27 +45,6 @@ The connector can also be run using `pyinfra @[name of connector in pyinfra.conn
 (inventory/data requested for a single host), `make_names_data(_=None)` should be updated to `make_names_data(name)` and the `name == None` case
 handled in code separately from `name` being a valid string.
 
-Its worth being aware up front that due to `make_names_data` being a `staticmethod` it has no automatic access to the parent classes attributes.
-To work around this - eg to configure an API connector - configuration will have to happen outside the function and be imported in. Two examples
-(`getattr` and a function) are provided below.
-
-```py
-def load_settings():
-  settings = {}
-  # logic here
-  return settings
-
-class InventoryConnector(BaseConnector):
-  api_instance = external.ApiClient()
-  ...
-
-  @staticmethod
-  def make_names_data(_=None)
-    api_client = getattr(InventoryConnector, 'api_instance')
-    api_settings = load_settings()
-    ...
-```
-
 ## Executing Connector
 
 A connector that implements execution requires a few more methods:
@@ -136,6 +115,71 @@ class LocalConnector(BaseConnector):
         """
 ```
 
+## Where to make changes
+
+Connectors enable pyinfra to expand work done `in its 5 stages <deploy-process.html#how-pyinfra-works>`_ by providing methods which can be called at
+appropriate times.
+
+To hook in to to the various steps with the methods outlined below.
+```
+--> Loading config...
+--> Loading inventory...
+```
+`make_names_data` is used to supply inventory data about a host while at 'Loading inventory' stage.
+
+Its worth being aware up front that due to `make_names_data` being a `staticmethod` it has no automatic access to the parent classes attributes.
+To work around this - eg to configure an API connector - configuration will have to happen outside the function and be imported in. Two examples
+(`getattr` and a function) are provided below.
+
+```py
+def load_settings():
+  settings = {}
+  # logic here
+  return settings
+
+class InventoryConnector(BaseConnector):
+  api_instance = external.ApiClient()
+  ...
+
+  @staticmethod
+  def make_names_data(_=None)
+    api_client = getattr(InventoryConnector, 'api_instance')
+    api_settings = load_settings()
+    ...
+```
+
+```
+--> Connecting to hosts...
+    [pytest.example.com] Connected
+```
+`connect` can be used to check access to a host is possible. If the connection fails `ConnectError` should be raised with a message to display on
+screen.
+
+```
+--> Preparing operations...
+--> Preparing Operations...
+    Loading: deploy_create_users.py
+    [pytest.example.com] Ready: deploy_create_users.py
+
+--> Detected changes:
+[list of changes here]
+
+--> Beginning operation run...
+--> Starting operation: sshd_install.py | Install OpenSSH server
+    [pytest.example.com] No changes
+```
+
+`run_shell_command`, `put_file`, `get_file` and `rsync` can be used to change behaviour of pyinfra as it performs operations.
+
+```
+--> Results:
+    Operation                                                                                            Hosts   Success   Error   No Change
+--> Disconnecting from hosts...
+```
+
+`disconnect` can be used after all operations complete to clean up any connection/s remaining to the hosts being managed.
+
+
 ## pyproject.toml
 
 In order for pyinfra to gain knowledge about your connector, you need to add the following snippet to your connector's `pyproject.toml`:

en/latest/api/connectors.html

@@ -108,6 +108,7 @@ <h3>Navigation</h3>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Writing Connectors</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#inventory-connector">Inventory Connector</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#executing-connector">Executing Connector</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#where-to-make-changes">Where to make changes</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#pyproject-toml">pyproject.toml</a></li>
 </ul>
 </li>
@@ -178,25 +179,6 @@ <h2>Inventory Connector<a class="headerlink" href="#inventory-connector" title="
 <p>The connector can also be run using <code class="docutils literal notranslate"><span class="pre">pyinfra</span> <span class="pre">&#64;[name</span> <span class="pre">of</span> <span class="pre">connector</span> <span class="pre">in</span> <span class="pre">pyinfra.connectors]/[hostname]</span> <span class="pre">[deployment</span> <span class="pre">script].py</span></code>. If executed this way
 (inventory/data requested for a single host), <code class="docutils literal notranslate"><span class="pre">make_names_data(_=None)</span></code> should be updated to <code class="docutils literal notranslate"><span class="pre">make_names_data(name)</span></code> and the <code class="docutils literal notranslate"><span class="pre">name</span> <span class="pre">==</span> <span class="pre">None</span></code> case
 handled in code separately from <code class="docutils literal notranslate"><span class="pre">name</span></code> being a valid string.</p>
-<p>Its worth being aware up front that due to <code class="docutils literal notranslate"><span class="pre">make_names_data</span></code> being a <code class="docutils literal notranslate"><span class="pre">staticmethod</span></code> it has no automatic access to the parent classes attributes.
-To work around this - eg to configure an API connector - configuration will have to happen outside the function and be imported in. Two examples
-(<code class="docutils literal notranslate"><span class="pre">getattr</span></code> and a function) are provided below.</p>
-<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">load_settings</span><span class="p">():</span>
-  <span class="n">settings</span> <span class="o">=</span> <span class="p">{}</span>
-  <span class="c1"># logic here</span>
-  <span class="k">return</span> <span class="n">settings</span>
-
-<span class="k">class</span> <span class="nc">InventoryConnector</span><span class="p">(</span><span class="n">BaseConnector</span><span class="p">):</span>
-  <span class="n">api_instance</span> <span class="o">=</span> <span class="n">external</span><span class="o">.</span><span class="n">ApiClient</span><span class="p">()</span>
-  <span class="o">...</span>
-
-  <span class="nd">@staticmethod</span>
-  <span class="k">def</span> <span class="nf">make_names_data</span><span class="p">(</span><span class="n">_</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
-    <span class="n">api_client</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">InventoryConnector</span><span class="p">,</span> <span class="s1">&#39;api_instance&#39;</span><span class="p">)</span>
-    <span class="n">api_settings</span> <span class="o">=</span> <span class="n">load_settings</span><span class="p">()</span>
-    <span class="o">...</span>
-</pre></div>
-</div>
 </section>
 <section id="executing-connector">
 <h2>Executing Connector<a class="headerlink" href="#executing-connector" title="Link to this heading">¶</a></h2>
@@ -267,6 +249,62 @@ <h2>Executing Connector<a class="headerlink" href="#executing-connector" title="
 </pre></div>
 </div>
 </section>
+<section id="where-to-make-changes">
+<h2>Where to make changes<a class="headerlink" href="#where-to-make-changes" title="Link to this heading">¶</a></h2>
+<p>Connectors enable pyinfra to expand work done <code class="docutils literal notranslate"><span class="pre">in</span> <span class="pre">its</span> <span class="pre">5</span> <span class="pre">stages</span> <span class="pre">&lt;deploy-process.html#how-pyinfra-works&gt;</span></code>_ by providing methods which can be called at
+appropriate times.</p>
+<p>To hook in to to the various steps with the methods outlined below.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--&gt;</span> <span class="n">Loading</span> <span class="n">config</span><span class="o">...</span>
+<span class="o">--&gt;</span> <span class="n">Loading</span> <span class="n">inventory</span><span class="o">...</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">make_names_data</span></code> is used to supply inventory data about a host while at ‘Loading inventory’ stage.</p>
+<p>Its worth being aware up front that due to <code class="docutils literal notranslate"><span class="pre">make_names_data</span></code> being a <code class="docutils literal notranslate"><span class="pre">staticmethod</span></code> it has no automatic access to the parent classes attributes.
+To work around this - eg to configure an API connector - configuration will have to happen outside the function and be imported in. Two examples
+(<code class="docutils literal notranslate"><span class="pre">getattr</span></code> and a function) are provided below.</p>
+<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">load_settings</span><span class="p">():</span>
+  <span class="n">settings</span> <span class="o">=</span> <span class="p">{}</span>
+  <span class="c1"># logic here</span>
+  <span class="k">return</span> <span class="n">settings</span>
+
+<span class="k">class</span> <span class="nc">InventoryConnector</span><span class="p">(</span><span class="n">BaseConnector</span><span class="p">):</span>
+  <span class="n">api_instance</span> <span class="o">=</span> <span class="n">external</span><span class="o">.</span><span class="n">ApiClient</span><span class="p">()</span>
+  <span class="o">...</span>
+
+  <span class="nd">@staticmethod</span>
+  <span class="k">def</span> <span class="nf">make_names_data</span><span class="p">(</span><span class="n">_</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
+    <span class="n">api_client</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">InventoryConnector</span><span class="p">,</span> <span class="s1">&#39;api_instance&#39;</span><span class="p">)</span>
+    <span class="n">api_settings</span> <span class="o">=</span> <span class="n">load_settings</span><span class="p">()</span>
+    <span class="o">...</span>
+</pre></div>
+</div>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--&gt;</span> <span class="n">Connecting</span> <span class="n">to</span> <span class="n">hosts</span><span class="o">...</span>
+    <span class="p">[</span><span class="n">pytest</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">]</span> <span class="n">Connected</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">connect</span></code> can be used to check access to a host is possible. If the connection fails <code class="docutils literal notranslate"><span class="pre">ConnectError</span></code> should be raised with a message to display on
+screen.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--&gt;</span> <span class="n">Preparing</span> <span class="n">operations</span><span class="o">...</span>
+<span class="o">--&gt;</span> <span class="n">Preparing</span> <span class="n">Operations</span><span class="o">...</span>
+    <span class="n">Loading</span><span class="p">:</span> <span class="n">deploy_create_users</span><span class="o">.</span><span class="n">py</span>
+    <span class="p">[</span><span class="n">pytest</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">]</span> <span class="n">Ready</span><span class="p">:</span> <span class="n">deploy_create_users</span><span class="o">.</span><span class="n">py</span>
+
+<span class="o">--&gt;</span> <span class="n">Detected</span> <span class="n">changes</span><span class="p">:</span>
+<span class="p">[</span><span class="nb">list</span> <span class="n">of</span> <span class="n">changes</span> <span class="n">here</span><span class="p">]</span>
+
+<span class="o">--&gt;</span> <span class="n">Beginning</span> <span class="n">operation</span> <span class="n">run</span><span class="o">...</span>
+<span class="o">--&gt;</span> <span class="n">Starting</span> <span class="n">operation</span><span class="p">:</span> <span class="n">sshd_install</span><span class="o">.</span><span class="n">py</span> <span class="o">|</span> <span class="n">Install</span> <span class="n">OpenSSH</span> <span class="n">server</span>
+    <span class="p">[</span><span class="n">pytest</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">]</span> <span class="n">No</span> <span class="n">changes</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">run_shell_command</span></code>, <code class="docutils literal notranslate"><span class="pre">put_file</span></code>, <code class="docutils literal notranslate"><span class="pre">get_file</span></code> and <code class="docutils literal notranslate"><span class="pre">rsync</span></code> can be used to change behaviour of pyinfra as it performs operations.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--&gt;</span> <span class="n">Results</span><span class="p">:</span>
+    <span class="n">Operation</span>                                                                                            <span class="n">Hosts</span>   <span class="n">Success</span>   <span class="n">Error</span>   <span class="n">No</span> <span class="n">Change</span>
+<span class="o">--&gt;</span> <span class="n">Disconnecting</span> <span class="kn">from</span> <span class="nn">hosts...</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">disconnect</span></code> can be used after all operations complete to clean up any connection/s remaining to the hosts being managed.</p>
+</section>
 <section id="pyproject-toml">
 <h2>pyproject.toml<a class="headerlink" href="#pyproject-toml" title="Link to this heading">¶</a></h2>
 <p>In order for pyinfra to gain knowledge about your connector, you need to add the following snippet to your connector’s <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>:</p>

en/latest/objects.inv

@@ -45,27 +45,6 @@ The connector can also be run using `pyinfra @[name of connector in pyinfra.conn
 (inventory/data requested for a single host), `make_names_data(_=None)` should be updated to `make_names_data(name)` and the `name == None` case
 handled in code separately from `name` being a valid string.
 
-Its worth being aware up front that due to `make_names_data` being a `staticmethod` it has no automatic access to the parent classes attributes.
-To work around this - eg to configure an API connector - configuration will have to happen outside the function and be imported in. Two examples
-(`getattr` and a function) are provided below.
-
-```py
-def load_settings():
-  settings = {}
-  # logic here
-  return settings
-
-class InventoryConnector(BaseConnector):
-  api_instance = external.ApiClient()
-  ...
-
-  @staticmethod
-  def make_names_data(_=None)
-    api_client = getattr(InventoryConnector, 'api_instance')
-    api_settings = load_settings()
-    ...
-```
-
 ## Executing Connector
 
 A connector that implements execution requires a few more methods:
@@ -136,6 +115,71 @@ class LocalConnector(BaseConnector):
         """
 ```
 
+## Where to make changes
+
+Connectors enable pyinfra to expand work done `in its 5 stages <deploy-process.html#how-pyinfra-works>`_ by providing methods which can be called at
+appropriate times.
+
+To hook in to to the various steps with the methods outlined below.
+```
+--> Loading config...
+--> Loading inventory...
+```
+`make_names_data` is used to supply inventory data about a host while at 'Loading inventory' stage.
+
+Its worth being aware up front that due to `make_names_data` being a `staticmethod` it has no automatic access to the parent classes attributes.
+To work around this - eg to configure an API connector - configuration will have to happen outside the function and be imported in. Two examples
+(`getattr` and a function) are provided below.
+
+```py
+def load_settings():
+  settings = {}
+  # logic here
+  return settings
+
+class InventoryConnector(BaseConnector):
+  api_instance = external.ApiClient()
+  ...
+
+  @staticmethod
+  def make_names_data(_=None)
+    api_client = getattr(InventoryConnector, 'api_instance')
+    api_settings = load_settings()
+    ...
+```
+
+```
+--> Connecting to hosts...
+    [pytest.example.com] Connected
+```
+`connect` can be used to check access to a host is possible. If the connection fails `ConnectError` should be raised with a message to display on
+screen.
+
+```
+--> Preparing operations...
+--> Preparing Operations...
+    Loading: deploy_create_users.py
+    [pytest.example.com] Ready: deploy_create_users.py
+
+--> Detected changes:
+[list of changes here]
+
+--> Beginning operation run...
+--> Starting operation: sshd_install.py | Install OpenSSH server
+    [pytest.example.com] No changes
+```
+
+`run_shell_command`, `put_file`, `get_file` and `rsync` can be used to change behaviour of pyinfra as it performs operations.
+
+```
+--> Results:
+    Operation                                                                                            Hosts   Success   Error   No Change
+--> Disconnecting from hosts...
+```
+
+`disconnect` can be used after all operations complete to clean up any connection/s remaining to the hosts being managed.
+
+
 ## pyproject.toml
 
 In order for pyinfra to gain knowledge about your connector, you need to add the following snippet to your connector's `pyproject.toml`: