pyinfra 3.1.1__py2.py3-none-any.whl → 3.3__py2.py3-none-any.whl

pyinfra/facts/crontab.py

@@ -0,0 +1,195 @@
+import re
+from typing import Dict, List, Optional, TypedDict, Union
+
+from typing_extensions import NotRequired, override
+
+from pyinfra.api import FactBase
+from pyinfra.api.util import try_int
+
+
+class CrontabDict(TypedDict):
+    command: NotRequired[str]
+    # handles cases like CRON_TZ=UTC
+    env: NotRequired[str]
+    minute: NotRequired[Union[int, str]]
+    hour: NotRequired[Union[int, str]]
+    month: NotRequired[Union[int, str]]
+    day_of_month: NotRequired[Union[int, str]]
+    day_of_week: NotRequired[Union[int, str]]
+    comments: NotRequired[List[str]]
+    special_time: NotRequired[str]
+
+
+# for compatibility, also keeps a dict of command -> crontab dict
+class CrontabFile:
+    commands: List[CrontabDict]
+
+    def __init__(self, input_dict: Optional[Dict[str, CrontabDict]] = None):
+        super().__init__()
+        self.commands = []
+        if input_dict:
+            for command, others in input_dict.items():
+                val = others.copy()
+                val["command"] = command
+                self.add_item(val)
+
+    def add_item(self, item: CrontabDict):
+        self.commands.append(item)
+
+    def __len__(self):
+        return len(self.commands)
+
+    def __bool__(self):
+        return len(self) > 0
+
+    def items(self):
+        return {item.get("command") or item.get("env"): item for item in self.commands}
+
+    def get_command(
+        self, command: Optional[str] = None, name: Optional[str] = None
+    ) -> Optional[CrontabDict]:
+        assert command or name, "Either command or name must be provided"
+
+        name_comment = "# pyinfra-name={0}".format(name)
+        for cmd in self.commands:
+            if cmd.get("command") == command:
+                return cmd
+            if cmd.get("comments") and name_comment in cmd["comments"]:
+                return cmd
+        return None
+
+    def get_env(self, env: str) -> Optional[CrontabDict]:
+        for cmd in self.commands:
+            if cmd.get("env") == env:
+                return cmd
+        return None
+
+    def get(self, item: str) -> Optional[CrontabDict]:
+        return self.get_command(command=item, name=item) or self.get_env(item)
+
+    def __getitem__(self, item) -> Optional[CrontabDict]:
+        return self.get(item)
+
+    @override
+    def __repr__(self):
+        return f"CrontabResult({self.commands})"
+
+    # noinspection PyMethodMayBeStatic
+    def format_item(self, item: CrontabDict):
+        lines = []
+        for comment in item.get("comments", []):
+            lines.append(comment)
+
+        if "env" in item:
+            lines.append(item["env"])
+        elif "special_time" in item:
+            lines.append(f"{item['special_time']} {item['command']}")
+        else:
+            lines.append(
+                f"{item['minute']} {item['hour']} "
+                f"{item['day_of_month']} {item['month']} {item['day_of_week']} "
+                f"{item['command']}"
+            )
+        return "\n".join(lines)
+
+    @override
+    def __str__(self):
+        return "\n".join(self.format_item(item) for item in self.commands)
+
+    def to_json(self):
+        return self.commands
+
+
+_crontab_env_re = re.compile(r"^\s*([A-Z_]+)=(.*)$")
+
+
+class Crontab(FactBase[CrontabFile]):
+    """
+    Returns a dictionary of CrontabFile.
+
+    .. code:: python
+
+        # CrontabFile.items()
+        {
+            "/path/to/command": {
+                "minute": "*",
+                "hour": "*",
+                "month": "*",
+                "day_of_month": "*",
+                "day_of_week": "*",
+            },
+            "echo another command": {
+                "special_time": "@daily",
+            },
+        }
+        # or CrontabFile.to_json()
+        [
+            {
+               command: "/path/to/command",
+               minute: "*",
+               hour: "*",
+               month: "*",
+               day_of_month: "*",
+               day_of_week: "*",
+            },
+            {
+                "command": "echo another command
+                "special_time": "@daily",
+            }
+        ]
+    """
+
+    default = CrontabFile
+
+    @override
+    def requires_command(self, user=None) -> str:
+        return "crontab"
+
+    @override
+    def command(self, user=None):
+        if user:
+            return "crontab -l -u {0} || true".format(user)
+        return "crontab -l || true"
+
+    @override
+    def process(self, output):
+        crons = CrontabFile()
+        current_comments = []
+
+        for line in output:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                current_comments.append(line)
+                continue
+
+            if line.startswith("@"):
+                special_time, command = line.split(None, 1)
+                item = CrontabDict(
+                    command=command,
+                    special_time=special_time,
+                    comments=current_comments,
+                )
+                crons.add_item(item)
+
+            elif _crontab_env_re.match(line):
+                # handle environment variables
+                item = CrontabDict(
+                    env=line,
+                    comments=current_comments,
+                )
+                crons.add_item(item)
+            else:
+                minute, hour, day_of_month, month, day_of_week, command = line.split(None, 5)
+                item = CrontabDict(
+                    command=command,
+                    minute=try_int(minute),
+                    hour=try_int(hour),
+                    month=try_int(month),
+                    day_of_month=try_int(day_of_month),
+                    day_of_week=try_int(day_of_week),
+                    comments=current_comments,
+                )
+                crons.add_item(item)
+
+            current_comments = []
+        return crons

