Docs build 2024-06-25

Author: github-actions

en/3.x/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: dcc57fcbe3feb18b33b0002b1af024a8
+config: 4b6280c49beb6599c8ef6e2bc36ec362
 tags: 645f666f9bcd5a90fca523b33c5a78b7

en/3.x/_sources/api/connectors.md.txt

@@ -1,6 +1,6 @@
 # Writing Connectors
 
-[Connectors](../connectors) enable pyinfra to directly integrate with other tools and systems. Connectos are written as Python classes.
+[Connectors](../connectors) enable pyinfra to directly integrate with other tools and systems. Connectors are written as Python classes.
 
 ## Inventory Connector
 
@@ -66,7 +66,7 @@ class LocalConnector(BaseConnector):
         and then writing it to the upload location.
 
         Returns:
-            bool: indicating succes or failure.
+            bool: indicating success or failure.
         """
 
     def get_file(

en/3.x/_sources/api/index.rst.txt

@@ -1,6 +1,6 @@
 Using the API
 =============
 
-In addition to :doc:`the pyinfra CLI <../cli>`, pyinfra provides a full Python API. As of `v1` this API can be considered mostly stable. An example of how to use the API is embedded below. See also :doc:`./reference`.
+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`.
 
-.. literalinclude:: ../../examples/api_deploy.py
+`An example of how to use the API can be found here <https://github.com/pyinfra-dev/pyinfra-examples/blob/main/.old/api_deploy.py>`_. Note: this is not yet tested and pending future updates.

en/3.x/_sources/api/operations.md.txt

@@ -1,10 +1,10 @@
 # Writing Facts & Operations
 
-Operations & facts the building blocks pyinfra uses to make changes to hosts, this document describes how you can write your own to extend pyinfra's functionality.
+Operations & facts are the building blocks pyinfra uses to make changes to hosts. This document describes how you can write your own to extend pyinfra's functionality.
 
 ## Operations
 
-[Operations](../operations) are defined as Python functions. They are passed the current deploy state, the target host and any operation arguments. Operation functions read state from the host, comparing it to the arguments, and yield commands.
+[Operations](../operations) are defined as Python functions. They are passed the current deploy state, the target host, and any operation arguments. Operation functions read state from the host, compare it to the arguments, and yield commands.
 
 ### Input: arguments
 
@@ -40,7 +40,7 @@ yield StringCommand("echo", "Shell!", _sudo=True)
 Operations can also call other operations using ``yield from`` syntax:
 
 ```py
-yield from files.file(
+yield from files.file._inner(
     path="/some/file",
     ...,
 )
@@ -88,7 +88,7 @@ passed (as a ``list`` of lines) to the ``process`` handler to generate fact data
 
 Fact classes may provide a ``default`` function that takes no arguments (except ``self``). The return value of this function is used if an error
 occurs during fact collection. Additionally, a ``requires_command`` variable can be set on the fact that specifies a command that must be available
-on the host to collect the fact. If this command is not present on the host the fact will be set to the default, or empty if no ``default`` function
+on the host to collect the fact. If this command is not present on the host, the fact will be set to the default, or empty if no ``default`` function
 is available.
 
 ### Importing & Using Facts

en/3.x/_sources/api/reference.rst.txt

@@ -3,11 +3,11 @@ API Reference
 
 The pyinfra API is designed to be used as follows:
 
-1. Create the state we are going to operate on, this consists of:
+1. Create the state we are going to operate on, which consists of:
     - An inventory ``pyinfra.api.Inventory`` containing hosts ``pyinfra.api.Host``, plus any data
     - A config ``pyinfra.api.Config`` for global flag
     - A state ``pyinfra.api.State`` that combines the inventory & config
-2. Now state is setup, we define operations:
+2. Now that state is setup, we define operations:
     - ``pyinfra.api.operation.add_op``
     - ``pyinfra.api.add_deploy``
 3. Now that's done, we execute it:

en/3.x/_sources/contributing.md.txt

@@ -13,7 +13,7 @@ Third party pull requests help expand pyinfra's functionality and are essential
 
 ## Branches
 
-+ There is a branch per major version, ie `2.x`, that tracks the latest release of that version
++ There is a branch per major version, ie `3.x`, that tracks the latest release of that version
 + Changes should generally be based off the latest major branch, unless fixing an old version
 
 ## Dev Setup
@@ -30,15 +30,27 @@ cd pyinfra
 pip install -e '.[dev]'
 ```
 
-## Tests
+### Code Style & Type Checking
 
-GitHub will run all the test suites as part of any pull requests, here's how you can run them locally:
+Code style is enforced via Black, isort and flake8. 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:
 
-### Unit Tests
+```sh
+scripts/dev-lint.sh
+```
+
+### Tests
+
+GitHub will run all the test suites as part of any pull requests. There's a handy script that runs the unit tests:
+
+```sh
+scripts/dev-test.sh
+```
+
+#### Unit Tests
 
 Use `pytest` to run the unit tests, or `pytest --cov` to run with coverage. Pull requests are expected to be tested and not drop overall project coverage by >1%.
 
-### End to End Tests
+#### End to End Tests
 
 The end to end tests are also executed via `pytest` but not selected by default, options/usage:
 
@@ -64,7 +76,3 @@ To view ([localhost:8000](http://localhost:8000)):
 ```sh
 python -m http.server -d docs/build/
 ```
-
-## Code Style
-
-Code is linted using `flake8` and uses the `black` / `isort` codestyles. To check you can just run `flake8` from the root directory.

en/3.x/_sources/examples.rst.txt

@@ -1,7 +1,7 @@
 Example Deploys
 ===============
 
-If you are getting started with pyinfra checkout `the examples on Github <https://github.com/Fizzadar/pyinfra/tree/2.x/examples>`_ which should properly introduce the file/folder structure as well as operation basics.
+If you are getting started with pyinfra checkout `the examples on GitHub <https://github.com/Fizzadar/pyinfra/tree/2.x/examples>`_ which should properly introduce the file/folder structure as well as operation basics.
 
 Included here is a set of documented example deploys highlighting common patterns and best practices:
 

en/3.x/_sources/facts.rst.txt

@@ -1,7 +1,7 @@
 Facts Index
 ===========
 
-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 is populated at the beginning of the deploy.
+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:
 
@@ -23,7 +23,7 @@ Multiple facts with arguments may be called like so:
 
     pyinfra @local fact files.File path=setup.py files.File path=anotherfile.txt
 
-You can leverage facts as part of :doc:`within operations <using-operations>` like this:
+You can leverage facts within :doc:`operations <using-operations>` like this:
 
 .. code:: py
 

en/3.x/_sources/facts/deb.rst.txt

@@ -20,7 +20,7 @@ Returns the architecture string used in apt repository sources, eg ``amd64``.
 
 .. code:: python
 
-    host.get_fact(DebPackage, name)
+    host.get_fact(DebPackage, package)
 
 Returns information on a .deb archive or installed package.
 

en/3.x/_sources/facts/docker.rst.txt

@@ -1,6 +1,8 @@
 Docker Facts
 ------------
 
+See also: :doc:`../operations/docker`.
+
 .. _facts:docker.DockerContainer:
 
 :code:`docker.DockerContainer`
@@ -94,3 +96,27 @@ Returns ``docker inspect`` output for all Docker networks.
 
 Returns ``docker system info`` output in JSON format.
 
+
+.. _facts:docker.DockerVolume:
+
+:code:`docker.DockerVolume`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+    host.get_fact(DockerVolume, object_id)
+
+Returns ``docker inspect`` output for a single Docker container.
+
+
+.. _facts:docker.DockerVolumes:
+
+:code:`docker.DockerVolumes`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+    host.get_fact(DockerVolumes)
+
+Returns ``docker inspect`` output for all Docker volumes.
+

en/3.x/_sources/facts/pacman.rst.txt

@@ -28,7 +28,7 @@ Returns a dict of installed pacman packages:
 
 .. code:: python
 
-    host.get_fact(PacmanUnpackGroup, name)
+    host.get_fact(PacmanUnpackGroup, package)
 
 Returns a list of actual packages belonging to the provided package name,
 expanding groups or virtual packages.

en/3.x/_sources/facts/rpm.rst.txt

@@ -8,7 +8,7 @@ Rpm Facts
 
 .. code:: python
 
-    host.get_fact(RpmPackage, name)
+    host.get_fact(RpmPackage, package)
 
 Returns information on a .rpm file:
 
@@ -27,7 +27,7 @@ Returns information on a .rpm file:
 
 .. code:: python
 
-    host.get_fact(RpmPackageProvides, name)
+    host.get_fact(RpmPackageProvides, package)
 
 Returns a list of packages that provide the specified capability (command, file, etc).
 

en/3.x/_sources/facts/runit.rst.txt

@@ -0,0 +1,43 @@
+Runit Facts
+-----------
+
+See also: :doc:`../operations/runit`.
+
+.. _facts:runit.RunitManaged:
+
+:code:`runit.RunitManaged`
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+    host.get_fact(RunitManaged, service=None, svdir='/var/service')
+
+Returns a set of all services managed by runit
+
++ **service**: optionally check only for a single service
++ **svdir**: alternative ``SVDIR``
+
+
+.. _facts:runit.RunitStatus:
+
+:code:`runit.RunitStatus`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+    host.get_fact(RunitStatus, service=None, svdir='/var/service')
+
+Returns a dict of name -> status for runit services.
+
++ **service**: optionally check only for a single service
++ **svdir**: alternative ``SVDIR``
+
+.. code:: python
+
+    {
+        'agetty-tty1': True,     # service is running
+        'dhcpcd': False,         # service is down
+        'wpa_supplicant': None,  # service is managed, but not running or down,
+                                 # possibly in a fail state
+    }
+

en/3.x/_sources/facts/server.rst.txt

@@ -97,9 +97,9 @@ Returns a boolean indicating the remote side has GUI capabilities. Linux only.
 
 .. code:: python
 
-    host.get_fact(Home)
+    host.get_fact(Home, user='')
 
-Returns the home directory of the current user.
+Returns the home directory of the given user, or the current user if no user is given.
 
 
 .. _facts:server.Hostname:

en/3.x/_sources/getting-started.rst.txt

@@ -5,7 +5,7 @@ This guide should help describe the basics of deploying stuff with pyinfra. Star
 
 .. code:: bash
 
-    pip install pyinfra
+    pip install pyinfra --pre
 
 To do something with pyinfra you need two things:
 

en/3.x/_sources/install.md.txt

@@ -1,11 +1,11 @@
 # Installation
 
-## Pipx
+## Pip
 
 It is recommended to install pyinfra using `pip`:
 
 ```sh
-pip install pyinfra
+pip install pyinfra --pre
 ```
 
 ## Windows

en/3.x/_sources/inventory-data.rst.txt

@@ -1,9 +1,9 @@
 Inventory & Data
 ================
 
-A pyinfra inventory provides hosts, groups and data. Host are the things pyinfra will make changes to (think a SSH daemon on a server, a Docker container or the local machine). Hosts can be attached to groups, and data can then be assigned to both the groups and individual hosts.
+A pyinfra inventory provides hosts, groups and data. Hosts are the things pyinfra will make changes to (think a SSH daemon on a server, a Docker container or the local machine). Hosts can be attached to groups, and data can then be assigned to both the groups and individual hosts.
 
-By default pyinfra assumes hosts are SSH servers and the name of the host is used as the SSH hostname. Prefixing the name of the host with ``@<connector-name>/`` is used to activate alternative connectors. See: :doc:`connectors`.
+By default, pyinfra assumes hosts are SSH servers and the name of the host is used as the SSH hostname. Prefixing the name of the host with ``@<connector-name>/`` is used to activate alternative connectors. See: :doc:`connectors`.
 
 Inventory Files
 ---------------
@@ -63,7 +63,7 @@ Data can be assigned to individual hosts in the inventory by using a tuple ``(ho
         ("db-1.net", {"install_postgres": True}),
     ]
 
-This can then be used in operations files:
+This data can then be used in operations:
 
 .. code:: python
 
@@ -84,7 +84,7 @@ Group data can be stored in separate files under the ``group_data`` directory (t
     app_user = "myuser"
     app_dir = "/opt/pyinfra"
 
-These can then be used in operations:
+These variables can then be used in operations:
 
 .. code:: python
 
@@ -115,7 +115,7 @@ The same keys can be defined for host and group data - this means we can set a d
 Connecting with Data
 --------------------
 
-Data can be used to configure connectors, for example setting SSH connection details can be done like so:
+Data can be used to configure connectors. For example, setting SSH connection details can be done like so:
 
 .. code:: python
 

en/3.x/_sources/operations/apt.rst.txt

@@ -281,7 +281,7 @@ Upgrades all apt packages.
 
     # Upgrade all packages and remove unneeded transitive dependencies
     apt.upgrade(
-        name="Upgrade apt packages and remove unneeded dependencies"
+        name="Upgrade apt packages and remove unneeded dependencies",
         auto_remove=True
     )
 

en/3.x/_sources/operations/dnf.rst.txt

@@ -54,7 +54,7 @@ Install/remove/update dnf packages & updates.
         extra_install_args=None, extra_uninstall_args=None,
     )
 
-+ **packages**: list of packages to ensure
++ **packages**: packages to ensure
 + **present**: whether the packages should be installed
 + **latest**: whether to upgrade packages without a specified version
 + **update**: run ``dnf update`` before installing packages
@@ -99,7 +99,7 @@ Add/remove/update dnf repositories.
         gpgkey=None,
     )
 
-+ **name**: URL or name for the ``.repo``   file
++ **src**: URL or name for the ``.repo``   file
 + **present**: whether the ``.repo`` file should be present
 + **baseurl**: the baseurl of the repo (if ``name`` is not a URL)
 + **description**: optional verbose description