Skip to content

Commit

Permalink
Docs build 2024-09-25
Browse files Browse the repository at this point in the history
  • Loading branch information
github-actions committed Sep 25, 2024
1 parent 13ef91d commit 32e9ad2
Show file tree
Hide file tree
Showing 155 changed files with 649 additions and 59 deletions.
2 changes: 1 addition & 1 deletion en/3.x/.buildinfo
Original file line number Diff line number Diff line change
@@ -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: 553769cb09bd26734a1d1f0b73b811bb
config: d07f8dc595accdbcd20e4d63574213b7
tags: 645f666f9bcd5a90fca523b33c5a78b7
11 changes: 11 additions & 0 deletions en/3.x/_sources/api/connectors.md.txt
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,14 @@ class LocalConnector(BaseConnector):
bool: indicating success or failure.
"""
```

## 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`:

```toml
[project.entry-points.'pyinfra.connectors']
# Key = Entry point name
# Value = module_path:class_name
custom = 'pyinfra_custom_connector.connector:LoggingConnector'
```
2 changes: 1 addition & 1 deletion en/3.x/_sources/api/deploys.md.txt
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ install_mariadb()

## Global Arguments

Deploys accept the same [global arguments as as operations](../deploys.html#global-arguments) and they apply to every operation call within that deploy. Taking the above example:
Deploys accept the same [global arguments as operations](../arguments) and they apply to every operation call within that deploy. Taking the above example:


```py
Expand Down
62 changes: 61 additions & 1 deletion en/3.x/_sources/api/index.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,64 @@ 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`.

`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.
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>`_.

Full Example
============

`A full 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 is pending future updates)

Basic Localhost Example
=======================

.. code:: python
from pyinfra.api import Config, Inventory, State
from pyinfra.api.connect import connect_all
from pyinfra.api.operation import add_op
from pyinfra.api.operations import run_ops
from pyinfra.api.facts import get_facts
from pyinfra.facts.server import Os
from pyinfra.operations import server
# Define your inventory (@local means execute on localhost using subprocess)
# https://docs.pyinfra.com/en/3.x/apidoc/pyinfra.api.inventory.html
inventory = Inventory((["@local"], {}))
# Define any config you need
# https://docs.pyinfra.com/en/3.x/apidoc/pyinfra.api.config.html
config = Config(SUDO=True)
# Set up the state object
# https://docs.pyinfra.com/en/3.x/apidoc/pyinfra.api.state.html
state = State(inventory=inventory, config=config)
# Connect to all the hosts
connect_all(state)
# Start adding operations
result1 = add_op(
state,
server.user,
user="pyinfra",
home="/home/pyinfra",
shell="/bin/bash",
)
result2 = add_op(
state,
server.shell,
name="Run some shell commands",
commands=["whoami", "echo $PATH", "bash --version"]
)
# And finally we run the ops
run_ops(state)
# add_op returns an OperationMeta for each op, letting you access stdout, stderr, etc. after they run
host = state.hosts.inventory['@local']
print(result1.changed, result1[host].stdout, result1[host].stderr)
print(result2.changed, result2[host].stdout, result2[host].stderr)
# We can also get facts for all the hosts
# https://docs.pyinfra.com/en/3.x/apidoc/pyinfra.api.facts.html
print(get_facts(state, Os))
2 changes: 1 addition & 1 deletion en/3.x/_sources/cli.md.txt
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ By default pyinfra only prints high level information (this host connected, this

## Inventory

When using pyinfra inventory can be provided directly via the command line or [defined in a file](./deploys.html#inventory). Both support the full range of [connectors](./connectors) and multiple hosts. Some CLI examples:
When using pyinfra inventory can be provided directly via the command line or [defined in a file](./inventory-data). Both support the full range of [connectors](./connectors) and multiple hosts. Some CLI examples:

```sh
# Load inventory hosts from a file
Expand Down
28 changes: 26 additions & 2 deletions en/3.x/_sources/compatibility.md.txt
Original file line number Diff line number Diff line change
Expand Up @@ -39,12 +39,36 @@ pyinfra aims to be compatible with all Unix-like operating systems and is curren
* HardenedBSD 11
* DragonflyBSD 5
+ OpenSUSE (leap15 + tumbleweed)
+ macOS 10.15 (with [`@local` connector](connectors.html#local))
+ Docker (with [`@docker` connector](connectors.html#docker))
+ macOS 10.15 (with [`@local` connector](./connectors/local))
+ Docker (with [`@docker` connector](./connectors/docker))

In general, the only requirement on the remote side is shell access. POSIX commands are used where possible for facts and operations, so most of the ``server`` and ``files`` operations should work anywhere POSIX.


## Upgrading pyinfra from ``2.x`` -> ``3.x``

- Rename `_use_sudo_password` argument to `_sudo_password`
- Deploy decorator must be called:

```py
# Old, 2.x decorator
@deploy
def mydeploy():
...

# New, 3.x decorator
@deploy()
def mydeploy():
...
```

- Remove `@winrm` connector, will come back as [`pyinfra-windows`](https://github.com/pyinfra-dev/pyinfra-windows)

## Upgrading pyinfra from ``1.x`` -> ``2.x``

- Python 2.7 (finally!), 3.5 support dropped, Python 3.6 is now the minimum required version
- The "deploy directory" concept has been removed - everything now executes from the current working directory which removes the ambiguous magic v1 used to pick a deploy directory. A new --chdir CLI flag has been added to set the working directory before pyinfra executes

## Upgrading pyinfra from ``0.x`` -> ``1.x``

The move to `v1` removes a lot of old legacy functionality in pyinfra - there will be warnings written to the user in CLI mode if any of these are encountered. The full list can be seen [on the changelog](https://github.com/Fizzadar/pyinfra/blob/master/CHANGELOG.md#v1). In addition to these removals, `v1` brings a few major changes and deprecates the old methods. Again, pyinfra will output warnings when these are encountered, and support will be removed in `v2`.
Expand Down
1 change: 1 addition & 0 deletions en/3.x/_sources/connectors/ssh.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ Multiple hosts with different SSH usernames:
("my-host-1.net", {"ssh_user": "ssh-user"}),
("my-host-2.net", {"ssh_user": "other-user"}),
]
Available Data
~~~~~~~~~~~~~~

Expand Down
2 changes: 1 addition & 1 deletion en/3.x/_sources/contributing.md.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Third party pull requests help expand pyinfra's functionality and are essential
## Guides

+ [How to write operations](api/operations)
+ [How to write facts](api/facts)
+ [How to write facts](api/operations.md#facts)
+ [How to write connectors](api/connectors)
+ [API reference](api/reference)

Expand Down
1 change: 1 addition & 0 deletions en/3.x/_sources/facts/hardware.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ Gets & returns a dict of network devices. See the ``ipv4_addresses`` and
``ipv6_addresses`` facts for easier-to-use shortcuts to get device addresses.

.. code:: python
"enp1s0": {
"ether": "12:34:56:78:9A:BC",
"mtu": 1500,
Expand Down
4 changes: 3 additions & 1 deletion en/3.x/_sources/facts/selinux.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ or ``None`` if the file does not exist.
host.get_fact(FileContextMapping, target)
Returns structured SELinux file context data for the specified target path prefix
using the same format as :ref:`selinux.FileContext`. If there is no mapping, it returns ``{}``
using the same format as :ref:`facts:selinux.FileContext`.
If there is no mapping, it returns ``{}``
Note: This fact requires root privileges.


Expand Down Expand Up @@ -79,6 +80,7 @@ Returns the SELinux 'type' definitions for ``(tcp|udp|dccp|sctp)`` ports.
Note: This fact requires root privileges.

.. code:: python
{
"tcp": { 22: "ssh_port_t", ...},
"udp": { ...}
Expand Down
5 changes: 5 additions & 0 deletions en/3.x/_sources/install.md.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
# Ignore warning about this page not being included in any toctree
orphan: true
---

# Installation

## Pip
Expand Down
3 changes: 2 additions & 1 deletion en/3.x/_sources/operations/apt.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,8 @@ keyserver/id:
.. warning::
``apt-key`` is deprecated in Debian, it is recommended NOT to use this
operation and instead follow the instructions here:
https://wiki.debian.org/DebianRepository/UseThirdParty

https://wiki.debian.org/DebianRepository/UseThirdParty

**Examples:**

Expand Down
4 changes: 2 additions & 2 deletions en/3.x/_sources/operations/files.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -335,7 +335,7 @@ Regex line matching:
change bits of lines, see ``files.replace``.

Regex line escaping:
If matching special characters (eg a crontab line containing *), remember to escape
If matching special characters (eg a crontab line containing ``*``), remember to escape
it first using Python's ``re.escape``.

Backup:
Expand Down Expand Up @@ -591,7 +591,7 @@ remove extra files on the remote side, but not extra directories.
+ **mode**: permissions of the files
+ **dir_mode**: permissions of the directories
+ **delete**: delete remote files not present locally
+ **exclude**: string or list/tuple of strings to match & exclude files (eg *.pyc)
+ **exclude**: string or list/tuple of strings to match & exclude files (eg ``*.pyc``)
+ **exclude_dir**: string or list/tuple of strings to match & exclude directories (eg node_modules)
+ **add_deploy_dir**: interpret src as relative to deploy directory instead of current directory

Expand Down
19 changes: 18 additions & 1 deletion en/3.x/_sources/operations/git.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ Manage git worktrees.
+ **from_remote_branch**: a 2-tuple ``(remote, branch)`` that identifies a remote branch
+ **present**: whether the working tree should exist
+ **assume_repo_exists**: whether to assume the main repo exists
+ **force**: remove unclean working tree if should not exist
+ **force**: whether to use ``--force`` when adding/removing worktrees
+ **user**: chown files to this user after
+ **group**: chown files to this group after

Expand All @@ -143,6 +143,14 @@ Manage git worktrees.
commitish="4e091aa0"
)
git.worktree(
name="Create a worktree from the tag `4e091aa0`, even if already registered",
repo="/usr/local/src/pyinfra/master",
worktree="/usr/local/src/pyinfra/2.x",
commitish="2.x",
force=True
)
git.worktree(
name="Create a worktree with a new local branch `v1.0`",
repo="/usr/local/src/pyinfra/master",
Expand Down Expand Up @@ -188,6 +196,15 @@ Manage git worktrees.
commitish="v1.0"
)
git.worktree(
name="Idempotent worktree creation, never pulls",
repo="/usr/local/src/pyinfra/master",
worktree="/usr/local/src/pyinfra/hotfix",
new_branch="v1.0",
commitish="v1.0",
pull=False
)
git.worktree(
name="Pull an existing worktree already linked to a tracking branch",
repo="/usr/local/src/pyinfra/master",
Expand Down
30 changes: 15 additions & 15 deletions en/3.x/_sources/operations/zfs.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -25,20 +25,20 @@ volume, snapshot).
+ **sparse**: for volumes, whether to create a sparse volume with no allocation
+ **volume_size**: the size of the volume
+ **properties**: the ZFS properties that should be set on the dataset.
+ **extra_props: additional props; merged with `properties` for convenience
+ ****extra_props**: additional props; merged with `properties` for convenience

**Examples:**

.. code:: python
zfs.dataset(
"tank/srv",
mountpoint="/srv",
compression="lz4",
properties={"com.sun:auto_snapshot": "true"}
)
zfs.dataset("tank/vm-disks/db_srv_04", volume_size="32G") # creates a volume
zfs.dataset("tank/home@old_version", present=False)
zfs.dataset(
"tank/srv",
mountpoint="/srv",
compression="lz4",
properties={"com.sun:auto_snapshot": "true"}
)
zfs.dataset("tank/vm-disks/db_srv_04", volume_size="32G") # creates a volume
zfs.dataset("tank/home@old_version", present=False)
.. _operations:zfs.filesystem:
Expand All @@ -56,13 +56,13 @@ Create or destroy a ZFS filesystem, or modify its properties.
+ **present**: whether the named volume should exist
+ **recursive**: whether to create parent datasets or destroy child datasets
+ **properties**: the ZFS properties that should be set on the snapshot.
+ **extra_props: additional props; merged with `properties` for convenience
+ ****extra_props**: additional props; merged with `properties` for convenience

**Examples:**

.. code:: python
zfs.filesystem("tank/vm-disks/db_srv_04", "32G")
zfs.filesystem("tank/vm-disks/db_srv_04", "32G")
.. _operations:zfs.snapshot:
Expand All @@ -80,13 +80,13 @@ Create or destroy a ZFS snapshot, or modify its properties.
+ **present**: whether the named filesystem should exist
+ **recursive**: whether to snapshot child datasets
+ **properties**: the ZFS properties that should be set on the snapshot.
+ **extra_props: additional props; merged with `properties` for convenience
+ ****extra_props**: additional props; merged with `properties` for convenience

**Examples:**

.. code:: python
zfs.snapshot("tank/home@weekly_backup")
zfs.snapshot("tank/home@weekly_backup")
.. _operations:zfs.volume:
Expand All @@ -106,11 +106,11 @@ Create or destroy a ZFS volume, or modify its properties.
+ **present**: whether the named volume should exist
+ **recursive**: whether to create parent datasets or destroy child datasets
+ **properties**: the ZFS properties that should be set on the snapshot.
+ **extra_props: additional props; merged with `properties` for convenience
+ ****extra_props**: additional props; merged with `properties` for convenience

**Examples:**

.. code:: python
zfs.volume("tank/vm-disks/db_srv_04", "32G")
zfs.volume("tank/vm-disks/db_srv_04", "32G")
6 changes: 3 additions & 3 deletions en/3.x/_sources/support.md.txt
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,16 @@ Need a hand with using pyinfra or have some questions? You can find official pyi
+ Chat in [the `pyinfra` Matrix room](https://matrix.to/#/#pyinfra:matrix.org)
+ Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/pyinfra) (be sure to use the `pyinfra` tag!)

### I think I've got a bug!
## I think I've got a bug!

+ Please have a quick scan of the [the compatibility page](./compatibility) to see if the issue is referenced there
+ Check [the issue list](https://github.com/Fizzadar/pyinfra/issues) to see if anyone else has this issue
+ Submit [a new bug report](https://github.com/Fizzadar/pyinfra/issues/new/choose)

### I have an idea!
## I have an idea!

Please consider [submitting a feature request](https://github.com/Fizzadar/pyinfra/issues/new/choose).

### I'd like to contribute!
## I'd like to contribute!

Fantastic! Please see [the contributing docs](./contributing).
13 changes: 13 additions & 0 deletions en/3.x/api/connectors.html
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,13 @@ <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="#pyproject-toml">pyproject.toml</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="operations.html">Writing Facts &amp; Operations</a></li>
<li class="toctree-l1"><a class="reference internal" href="index.html">Using the API</a></li>
<li class="toctree-l1"><a class="reference internal" href="index.html#full-example">Full Example</a></li>
<li class="toctree-l1"><a class="reference internal" href="index.html#basic-localhost-example">Basic Localhost Example</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Meta</span></p>
<ul>
Expand Down Expand Up @@ -217,6 +220,16 @@ <h2>Executing Connector<a class="headerlink" href="#executing-connector" title="
</pre></div>
</div>
</div>
<div class="section" id="pyproject-toml">
<h2>pyproject.toml<a class="headerlink" href="#pyproject-toml" title="Permalink 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>
<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[project.entry-points.</span><span class="s1">&#39;pyinfra.connectors&#39;</span><span class="k">]</span>
<span class="c1"># Key = Entry point name</span>
<span class="c1"># Value = module_path:class_name</span>
<span class="n">custom</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;pyinfra_custom_connector.connector:LoggingConnector&#39;</span>
</pre></div>
</div>
</div>
</div>


Expand Down
Loading

0 comments on commit 32e9ad2

Please sign in to comment.