pyinfra/facts/deb.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 import shlex
 
+from typing_extensions import override
+
 from pyinfra.api import FactBase
 
 from .util.packaging import parse_packages
@@ -16,9 +18,11 @@ class DebArch(FactBase):
     Returns the architecture string used in apt repository sources, eg ``amd64``.
     """
 
+    @override
     def command(self) -> str:
         return "dpkg --print-architecture"
 
+    @override
     def requires_command(self) -> str:
         return "dpkg"
 
@@ -34,9 +38,11 @@ class DebPackages(FactBase):
         }
     """
 
+    @override
     def command(self) -> str:
         return "dpkg -l"
 
+    @override
     def requires_command(self) -> str:
         return "dpkg"
 
@@ -47,6 +53,7 @@ class DebPackages(FactBase):
         DEB_PACKAGE_VERSION_REGEX,
     )
 
+    @override
     def process(self, output):
         return parse_packages(self.regex, output)
 
@@ -61,14 +68,17 @@ class DebPackage(FactBase):
         "version": r"^Version:\s+({0})$".format(DEB_PACKAGE_VERSION_REGEX),
     }
 
+    @override
     def requires_command(self, package) -> str:
         return "dpkg"
 
+    @override
     def command(self, package):
         return "! test -e {0} && (dpkg -s {0} 2>/dev/null || true) || dpkg -I {0}".format(
             shlex.quote(package)
         )
 
+    @override
     def process(self, output):
         data = {}
 

pyinfra/facts/dnf.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing_extensions import override
+
 from pyinfra.api import FactBase
 
 from .util import make_cat_files_command
@@ -23,6 +25,7 @@ class DnfRepositories(FactBase):
         ]
     """
 
+    @override
     def command(self) -> str:
         return make_cat_files_command(
             "/etc/dnf.conf",
@@ -30,10 +33,12 @@ class DnfRepositories(FactBase):
             "/etc/yum.repos.d/*.repo",
         )
 
+    @override
     def requires_command(self) -> str:
         return "dnf"
 
     default = list
 
+    @override
     def process(self, output):
         return parse_yum_repositories(output)

pyinfra/facts/docker.py

@@ -1,7 +1,15 @@
+"""
+Facts about Docker containers, volumes and networks. These facts give you information from the view
+of the current inventory host. See the :doc:`../connectors/docker` to use Docker containers as
+inventory directly.
+"""
+
 from __future__ import annotations
 
 import json
 
+from typing_extensions import override
+
 from pyinfra.api import FactBase
 
 
@@ -10,9 +18,11 @@ class DockerFactBase(FactBase):
 
     docker_type: str
 
+    @override
     def requires_command(self, *args, **kwargs) -> str:
         return "docker"
 
+    @override
     def process(self, output):
         output = "".join(output)
         return json.loads(output)
@@ -23,6 +33,7 @@ class DockerSystemInfo(DockerFactBase):
     Returns ``docker system info`` output in JSON format.
     """
 
