pyinfra 3.5.1__tar.gz → 3.6__tar.gz

{pyinfra-3.5.1 → pyinfra-3.6}/.github/workflows/test.yml

@@ -50,10 +50,19 @@ jobs:
     needs:
       - lint
       - type-check
+      - spell-check
     strategy:
       matrix:
-        os: [ubuntu-22.04, ubuntu-24.04, macos-13, macos-14, macos-15,windows-2022, windows-2025]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [macos-26, macos-15, macos-14, windows-2025, windows-2022, ubuntu-24.04, ubuntu-22.04]
+        # Test every OS vs. Python 3.13, and only one for 3.1[012]
+        python-version: ["3.13"]
+        include:
+          - os: ubuntu-24.04
+            python-version: "3.12"
+          - os: ubuntu-24.04
+            python-version: "3.11"
+          - os: ubuntu-24.04
+            python-version: "3.10"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v5
@@ -75,27 +84,24 @@ jobs:
     needs:
       - lint
       - type-check
+      - spell-check
     strategy:
       matrix:
         os: [ubuntu-22.04, ubuntu-24.04]
         test-name: [local, ssh, docker, podman]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
         include:
-          - os: macos-13
-            test-name: local
-            python-version: "3.13"
           - os: macos-14
             test-name: local
-            python-version: "3.13"
           - os: macos-15
             test-name: local
-            python-version: "3.13"
+          - os: macos-26
+            test-name: local
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.13"
       - name: Install uv
         uses: astral-sh/setup-uv@v6
       - run: uv sync --group test --no-default-groups --python=${{ matrix.python-version }}
@@ -108,6 +114,7 @@ jobs:
     needs:
       - lint
       - type-check
+      - spell-check
       - unit-test
       - end-to-end-test
     runs-on: ubuntu-latest

{pyinfra-3.5.1 → pyinfra-3.6}/CHANGELOG.md

@@ -1,3 +1,52 @@
+# v3.6
+
+First 2026 release - Happy New Year all! Thank you to all contributors. One big highlight is new metadata spec for plugins, this is the start of better discovery and documentation generation for third party facts and operations:
+
+- add metadata spec for pyinfra plugins (@rod7760)
+
+New and updated operations/facts:
+
+- operations: add `_temp_dir` global argument for configuring temp directory (@wowi42)
+- operations: add `files.copy` operation (@EricDriussi)
+- operations.crontab: fix modification not properly relying on the `cron_name` parameter (@information-redacted)
+- operations.docker.container: add support for setting labels (@spookyvision)
+- operations: add import statements on at least one example of every operation (@mkinney)
+- operations.docker.image: make operation idempotent (@DonDebonair)
+- operations.files.template: allow custom jinja2 template loaders (@DaRasch)
+- operations.files.block/connectors.util: use correct temporary directory (@morrison12)
+- operations.util.packaging: allow empty package list in `ensure_packages` (@schenker)
+- operations: fix tmpdir to properly use all the POSIX environment variables (@wowi42)
+- facts.files.FileContents: improve docstring (@adonm)
+- facts.apt.update: fix computation of cache_time when host is not UTC (@philippemilink)
+- facts: add `FactProcessError` to log, not explode, issues processing facts (@NichtJens)
+- facts.npm: check directory exists before cd-ing (wowi42)
+
+Connectors:
+
+- connectors.docker: add platform and architecture option via connector data (@JP-Ellis)
+- connectors: close stdin after writing any input
+- connectors.ssh: add workaround for paramiko no session error (@dfaerch)
+
+CLI:  
+
+- cli: change color of "No changes" to cyan
+- cli: add option `--same-sudo-password` (@philippemilink)
+
+Docs/meta:
+
+- docs: replace `python -m` with `uv run -m` (@JP-Ellis)
+- docs: fix URLs in API documentation (@kelno)
+- docs/connectors: document command wrapping and parameter filtering best practices (@elazar)
+- tests: freeze date for fact tests
+
+# v3.5.3
+
+- another release to fix different doc generation issues 🫠
+
+# v3.5.2
+
+- fix operation & fact docs generation
+
 # v3.5.1
 
 Patch release with a bunch of great fixes. But notably want to call out two major changes for anyone working on the pyinfra code itself (huge thank you Daan for implementing these):
@@ -40,6 +89,7 @@ New release with some really awesome new features, brought to you by the fantast
 - enable using SCP instead of SFTP for SSH file transfers (@DonDebonair)
 
 New and updated operations/facts:
