pyinfra 3.4__py2.py3-none-any.whl → 3.5__py2.py3-none-any.whl

pyinfra/connectors/ssh.py

@@ -5,7 +5,7 @@ from random import uniform
 from shutil import which
 from socket import error as socket_error, gaierror
 from time import sleep
-from typing import TYPE_CHECKING, Any, Iterable, Optional, Tuple
+from typing import IO, TYPE_CHECKING, Any, Iterable, Optional, Protocol, Tuple
 
 import click
 from paramiko import AuthenticationException, BadHostKeyException, SFTPClient, SSHException
@@ -17,6 +17,7 @@ from pyinfra.api.exceptions import ConnectError
 from pyinfra.api.util import get_file_io, memoize
 
 from .base import BaseConnector, DataMeta
+from .scp import SCPClient
 from .ssh_util import get_private_key, raise_connect_error
 from .sshuserclient import SSHClient
 from .util import (
@@ -53,6 +54,7 @@ class ConnectorData(TypedDict):
     ssh_connect_retries: int
     ssh_connect_retry_min_delay: float
     ssh_connect_retry_max_delay: float
+    ssh_file_transfer_protocol: str
 
 
 connector_data_meta: dict[str, DataMeta] = {
@@ -92,9 +94,27 @@ connector_data_meta: dict[str, DataMeta] = {
         "Upper bound for random delay between retries",
         0.5,
     ),
+    "ssh_file_transfer_protocol": DataMeta(
+        "Protocol to use for file transfers. Can be ``sftp`` or ``scp``.",
+        "sftp",
+    ),
 }
 
 
+class FileTransferClient(Protocol):
+    def getfo(self, remote_filename: str, fl: IO) -> Any | None:
+        """
+        Get a file from the remote host, writing to the provided file-like object.
+        """
+        ...
+
+    def putfo(self, fl: IO, remote_filename: str) -> Any | None:
+        """
+        Put a file to the remote host, reading from the provided file-like object.
+        """
+        ...
+
+
 class SSHConnector(BaseConnector):
     """
     Connect to hosts over SSH. This is the default connector and all targets default
@@ -268,7 +288,7 @@ class SSHConnector(BaseConnector):
 
     @override
     def disconnect(self) -> None:
-        self.get_sftp_connection.cache.clear()
+        self.get_file_transfer_connection.cache.clear()
 
     @override
     def run_shell_command(
@@ -353,13 +373,25 @@ class SSHConnector(BaseConnector):
         return status, combined_output
 
     @memoize
-    def get_sftp_connection(self):
+    def get_file_transfer_connection(self) -> FileTransferClient | None:
         assert self.client is not None
         transport = self.client.get_transport()
         assert transport is not None, "No transport"
         try:
-            return SFTPClient.from_transport(transport)
+            if self.data["ssh_file_transfer_protocol"] == "sftp":
+                logger.debug("Using SFTP for file transfer")
+                return SFTPClient.from_transport(transport)
+            elif self.data["ssh_file_transfer_protocol"] == "scp":
+                logger.debug("Using SCP for file transfer")
+                return SCPClient(transport)
+            else:
+                raise ConnectError(
+                    "Unsupported file transfer protocol: {0}".format(
+                        self.data["ssh_file_transfer_protocol"],
+                    ),
+                )
         except SSHException as e:
+
             raise ConnectError(
                 (
                     "Unable to establish SFTP connection. Check that the SFTP subsystem "
@@ -367,9 +399,9 @@ class SSHConnector(BaseConnector):
                 ).format(self.host),
             ) from e
 
-    def _get_file(self, remote_filename: str, filename_or_io):
+    def _get_file(self, remote_filename: str, filename_or_io: str | IO):
         with get_file_io(filename_or_io, "wb") as file_io:
-            sftp = self.get_sftp_connection()
+            sftp = self.get_file_transfer_connection()
             sftp.getfo(remote_filename, file_io)
 
     @override
@@ -448,7 +480,7 @@ class SSHConnector(BaseConnector):
         while attempts < 3:
             try:
                 with get_file_io(filename_or_io) as file_io:
-                    sftp = self.get_sftp_connection()
+                    sftp = self.get_file_transfer_connection()
                     sftp.putfo(file_io, remote_location)
                 return
             except OSError as e:

pyinfra/connectors/util.py

@@ -314,6 +314,10 @@ def make_unix_command(
     # Doas config
     _doas=False,
     _doas_user=None,
+    # Retry config (ignored in command generation but passed through)
+    _retries=0,
+    _retry_delay=0,
+    _retry_until=None,
 ) -> StringCommand:
     """
     Builds a shell command with various kwargs.

pyinfra/facts/dnf.py

@@ -16,11 +16,15 @@ class DnfRepositories(FactBase):
 
         [
             {
-                "name": "CentOS-$releasever - Apps",
-                "baseurl": "http://mirror.centos.org/$contentdir/$releasever/Apps/$basearch/os/",
-                "gpgcheck": "1",
+                "repoid": "baseos",
+                "name": "AlmaLinux $releasever - BaseOS",
+                "mirrorlist": "https://mirrors.almalinux.org/mirrorlist/$releasever/baseos",
                 "enabled": "1",
-                "gpgkey": "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial",
+                "gpgcheck": "1",
+                "countme": "1",
+                "gpgkey": "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-AlmaLinux-9",
+                "metadata_expire": "86400",
+                "enabled_metadata": "1"
             },
         ]
     """

pyinfra/facts/docker.py

@@ -76,6 +76,28 @@ class DockerNetworks(DockerFactBase):
         return "docker network inspect `docker network ls -q`"
 
 
+class DockerVolumes(DockerFactBase):
+    """
+    Returns ``docker inspect`` output for all Docker volumes.
+    """
+
+    @override
+    def command(self) -> str:
+        return "docker volume inspect `docker volume ls -q`"
+
+
+class DockerPlugins(DockerFactBase):
+    """
+    Returns ``docker plugin inspect`` output for all Docker plugins.
+    """
+
+    @override
+    def command(self) -> str:
+        return """
+        ids=$(docker plugin ls -q) && [ -n "$ids" ] && docker plugin inspect $ids || echo "[]"
+        """.strip()
+
+
 # Single Docker objects
 #
 
@@ -113,19 +135,17 @@ class DockerNetwork(DockerSingleMixin):
     docker_type = "network"
 
 
-class DockerVolumes(DockerFactBase):
+class DockerVolume(DockerSingleMixin):
     """
-    Returns ``docker inspect`` output for all Docker volumes.
+    Returns ``docker inspect`` output for a single Docker container.
     """
 
-    @override
-    def command(self) -> str:
-        return "docker volume inspect `docker volume ls -q`"
+    docker_type = "volume"
 
 
-class DockerVolume(DockerSingleMixin):
+class DockerPlugin(DockerSingleMixin):
     """
-    Returns ``docker inspect`` output for a single Docker container.
+    Returns ``docker plugin inspect`` output for a single Docker plugin.
     """
 
-    docker_type = "volume"
+    docker_type = "plugin"

pyinfra/facts/files.py

@@ -24,13 +24,21 @@ from pyinfra.facts.util.units import parse_size
 
 LINUX_STAT_COMMAND = "stat -c 'user=%U group=%G mode=%A atime=%X mtime=%Y ctime=%Z size=%s %N'"
 BSD_STAT_COMMAND = "stat -f 'user=%Su group=%Sg mode=%Sp atime=%a mtime=%m ctime=%c size=%z %N%SY'"
+LS_COMMAND = "ls -ld"
 
 STAT_REGEX = (
     r"user=(.*) group=(.*) mode=(.*) "
-    r"atime=([0-9]*) mtime=([0-9]*) ctime=([0-9]*) "
+    r"atime=(-?[0-9]*) mtime=(-?[0-9]*) ctime=(-?[0-9]*) "
     r"size=([0-9]*) (.*)"
 )
 
+# ls -ld output: permissions links user group size month day year/time path
+# Supports attribute markers: . (SELinux), @ (extended attrs), + (ACL)
+# Handles both "MMM DD" and "DD MMM" date formats
+LS_REGEX = (
+    r"^([dlbcsp-][-rwxstST]{9}[.@+]?)\s+\d+\s+(\S+)\s+(\S+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(.+)$"
+)
+
 FLAG_TO_TYPE = {
     "b": "block",
     "c": "character",
@@ -82,6 +90,108 @@ def _parse_datetime(value: str) -> Optional[datetime]:
     return None
 
 
+def _parse_ls_timestamp(month: str, day: str, year_or_time: str) -> Optional[datetime]:
+    """
+    Parse ls timestamp format.
+    Examples: "Jan  1  1970", "Apr  2  2025", "Dec 31 12:34"
+    """
+    try:
+        # Month abbreviation to number mapping
+        month_map = {
+            "Jan": 1,
+            "Feb": 2,
+            "Mar": 3,
+            "Apr": 4,
+            "May": 5,
+            "Jun": 6,
+            "Jul": 7,
+            "Aug": 8,
+            "Sep": 9,
+            "Oct": 10,
+            "Nov": 11,
+            "Dec": 12,
+        }
+
+        month_num = month_map.get(month)
+        if month_num is None:
+            return None
+
+        day_num = int(day)
+
+        # Check if year_or_time is a year (4 digits) or time (HH:MM)
+        if ":" in year_or_time:
+            # It's a time, assume current year
+            import time
+
+            current_year = time.gmtime().tm_year
+            hour, minute = map(int, year_or_time.split(":"))
+            return datetime(current_year, month_num, day_num, hour, minute)
+        else:
+            # It's a year
+            year_num = int(year_or_time)
+            return datetime(year_num, month_num, day_num)
+
+    except (ValueError, TypeError):
+        return None
+
+
+def _parse_ls_output(output: str) -> Optional[tuple[FileDict, str]]:
+    """
+    Parse ls -ld output and extract file information.
+    Example: drwxr-xr-x    1 root     root           416 Jan  1  1970 /
+    """
+    match = re.match(LS_REGEX, output.strip())
+    if not match:
+        return None
+
+    permissions = match.group(1)
+    user = match.group(2)
+    group = match.group(3)
+    size = match.group(4)
+    date_part1 = match.group(5)
+    date_part2 = match.group(6)
+    year_or_time = match.group(7)
+    path = match.group(8)
+
+    # Determine if it's "MMM DD" or "DD MMM" format
+    if date_part1.isdigit():
+        # "DD MMM" format (e.g., "22 Jun")
+        day = date_part1
+        month = date_part2
+    else:
+        # "MMM DD" format (e.g., "Jun 22")
+        month = date_part1
+        day = date_part2
+
+    # Extract file type from first character of permissions
+    path_type = FLAG_TO_TYPE[permissions[0]]
+
+    # Parse mode (skip first character which is file type, and any trailing attribute markers)
+    # Remove trailing attribute markers (.@+) if present
+    mode_str = permissions[1:10]  # Take exactly 9 characters after file type
+    mode = _parse_mode(mode_str)
+
+    # Parse timestamp - ls shows modification time
+    mtime = _parse_ls_timestamp(month, day, year_or_time)
+
+    data: FileDict = {
+        "user": user,
+        "group": group,
+        "mode": mode,
+        "atime": None,  # ls doesn't provide atime
+        "mtime": mtime,
+        "ctime": None,  # ls doesn't provide ctime
+        "size": try_int(size),
+    }
+
+    # Handle symbolic links
+    if path_type == "link" and " -> " in path:
+        filename, target = path.split(" -> ", 1)
+        data["link_target"] = target.strip("'").lstrip("`")
+
+    return data, path_type
+
+
 class FileDict(TypedDict):
     mode: int
     size: Union[int, str]
@@ -127,41 +237,54 @@ class File(FactBase[Union[FileDict, Literal[False], None]]):
             (
                 # only stat if the path exists (file or symlink)
                 "! (test -e {0} || test -L {0} ) || "
-                "( {linux_stat_command} {0} 2> /dev/null || {bsd_stat_command} {0} )"
+                "( {linux_stat_command} {0} 2> /dev/null || "
+                "{bsd_stat_command} {0} || {ls_command} {0} )"
             ),
             path,
             linux_stat_command=LINUX_STAT_COMMAND,
             bsd_stat_command=BSD_STAT_COMMAND,
+            ls_command=LS_COMMAND,
         )
 
     @override
     def process(self, output) -> Union[FileDict, Literal[False], None]:
+        # Try to parse as stat output first
         match = re.match(STAT_REGEX, output[0])
-        if not match:
-            return None
+        if match:
+            mode = match.group(3)
+            path_type = FLAG_TO_TYPE[mode[0]]
 
-        mode = match.group(3)
-        path_type = FLAG_TO_TYPE[mode[0]]
-
-        data: FileDict = {
-            "user": match.group(1),
-            "group": match.group(2),
-            "mode": _parse_mode(mode[1:]),
-            "atime": _parse_datetime(match.group(4)),
-            "mtime": _parse_datetime(match.group(5)),
-            "ctime": _parse_datetime(match.group(6)),
-            "size": try_int(match.group(7)),
-        }
+            data: FileDict = {
+                "user": match.group(1),
+                "group": match.group(2),
+                "mode": _parse_mode(mode[1:]),
+                "atime": _parse_datetime(match.group(4)),
+                "mtime": _parse_datetime(match.group(5)),
+                "ctime": _parse_datetime(match.group(6)),
+                "size": try_int(match.group(7)),
+            }
+
+            if path_type != self.type:
+                return False
+
+            if path_type == "link":
+                filename = match.group(8)
+                filename, target = filename.split(" -> ")
+                data["link_target"] = target.strip("'").lstrip("`")
+
+            return data
 
-        if path_type != self.type:
-            return False
+        # Try to parse as ls output
+        ls_result = _parse_ls_output(output[0])
+        if ls_result is not None:
+            data, path_type = ls_result
 
-        if path_type == "link":
-            filename = match.group(8)
-            filename, target = filename.split(" -> ")
-            data["link_target"] = target.strip("'").lstrip("`")
+            if path_type != self.type:
+                return False
 
-        return data
+            return data
+
+        return None
 
 
 class Link(File):
@@ -520,10 +643,13 @@ class Block(FactBase):
             QuoteString(f"{EXISTS}{path}"),
             QuoteString(f"{MISSING}{path}"),
         )
-        # m_f_s_c inserts blanks in unfortunate places, e.g. after first slash
-        cmd = make_formatted_string_command(
-            f"awk \\'/{end}/{{{{f=0}}}} f; /{start}/{{{{f=1}}}}\\' {{0}} || {backstop}",
+
+        cmd = StringCommand(
+            f"awk '/{end}/{{ f=0}} f; /{start}/{{ f=1}} ' ",
             QuoteString(path),
+            " || ",
+            backstop,
+            _separator="",
         )
         return cmd
 
@@ -534,3 +660,18 @@ class Block(FactBase):
         if output and (output[0] == f"{MISSING}{self.path}"):
             return None
         return output
+
+
+class FileContents(FactBase):
+    """
+    Returns the contents of a file as a list of lines. Works with both sha1sum and sha1. Returns
+    ``None`` if the file doest not exist.
+    """
+
+    @override
+    def command(self, path):
+        return make_formatted_string_command("cat {0}", QuoteString(path))
+
+    @override
+    def process(self, output):
+        return output

pyinfra/facts/server.py

@@ -6,7 +6,7 @@ import re
 import shutil
 from datetime import datetime
 from tempfile import mkdtemp
-from typing import Dict, Iterable, List, Optional, Tuple
+from typing import Dict, Iterable, List, Optional, Tuple, Union
 
 from dateutil.parser import parse as parse_date
 from distro import distro
@@ -280,7 +280,7 @@ class Mounts(FactBase[Dict[str, MountsDict]]):
         return devices
 
 
-class Port(FactBase[Tuple[str, int] | Tuple[None, None]]):
+class Port(FactBase[Union[Tuple[str, int], Tuple[None, None]]]):
     """
     Returns the process occuping a port and its PID
     """
@@ -290,7 +290,7 @@ class Port(FactBase[Tuple[str, int] | Tuple[None, None]]):
         return f"ss -lptnH 'src :{port}'"
 
     @override
-    def process(self, output: Iterable[str]) -> Tuple[str, int] | Tuple[None, None]:
+    def process(self, output: Iterable[str]) -> Union[Tuple[str, int], Tuple[None, None]]:
         for line in output:
             proc, pid = line.split('"')[1], int(line.split("pid=")[1].split(",")[0])
             return (proc, pid)
@@ -661,7 +661,9 @@ class LinuxDistribution(FactBase[LinuxDistributionDict]):
 
             for filename, content in parts.items():
                 with open(
-                    os.path.join(temp_etc_dir, os.path.basename(filename)), "w", encoding="utf-8"
+                    os.path.join(temp_etc_dir, os.path.basename(filename)),
+                    "w",
+                    encoding="utf-8",
                 ) as fp:
                     fp.write(content)
 
@@ -901,3 +903,52 @@ class SecurityLimits(FactBase):
             )
 
         return limits
+
+
+class RebootRequired(FactBase[bool]):
+    """
+    Returns a boolean indicating whether the system requires a reboot.
+
+    On Linux systems:
+    - Checks /var/run/reboot-required and /var/run/reboot-required.pkgs
+    - On Alpine Linux, compares installed kernel with running kernel
+
+    On FreeBSD systems:
+    - Compares running kernel version with installed kernel version
+    """
+
+    @override
+    def command(self) -> str:
+        return """
+# Get OS type
+OS_TYPE=$(uname -s)
+if [ "$OS_TYPE" = "Linux" ]; then
+    # Check if it's Alpine Linux
+    if [ -f /etc/alpine-release ]; then
+        RUNNING_KERNEL=$(uname -r)
+        INSTALLED_KERNEL=$(ls -1 /lib/modules | sort -V | tail -n1)
+        if [ "$RUNNING_KERNEL" != "$INSTALLED_KERNEL" ]; then
+            echo "reboot_required"
+            exit 0
+        fi
+    else
+        # Check standard Linux reboot required files
+        if [ -f /var/run/reboot-required ] || [ -f /var/run/reboot-required.pkgs ]; then
+            echo "reboot_required"
+            exit 0
+        fi
+    fi
+elif [ "$OS_TYPE" = "FreeBSD" ]; then
+    RUNNING_VERSION=$(freebsd-version -r)
+    INSTALLED_VERSION=$(freebsd-version -k)
+    if [ "$RUNNING_VERSION" != "$INSTALLED_VERSION" ]; then
+        echo "reboot_required"
+        exit 0
+    fi
+fi
+echo "no_reboot_required"
+"""
+
+    @override
+    def process(self, output) -> bool:
+        return list(output)[0].strip() == "reboot_required"

pyinfra/facts/util/packaging.py

@@ -32,6 +32,7 @@ def _parse_yum_or_zypper_repositories(output):
                 repos.append(current_repo)
                 current_repo = {}
 
+            current_repo["repoid"] = line[1:-1]
             current_repo["name"] = line[1:-1]
 
         if current_repo and "=" in line:

pyinfra/facts/yum.py

@@ -16,11 +16,15 @@ class YumRepositories(FactBase):
 
         [
             {
-                "name": "CentOS-$releasever - Apps",
-                "baseurl": "http://mirror.centos.org/$contentdir/$releasever/Apps/$basearch/os/",
-                "gpgcheck": "1",
+                "repoid": "baseos",
+                "name": "AlmaLinux $releasever - BaseOS",
+                "mirrorlist": "https://mirrors.almalinux.org/mirrorlist/$releasever/baseos",
                 "enabled": "1",
-                "gpgkey": "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial",
+                "gpgcheck": "1",
+                "countme": "1",
+                "gpgkey": "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-AlmaLinux-9",
+                "metadata_expire": "86400",
+                "enabled_metadata": "1"
             },
         ]
     """

pyinfra/facts/zypper.py

@@ -16,11 +16,11 @@ class ZypperRepositories(FactBase):
 
         [
             {
+                "repoid": "repo-oss",
                 "name": "Main Repository",
                 "enabled": "1",
-                "autorefresh": "0",
-                "baseurl": "http://download.opensuse.org/distribution/leap/$releasever/repo/oss/",
-                "type": "rpm-md",
+                "autorefresh": "1",
+                "baseurl": "http://download.opensuse.org/distribution/leap/$releasever/repo/oss/"
             },
         ]
     """

pyinfra/operations/crontab.py

@@ -157,7 +157,7 @@ def crontab(
             ),
         ):
             if not exists_name and cron_name:
-                new_crontab_line = f"{name_comment}\n{new_crontab_line}"
+                new_crontab_line = f"{name_comment}\\n{new_crontab_line}"
             edit_commands.append(
                 sed_replace(
                     temp_filename,