+    @override
     def command(self) -> str:
         return 'docker system info --format="{{json .}}"'
 
@@ -36,6 +47,7 @@ class DockerContainers(DockerFactBase):
     Returns ``docker inspect`` output for all Docker containers.
     """
 
+    @override
     def command(self) -> str:
         return "docker container inspect `docker ps -qa`"
 
@@ -45,6 +57,7 @@ class DockerImages(DockerFactBase):
     Returns ``docker inspect`` output for all Docker images.
     """
 
+    @override
     def command(self) -> str:
         return "docker image inspect `docker images -q`"
 
@@ -54,6 +67,7 @@ class DockerNetworks(DockerFactBase):
     Returns ``docker inspect`` output for all Docker networks.
     """
 
+    @override
     def command(self) -> str:
         return "docker network inspect `docker network ls -q`"
 
@@ -63,6 +77,7 @@ class DockerNetworks(DockerFactBase):
 
 
 class DockerSingleMixin(DockerFactBase):
+    @override
     def command(self, object_id):
         return "docker {0} inspect {1} 2>&- || true".format(
             self.docker_type,
@@ -99,6 +114,7 @@ class DockerVolumes(DockerFactBase):
     Returns ``docker inspect`` output for all Docker volumes.
     """
 
+    @override
     def command(self) -> str:
         return "docker volume inspect `docker volume ls -q`"
 

pyinfra/facts/efibootmgr.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional, Tuple, TypedDict
+
+from typing_extensions import override
+
+from pyinfra.api import FactBase
+
+BootEntry = Tuple[bool, str]
+EFIBootMgrInfoDict = TypedDict(
+    "EFIBootMgrInfoDict",
+    {
+        "BootNext": Optional[int],
+        "BootCurrent": Optional[int],
+        "Timeout": Optional[int],
+        "BootOrder": Optional[List[int]],
+        "Entries": Dict[int, BootEntry],
+    },
+)
+
+
+class EFIBootMgr(FactBase[Optional[EFIBootMgrInfoDict]]):
+    """
+    Returns information about the UEFI boot variables:
+
+    .. code:: python
+
+        {
+            "BootNext": 6,
+            "BootCurrent": 6,
+            "Timeout": 0,
+            "BootOrder": [1,4,3],
+            "Entries": {
+                1: (True, "myefi1"),
+                2: (False, "myefi2.efi"),
+                3: (True, "myefi3.efi"),
+                4: (True, "grub2.efi"),
+            },
+        }
+    """
+
+    @override
+    def requires_command(self, *args: Any, **kwargs: Any) -> str:
+        return "efibootmgr"
+
+    @override
+    def command(self) -> str:
+        # FIXME: Use '|| true' to properly handle the case where
+        #        'efibootmgr' is run on a non-UEFI system
+        return "efibootmgr || true"
+
+    @override
+    def process(self, output: Iterable[str]) -> Optional[EFIBootMgrInfoDict]:
+        # This parsing code closely follows the printing code of efibootmgr
+        # at <https://github.com/rhboot/efibootmgr/blob/main/src/efibootmgr.c#L2020-L2048>
+
+        info: EFIBootMgrInfoDict = {
+            "BootNext": None,
+            "BootCurrent": None,
+            "Timeout": None,
+            "BootOrder": [],
+            "Entries": {},
+        }
+
+        output = iter(output)
+
+        line: Optional[str] = next(output, None)
+
+        if line is None:
+            # efibootmgr run on a non-UEFI system, likely printed
+            # "EFI variables are not supported on this system."
+            # to stderr
+            return None
+
+        # 1. Maybe have BootNext
+        if line and line.startswith("BootNext: "):
+            info["BootNext"] = int(line[len("BootNext: ") :], 16)
+            line = next(output, None)
+
+        # 2. Maybe have BootCurrent
+        if line and line.startswith("BootCurrent: "):
+            info["BootCurrent"] = int(line[len("BootCurrent: ") :], 16)
+            line = next(output, None)
+
+        # 3. Maybe have Timeout
+        if line and line.startswith("Timeout: "):
+            info["Timeout"] = int(line[len("Timeout: ") : -len(" seconds")])
+            line = next(output, None)
+
+        # 4. `show_order`
+        if line and line.startswith("BootOrder: "):
+            entries = line[len("BootOrder: ") :]
+            info["BootOrder"] = list(map(lambda x: int(x, 16), entries.split(",")))
+            line = next(output, None)
+
+        # 5. `show_vars`: The actual boot entries
+        while line is not None and line.startswith("Boot"):
+            number = int(line[4:8], 16)
+
+            # Entries marked with a * are active
+            active = line[8:9] == "*"
+
+            # TODO: Maybe split and parse (name vs. arguments ?), might require --verbose ?
+            entry = line[10:]
+            info["Entries"][number] = (active, entry)
+            line = next(output, None)
+
+        # 6. `show_mirror`
+        # Currently not implemented, since I haven't actually encountered this in the wild.
+        if line is not None:
+            raise ValueError(f"Unexpected line '{line}' while parsing")
+
+        return info