+
 - facts/server: add `RebootRequired` fact (@wowi42)
 - operations/pip: support PEP-508 package versions (@morrison12)
 - operations+facts/docker: add Docker plugin support (@DonDebonair)

{pyinfra-3.5.1 → pyinfra-3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyinfra
-Version: 3.5.1
+Version: 3.6
 Summary: pyinfra automates/provisions/manages/deploys infrastructure.
 Project-URL: homepage, https://pyinfra.com
 Project-URL: documentation, https://docs.pyinfra.com
@@ -29,6 +29,7 @@ Requires-Dist: gevent>=1.5
 Requires-Dist: jinja2<4,>3
 Requires-Dist: packaging>=16.1
 Requires-Dist: paramiko<4,>=2.7
+Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: python-dateutil<3,>2
 Requires-Dist: typeguard<5,>=4
 Requires-Dist: typing-extensions; python_version < '3.11'

{pyinfra-3.5.1 → pyinfra-3.6}/docs/api/connectors.md

@@ -56,7 +56,7 @@ class MyConnector(BaseConnector):
     @staticmethod
     def make_names_data(_=None):
         ...  # see above
- 
+
     def run_shell_command(
         self,
         command: StringCommand,
@@ -191,6 +191,60 @@ screen.
 `disconnect` can be used after all operations complete to clean up any connection/s remaining to the hosts being managed.
 
 
+## Implementing `run_shell_command`
+
+When implementing `run_shell_command`, connectors should use pyinfra's command wrapping utilities rather than manually constructing commands. The `make_unix_command_for_host()` function from `pyinfra.connectors.util` handles shell wrapping, sudo elevation, environment variables, working directory changes, command retries and shell executable selection.
+
+Its worth being aware that when passing `arguments` to `make_unix_command_for_host()`, connector control parameters must be filtered out. These parameters (`_success_exit_codes`, `_timeout`, `_get_pty`, `_stdin`) are defined in `pyinfra.api.arguments.ConnectorArguments` and are meant for the connector's internal logic after command generation, not for command construction itself.
+
+The recommended approach is to use `extract_control_arguments()` from `pyinfra.connectors.util` which handles this filtering for you:
+
+```py
+from pyinfra.connectors.util import extract_control_arguments, make_unix_command_for_host
+
+class MyConnector(BaseConnector):
+    handles_execution = True
+
+    def run_shell_command(
+        self,
+        command: StringCommand,
+        print_output: bool = False,
+        print_input: bool = False,
+        **arguments: Unpack["ConnectorArguments"],
+    ) -> Tuple[bool, CommandOutput]:
+        """Execute a command with proper shell wrapping."""
+
+        # Extract and remove control parameters from arguments
+        # This modifies arguments dict in place and returns the extracted params
+        control_args = extract_control_arguments(arguments)
+
+        # Generate properly wrapped command with sudo, environment, etc
+        # arguments now contains only command generation parameters
+        wrapped_command = make_unix_command_for_host(
+            self.state,
+            self.host,
+            command,
+            **arguments,
+        )
+
+        # Use control parameters for execution
+        timeout = control_args.get("_timeout")
+        success_exit_codes = control_args.get("_success_exit_codes", [0])
+
+        # Execute the wrapped command using your connector's method
+        exit_code, output = self._execute(wrapped_command, timeout=timeout)
+
+        # Check success based on exit codes
+        success = exit_code in success_exit_codes
+
+        return success, output
+```
+
+Without proper command wrapping, shell operators and complex commands will fail. For example `timeout 60 bash -c 'command' || true` executed without shell wrapping will result in `bash: ||: command not found`. PyInfra operations and fact gathering rely on shell operators (`&&`, `||`, pipes, redirects) so using `make_unix_command_for_host()` ensures your connector handles these correctly.
+
+For complete examples see pyinfra's built-in connectors in `pyinfra/connectors/docker.py`, `pyinfra/connectors/chroot.py`, `pyinfra/connectors/ssh.py` and `pyinfra/connectors/local.py`, as well as the command wrapping utilities in `pyinfra/connectors/util.py`.
+
+
 ## 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`:

{pyinfra-3.5.1 → pyinfra-3.6}/docs/api/index.rst

@@ -3,7 +3,7 @@ Using the API
 
 In addition to :doc:`the pyinfra CLI <../cli>`, pyinfra provides a full Python API. As of ``v3`` this API can be considered mostly stable. See the :doc:`./reference`.
 
-You can also reference `pyinfra's own main.py <https://github.com/pyinfra-dev/pyinfra/blob/3.x/pyinfra_cli/main.py>`_, and the `pyinfra API source code <https://github.com/pyinfra-dev/pyinfra/tree/3.x/pyinfra/api>`_.
+You can also reference `pyinfra's own main.py <https://github.com/pyinfra-dev/pyinfra/blob/3.x/src/pyinfra_cli/main.py>`_, and the `pyinfra API source code <https://github.com/pyinfra-dev/pyinfra/tree/3.x/src/pyinfra/api>`_.
 
 Full Example
 ------------

{pyinfra-3.5.1 → pyinfra-3.6}/docs/cli.md

@@ -77,7 +77,7 @@ pyinfra @local ...
 pyinfra my-server.net,@local ...
 
 # Execute against a Docker container
-pyinfra @docker/centos:8 ...
+pyinfra @docker/fedora:43 ...
 ```
 
 ### Limit
@@ -132,7 +132,7 @@ For example, here we ensure that `nginx` is installed on the remote servers:
 # Ubuntu example
 pyinfra inventory.py apt.packages nginx update=true _sudo=true
 
-# Centos example
+# Fedora example
 pyinfra inventory2.py yum.packages nginx _sudo=true
 ```
 

{pyinfra-3.5.1 → pyinfra-3.6}/docs/compatibility.md

@@ -27,10 +27,9 @@ To debug pyinfra within PyCharm, you need to [explicitly enable support for Geve
 pyinfra aims to be compatible with all Unix-like operating systems and is currently developed against:
 
 + Linux distros:
-    * Ubuntu 18/20
+    * Ubuntu 20/22/24
     * Debian 9/10
-    * CentOS 7/8
-    * Fedora 33
+    * Fedora 43
     * Alpine 3.8
 + BSD flavours:
     * OpenBSD 6

{pyinfra-3.5.1 → pyinfra-3.6}/docs/conf.py

@@ -5,6 +5,7 @@ from shutil import rmtree
 import guzzle_sphinx_theme
 
 from pyinfra import __version__, local
+from pyinfra.api import metadata
 
 copyright = "Nick Barrett {0} — pyinfra v{1}".format(
     date.today().year,
@@ -57,9 +58,42 @@ exclude_patterns = [
 ]
 
 
+def rstjinja(app, docname, source):
+    """
+    Render certain pages as a jinja templates.
+    """
+    # this should only be run when building html
+    if app.builder.format != "html":
+        return
+    # We currently only render docs/operations.rst
+    # and docs/facts.rst as jinja2 templates
+    if docname in ["operations", "facts"]:
+        src = source[0]
+        rendered = app.builder.templates.render_string(src, app.config.html_context)
+        source[0] = rendered
+
+
 def setup(app):
+    app.connect("source-read", rstjinja)
     this_dir = path.dirname(path.realpath(__file__))
     scripts_dir = path.abspath(path.join(this_dir, "..", "scripts"))
+    metadata_file = path.abspath(path.join(this_dir, "..", "pyinfra-metadata.toml"))
+    if not path.exists(metadata_file):
+        raise ValueError("No pyinfra-metadata.toml in project root")
+    with open(metadata_file, "r") as file:
+        metadata_text = file.read()
+    plugins = metadata.parse_plugins(metadata_text)
+
+    operation_plugins = sorted([p for p in plugins if p.type == "operation"], key=lambda p: p.name)
+    fact_plugins = sorted([p for p in plugins if p.type == "fact"], key=lambda p: p.name)
+    html_context = {
+        "operation_plugins": operation_plugins,
+        "fact_plugins": fact_plugins,
+        "tags": metadata.ALLOWED_TAGS,
+        "docs_language": language,
+        "docs_version": version,
+    }
+    app.config.html_context = html_context
 
     for auto_docs_name in ("operations", "facts", "apidoc", "connectors"):
         auto_docs_path = path.join(this_dir, auto_docs_name)

{pyinfra-3.5.1 → pyinfra-3.6}/docs/connectors.rst

@@ -1,6 +1,14 @@
 Connectors Index
 ================
 
+.. raw:: html
+
+  <nav class="under-title-tabs">
+    See also:
+    <a href="operations.html">Operations Index</a>
+    <a href="facts.html">Facts Index</a>
+  </nav>
+
 Connectors enable pyinfra to integrate with other tools out of the box. Connectors can do one of three things:
 
 + Implement how commands are executed (``@ssh``, ``@local``)

{pyinfra-3.5.1 → pyinfra-3.6}/docs/contributing.md

@@ -35,7 +35,7 @@ uv sync
 
 ### Code Style & Type Checking
 
-Code style is enforced via [ruff](https://docs.astral.sh/ruff/). Types are checked with mypy currently, and pyright is 
+Code style is enforced via [ruff](https://docs.astral.sh/ruff/). Types are checked with mypy currently, and pyright is
 recommended for local development though currently optional. There is a script to run the linting & type-checking:
 
 ```sh
@@ -96,5 +96,5 @@ scripts/build-public-docs.sh
 To view ([localhost:8000](http://localhost:8000)):
 
 ```sh
-python -m http.server -d docs/public/en/latest/
+uv run -m http.server -d docs/public/en/latest/
 ```

pyinfra-3.6/docs/facts.rst

@@ -0,0 +1,102 @@
+Facts Index
+===========
+
+.. raw:: html
+
+  <nav class="under-title-tabs">
+    See also:
+    <a href="operations.html">Operations Index</a>
+    <a href="connectors.html">Connectors Index</a>
+  </nav>
+
+pyinfra uses **facts** to determine the existing state of a remote server. Operations use this information to generate commands which alter the state. Facts are read-only and are populated at the beginning of the deploy.
+
+Facts can be executed/tested via the command line:
+
+.. code:: sh
+
+    # Example how to get multiple facts from a server myhost.com
+    pyinfra myhost.com fact server.Date server.Hostname ...
+
+If you want to pass an argument to a fact, pass it with ``key=value``. For example:
+
+.. code:: sh
+
+    # See if the package 'openssh-server' is installed servers myhost.com and myhost2.com
+    pyinfra myhost.com,myhost2.com fact deb.DebPackage name=openssh-server
+
+Multiple facts with arguments may be called like so:
+
+.. code:: sh
+
+    pyinfra @local fact files.File path=setup.py files.File path=anotherfile.txt
+
+You can leverage facts within :doc:`operations <using-operations>` like this:
+
+.. code:: py
+
+    from pyinfra import host
+    from pyinfra.facts.server import LinuxName
+
+    if host.get_fact(LinuxName) == 'Ubuntu':
+        apt.packages(...)
+
+**Want a new fact?** Check out :doc:`the writing facts guide <./api/operations>`.
+
+.. raw:: html
+
+        <div class="container my-4">
+          <!-- Dropdown Filter -->
+          <div class="mb-4">
+            <label for="tag-dropdown" class="form-label">Filter by Tag:</label>
+            <select class="form-select" id="tag-dropdown">
+	      <option value="All">All</option>
+{% for tag in tags %}
+              <option value="{{ tag.title_case }}">{{ tag.title_case }}</option>
+{% endfor %}
+            </select>
+          </div>
+
+          <!-- Cards Grid -->
+          <div class="row" id="card-container">
+{% for plugin in fact_plugins %}
+            <div class="col-md-4 mb-4 card-item">
+              <div class="card h-100">
+                <div class="card-body">
+                  <h5 class="card-title">
+                    <a href="./facts/{{ plugin.name }}.html">
+                      {{ plugin.name }}
+                    </a>
+                  <p class="card-text">{{ plugin.description }}</p>
+{% for tag in plugin.tags %}
+                  <span class="badge bg-secondary">{{ tag.title_case }}</span>
+{% endfor %}
+                </div>
+              </div>
+            </div>
+{% endfor %}
+          </div>
+        </div>
+        <script>
+          document.getElementById('tag-dropdown').addEventListener('change', function () {
+            const selectedTag = this.value;
+            const cards = document.querySelectorAll('.card-item');
+
+            cards.forEach(card => {
+              const tags = Array.from(card.querySelectorAll('.badge')).map(badge => badge.textContent.trim());
+
+              if (selectedTag === 'All' || tags.includes(selectedTag)) {
+                card.style.display = 'block';
+              } else {
+                card.style.display = 'none';
+              }
+            });
+          });
+        </script>
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+   :hidden:
+
+   facts/*

{pyinfra-3.5.1 → pyinfra-3.6}/docs/faq.rst

@@ -20,6 +20,7 @@ The currently executing host can be fetched from the ``host`` context variable.
     # Get the actual current hostname from the host
     from pyinfra.facts.server import Hostname
     hostname = host.get_fact(Hostname)
+    print(f"hostname:{hostname}")
 
 How do I use sudo in an operation?
 ----------------------------------
@@ -28,6 +29,7 @@ Sudo is controlled by one of the `privilege and user escalation arguments <argum
 
 .. code:: python
 
+    from pyinfra.operations import apt
     apt.packages(
         packages=["iftop"],
         _sudo=True,
@@ -43,6 +45,7 @@ Use the LINK ``files.file``, ``files.directory`` or ``files.link`` operations to
 
 .. code:: python
 
+    from pyinfra.operations import files
     files.file(
         path="/etc/default/elasticsearch",
         user="pyinfra",
@@ -57,6 +60,7 @@ Use the `retry behavior arguments <arguments.html#retry-behavior>`_ to automatic
 
 .. code:: python
 
+    from pyinfra.operations import server
     # Retry a network operation up to 3 times
     server.shell(
         name="Download file with retries",

{pyinfra-3.5.1 → pyinfra-3.6}/docs/getting-started.rst

@@ -29,8 +29,11 @@ You can start pyinfra immediately with some ad-hoc command execution. The CLI al
     # Execute over SSH
     pyinfra my-server.net exec -- echo "hello world"
 
+    # Execute over SSH with options
+    pyinfra localhost --ssh-port 2222 --ssh-user vagrant exec -- echo "hello world"
+
     # Execute within a new docker container
-    pyinfra @docker/ubuntu:18.04 exec -- echo "hello world"
+    pyinfra @docker/ubuntu:22.04 exec -- echo "hello world"
 
     # Execute on the local machine (MacOS/Linux only - for now)
     pyinfra @local exec -- echo "hello world"
@@ -66,8 +69,19 @@ To get started create an ``inventory.py`` containing our hosts to target:
 
 .. code:: python
 
-    # Define a group as a list of hosts
-    my_hosts = ["my-server.net", "@docker/ubuntu:18.04"]
+     # Define a group as a list of hosts
+     my_hosts = [
+        # vagrant instance
+        ("ubuntu2204", {
+           "ssh_port": 2222,
+           "ssh_hostname": "localhost",
+           "ssh_user": "vagrant",
+           "_sudo": True
+        }),
+       "my-server.net",
+       "@docker/ubuntu:22.04"
+     ]
+
 
 Now create a ``deploy.py`` containing our operations to execute:
 
@@ -79,7 +93,7 @@ Now create a ``deploy.py`` containing our operations to execute:
     apt.packages(
         name="Ensure the vim apt package is installed",
         packages=["vim"],
-        _sudo=True,  # use sudo when installing the packages
+        update=True,
     )
 
 This can now be executed like this:

pyinfra-3.6/docs/operations.rst

@@ -0,0 +1,73 @@
+Operations Index
+================
+
+.. raw:: html
+
+  <nav class="under-title-tabs">
+    See also:
+    <a href="facts.html">Facts Index</a>
+    <a href="connectors.html">Connectors Index</a>
+  </nav>
+
+Operations are used to describe changes to make to systems in the inventory. Use them to define state and pyinfra will make any necessary changes to reach that state. All operations accept a set of :doc:`global arguments <arguments>` and are grouped as Python modules.
+
+**Want a new operation?** Check out :doc:`the writing operations guide <./api/operations>`.
+
+.. raw:: html
+
+        <div class="container my-4">
+          <!-- Dropdown Filter -->
+          <div class="mb-4">
+            <label for="tag-dropdown" class="form-label">Filter by Tag:</label>
+            <select class="form-select" id="tag-dropdown">
+	      <option value="All">All</option>
+{% for tag in tags %}
+              <option value="{{ tag.title_case }}">{{ tag.title_case }}</option>
+{% endfor %}
+            </select>
+          </div>
+
+          <!-- Cards Grid -->
+          <div class="row" id="card-container">
+{% for plugin in operation_plugins %}
+            <div class="col-md-4 mb-4 card-item">
+              <div class="card h-100">
+                <div class="card-body">
+                  <h5 class="card-title">
+                    <a href="./operations/{{ plugin.name }}.html">
+                      {{ plugin.name }}
+                    </a>
+                  </h5>
+                  <p class="card-text">{{ plugin.description }}</p>
+{% for tag in plugin.tags %}
+                  <span class="badge bg-secondary">{{ tag.title_case }}</span>
+{% endfor %}
+                </div>
+              </div>
+            </div>
+{% endfor %}
+          </div>
+        </div>
+        <script>
+          document.getElementById('tag-dropdown').addEventListener('change', function () {
+            const selectedTag = this.value;
+            const cards = document.querySelectorAll('.card-item');
+
+            cards.forEach(card => {
+              const tags = Array.from(card.querySelectorAll('.badge')).map(badge => badge.textContent.trim());
+
+              if (selectedTag === 'All' || tags.includes(selectedTag)) {
+                card.style.display = 'block';
+              } else {
+                card.style.display = 'none';
+              }
+            });
+          });
+        </script>
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+   :hidden:
+
+   operations/*