pyinfra/facts/files.py

@@ -1,5 +1,9 @@
 """
 The files facts provide information about the filesystem and it's contents on the target host.
+
+Facts need to be imported before use, eg
+
+from pyinfra.facts.files import File
 """
 
 from __future__ import annotations
@@ -10,11 +14,13 @@ import stat
 from datetime import datetime
 from typing import TYPE_CHECKING, List, Optional, Tuple, Union
 
-from typing_extensions import Literal, NotRequired, TypedDict
+from typing_extensions import Literal, NotRequired, TypedDict, override
 
+from pyinfra.api import StringCommand
 from pyinfra.api.command import QuoteString, make_formatted_string_command
 from pyinfra.api.facts import FactBase
 from pyinfra.api.util import try_int
+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'"
@@ -109,6 +115,7 @@ class File(FactBase[Union[FileDict, Literal[False], None]]):
 
     type = "file"
 
+    @override
     def command(self, path):
         if path.startswith("~/"):
             # Do not quote leading tilde to ensure that it gets properly expanded by the shell
@@ -127,6 +134,7 @@ class File(FactBase[Union[FileDict, Literal[False], None]]):
             bsd_stat_command=BSD_STAT_COMMAND,
         )
 
+    @override
     def process(self, output) -> Union[FileDict, Literal[False], None]:
         match = re.match(STAT_REGEX, output[0])
         if not match:
@@ -231,6 +239,7 @@ class HashFileFactBase(FactBaseOptionalStr):
     _raw_cmd: str
     _regexes: Tuple[str, str]
 
+    @override
     def __init_subclass__(cls, digits: int, cmds: List[str], **kwargs) -> None:
         super().__init_subclass__(**kwargs)
 
@@ -247,10 +256,12 @@ class HashFileFactBase(FactBaseOptionalStr):
             r"^%s\s+\(%%s\)\s+=\s+([a-fA-F0-9]{%d})$" % (hash_name, digits),
         )
 
+    @override
     def command(self, path):
         self.path = path
         return make_formatted_string_command(self._raw_cmd, QuoteString(path))
 
+    @override
     def process(self, output) -> Optional[str]:
         output = output[0]
         escaped_path = re.escape(self.path)
@@ -274,6 +285,12 @@ class Sha256File(HashFileFactBase, digits=64, cmds=["sha256sum", "shasum -a 256"
     """
 
 
+class Sha384File(HashFileFactBase, digits=96, cmds=["sha384sum", "shasum -a 384", "sha384"]):
+    """
+    Returns a SHA384 hash of a file, or ``None`` if the file does not exist.
+    """
+
+
 class Md5File(HashFileFactBase, digits=32, cmds=["md5sum", "md5"]):
     """
     Returns an MD5 hash of a file, or ``None`` if the file does not exist.
@@ -286,6 +303,7 @@ class FindInFile(FactBase):
     lines if the file exists, and ``None`` if the file does not.
     """
 
+    @override
     def command(self, path, pattern, interpolate_variables=False):
         self.exists_flag = "__pyinfra_exists_{0}".format(path)
 
@@ -304,6 +322,7 @@ class FindInFile(FactBase):
             QuoteString(self.exists_flag),
         )
 
+    @override
     def process(self, output):
         # If output is the special string: no matches, so return an empty list;
         # this allows us to differentiate between no matches in an existing file
@@ -319,15 +338,96 @@ class FindFilesBase(FactBase):
     default = list
     type_flag: str
 
+    @override
     def process(self, output):
         return output
 
-    def command(self, path, quote_path=True):
-        return make_formatted_string_command(
-            "find {0} -type {type_flag} || true",
-            QuoteString(path) if quote_path else path,
-            type_flag=self.type_flag,
-        )
+    @override
+    def command(
+        self,
+        path: str,
+        size: Optional[str | int] = None,
+        min_size: Optional[str | int] = None,
+        max_size: Optional[str | int] = None,
+        maxdepth: Optional[int] = None,
+        fname: Optional[str] = None,
+        iname: Optional[str] = None,
+        regex: Optional[str] = None,
+        args: Optional[List[str]] = None,
+        quote_path=True,
+    ):
+        """
+        @param path: the path to start the search from
+        @param size: exact size in bytes or human-readable format.
+                     GB means 1e9 bytes, GiB means 2^30 bytes
+        @param min_size: minimum size in bytes or human-readable format
+        @param max_size: maximum size in bytes or human-readable format
+        @param maxdepth: maximum depth to descend to
+        @param name: True if the last component of the pathname being examined matches pattern.
+                      Special shell pattern matching characters (“[”, “]”, “*”, and “?”)
+                      may be used as part of pattern.
+                      These characters may be matched explicitly
+                      by escaping them with a backslash (“\\”).
+
+        @param iname: Like -name, but the match is case insensitive.
+        @param regex: True if the whole path of the file matches pattern using regular expression.
+        @param args: additional arguments to pass to find
+        @param quote_path: if the path should be quoted
+        @return:
+        """
+        if args is None:
+            args = []
+
+        def maybe_quote(value):
+            return QuoteString(value) if quote_path else value
+
+        command = [
+            "find",
+            maybe_quote(path),
+            "-type",
+            self.type_flag,
+        ]
+
+        """
+        Why we need special handling for size:
+        https://unix.stackexchange.com/questions/275925/why-does-find-size-1g-not-find-any-files
+        In short, 'c' means bytes, without it, it means 512-byte blocks.
+        If we use any units other than 'c', it has a weird rounding behavior,
+        and is implementation-specific. So, we always use 'c'
+        """
+        if "-size" not in args:
+            if min_size is not None:
+                command.append("-size")
+                command.append("+{0}c".format(parse_size(min_size)))
+
+            if max_size is not None:
+                command.append("-size")
+                command.append("-{0}c".format(parse_size(max_size)))
+
+            if size is not None:
+                command.append("-size")
+                command.append("{0}c".format(size))
+
+        if maxdepth is not None and "-maxdepth" not in args:
+            command.append("-maxdepth")
+            command.append("{0}".format(maxdepth))
+
+        if fname is not None and "-fname" not in args:
+            command.append("-name")
+            command.append(maybe_quote(fname))
+
+        if iname is not None and "-iname" not in args:
+            command.append("-iname")
+            command.append(maybe_quote(iname))
+
+        if regex is not None and "-regex" not in args:
+            command.append("-regex")
+            command.append(maybe_quote(regex))
+
+        command.append("||")
+        command.append("true")
+
+        return StringCommand(*command)
 
 
 class FindFiles(FindFilesBase):
@@ -359,15 +459,18 @@ class Flags(FactBase):
     Returns a list of the file flags set for the specified file or directory.
     """
 
+    @override
     def requires_command(self, path) -> str:
         return "chflags"  # don't try to retrieve them if we can't set them
 
+    @override
     def command(self, path):
         return make_formatted_string_command(
             "! test -e {0} || stat -f %Sf {0}",
             QuoteString(path),
         )
 
+    @override
     def process(self, output):
         return [flag for flag in output[0].split(",") if len(flag) > 0] if len(output) == 1 else []
 
@@ -403,6 +506,7 @@ class Block(FactBase):
     # the list with a single empty string.
     default = list
 
+    @override
     def command(self, path, marker=None, begin=None, end=None):
         self.path = path
         start = (marker or MARKER_DEFAULT).format(mark=begin or MARKER_BEGIN_DEFAULT)
@@ -423,6 +527,7 @@ class Block(FactBase):
         )
         return cmd
 
+    @override
     def process(self, output):
         if output and (output[0] == f"{EXISTS}{self.path}"):
             return []