veridret 1__py3-none-any.whl

veridret/__init__.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+VerIdRet (*Ver*sion-*Id*entifier *Ret*riever),
+a program that retrieves the version identifiers
+of the locally installed and upstream versions of software.
+"""
+
+import functools
+import os
+import os.path
+import typing
+from typing import Final
+
+__all__: Final = [
+    'get_config_dirs',
+]
+
+__version__: Final = '1'
+
+PATH_LIST_SEP: Final = ':'
+
+@typing.overload
+def getenv_if_abs_path[T](key: str, default: T) -> str | T:
+    ...
+@typing.overload
+def getenv_if_abs_path(key: str) -> str | None:
+    ...
+def getenv_if_abs_path[T](
+    key: str, default: T | None = None,
+) -> str | T | None:
+    value = os.getenv(key)
+    if value is None or not os.path.isabs(value):
+        return default
+    return value
+
+@functools.cache
+def get_config_dirs() -> tuple[str, ...]:
+    """
+    Get the paths to the program's configuration directories.
+
+    :return:
+        A tuple of the paths to the program's configuration directories,
+        in order of decreasing priority.
+    """
+
+    config_dirs = os.getenv('VERIDRET_CONFIG')
+    if config_dirs is not None:
+        return tuple(config_dirs.split(PATH_LIST_SEP))
+
+    xdg_config_home = getenv_if_abs_path('XDG_CONFIG_HOME')
+    if xdg_config_home is None:
+        home_dir = getenv_if_abs_path('HOME', '/')
+        xdg_config_home = os.path.join(home_dir, '.config')
+
+    system_config_home = '/etc'
+
+    return tuple(
+        os.path.join(x, 'veridret')
+        for x in (xdg_config_home, system_config_home)
+    )

veridret/__main__.py

@@ -0,0 +1,302 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+The program's entry point.
+"""
+
+import dataclasses
+import enum
+import json
+import io
+import sys
+import threading
+from collections.abc import MutableSequence, Sequence
+from contextlib import ExitStack
+from queue import Queue, ShutDown as QueueShutDown
+from typing import Any, Final, Never, TypeIs
+
+import regex
+
+import structlog
+
+import veridret.json
+from veridret._cli import parse as parse_args
+from veridret._config import Config
+from veridret._logging import init as init_logging
+from veridret._sw import Config as SwConfig
+from veridret._unset import Unset
+from veridret._version_info import Fields as VersionInfoFields, VersionInfo
+from veridret.logging import Logger
+
+__all__: Final = [
+    'main',
+]
+
+g_logger: Final[Logger] = structlog.get_logger(logger_name=__name__)
+
+def json_seq_dump(
+    obj: object, fp: io.Writer[str], **kwargs: Any,
+) -> None:
+    fp.write('\N{RECORD SEPARATOR}')
+    json.dump(obj, fp, **kwargs)
+    fp.write('\n')
+
+def sw_proc_thread_main_impl(
+    *,
+    queue: Queue[tuple[str, SwConfig]],
+    version_info_fields: VersionInfoFields,
+    output_lock: threading.Lock,
+) -> bool:
+    name_field_mask = version_info_fields & VersionInfoFields.NAME
+    ok = True
+
+    while True:
+        try:
+            name, config = queue.get()
+        except QueueShutDown:
+            break
+
+        with ExitStack() as exit_stack:
+            exit_stack.callback(queue.task_done)
+
+            logger = g_logger.bind(
+                software={
+                    'name': name,
+                    'config': config,
+                },
+                requested_version_info_fields=version_info_fields,
+            )
+
+            logger.info('processing software')
+
+            version_info = VersionInfo.compute(config, version_info_fields)
+            actual_fields = version_info.field_mask() | name_field_mask
+            if version_info_fields not in actual_fields:
+                ok = False
+                logger.error(
+                    'cannot compute all requested version-info fields',
+                    actual_version_info_fields=actual_fields,
+                    cause='(previous error(s))',
+                )
+
+            version_info_with_name = {
+                'name': name if name_field_mask else Unset(),
+                'local': version_info.local,
+                'upstream': version_info.upstream,
+                'comparison': version_info.comparison,
+            }
+
+            output_obj = {
+                k: v
+                for k, v in version_info_with_name.items()
+                if not isinstance(v, Unset)
+            }
+
+            try:
+                with output_lock:
+                    json_seq_dump(
+                        output_obj,
+                        sys.stdout,
+                        skipkeys=True,
+                        separators=(',', ':'),
+                        default=veridret.json.to_directly_encodable,
+                    )
+            # pylint: disable-next=broad-exception-caught
+            except Exception as e:
+                ok = False
+                logger.error('cannot output version info', cause=e)
+
+            logger.info('done processing software')
+
+    return ok
+
+def sw_proc_thread_main(
+    index: int,
+    *,
+    queue: Queue[tuple[str, SwConfig]],
+    oks: MutableSequence[bool],
+    version_info_fields: VersionInfoFields,
+    output_lock: threading.Lock,
+) -> None:
+    oks[index] = sw_proc_thread_main_impl(
+        queue=queue,
+        version_info_fields=version_info_fields,
+        output_lock=output_lock,
+    )
+
+@dataclasses.dataclass(kw_only=True, frozen=True)
+class SwProcessingThreadInfo:
+    threads: Sequence[threading.Thread]
+    oks: MutableSequence[bool]
+
+def create_sw_proc_threads(
+    n: int,
+    queue: Queue[tuple[str, SwConfig]],
+    version_info_fields: VersionInfoFields,
+) -> SwProcessingThreadInfo:
+    oks = [False] * n
+    output_lock = threading.Lock()
+    threads = tuple(
+        threading.Thread(
+            target=sw_proc_thread_main,
+            args=(i,),
+            kwargs={
+                'queue': queue,
+                'oks': oks,
+                'version_info_fields': version_info_fields,
+                'output_lock': output_lock,
+            },
+        )
+        for i in range(n)
+    )
+    return SwProcessingThreadInfo(threads=threads, oks=oks)
+
+@dataclasses.dataclass(frozen=True)
+class SoftwareNamePatternFilter:
+    pattern: regex.Pattern[str] | None = None
+
+    def __call__(self, name: str) -> bool:
+        return self.pattern is None or bool(self.pattern.search(name))
+
+def load_and_enqueue_software(
+    queue: Queue[tuple[str, SwConfig]],
+    name_filter: SoftwareNamePatternFilter,
+) -> bool:
+    logger = g_logger.bind()
+
+    ok = True
+
+    def sw_filter(
+        software: tuple[str, SwConfig | None] | None,
+    ) -> TypeIs[tuple[str, SwConfig]]:
+        nonlocal ok
+        match software:
+            case name, config:
+                if not name_filter(name):
+                    logger.debug(
+                        'discarding software from processing',
+                        software=name,
+                        software_name_pattern=name_filter.pattern,
+                        cause='software-name pattern mismatch',
+                    )
+                    return False
+                match config:
+                    case SwConfig():
+                        return True
+                    case None:
+                        ok = False
+                        return False
+            case None:
+                ok = False
+                return False
+
+    logger.debug('enqueuing software for processing')
+
+    sw_iter = (x for x in SwConfig.load_all() if sw_filter(x))
+    for name, config in sw_iter:
+        sw_logger = logger.bind(
+            software={
+                'name': name,
+                'config': config,
+            },
+        )
+
+        sw_logger.debug(
+            'enqueuing software for processing',
+        )
+        queue.put((name, config))
+        sw_logger.debug(
+            'done enqueuing software for processing',
+        )
+
+    logger.debug('done enqueuing software for processing')
+
+    return ok
+
+class ExitCode(enum.Enum):
+    SUCCESS = 0
+    FAILURE = 1
+
+    def __int__(self) -> int:
+        return self.value
+
+def main() -> Never:
+    """
+    Run the program
+    and then terminate the current process.
+
+    This function is the program's entry point
+    and terminates the current process upon completion.
+    If the program's command-line arguments are incorrect,
+    then the exit code is 2;
+    otherwise,
+    if program encounteres unrecoverable errors,
+    then the exit code is 1;
+    otherwise,
+    the exit code is 0.
+
+    :return: This function does not return.
+    """
+
+    args = parse_args()
+
+    init_logging(
+        min_level=args.min_logging_level,
+        fmt=args.log_format,
+    )
+
+    logger = g_logger.bind()
+
+    config = Config.load(
+        max_job_count=args.max_job_count,
+        job_queue_capacity=args.job_queue_capacity,
+    )
+
+    sw_queue: Queue[tuple[str, SwConfig]] = Queue(
+        config.job_queue_capacity,
+    )
+
+    sw_proc_thread_info = create_sw_proc_threads(
+        config.max_job_count, sw_queue, args.version_info_fields,
+    )
+    sw_proc_threads = sw_proc_thread_info.threads
+    sw_proc_thread_oks = sw_proc_thread_info.oks
+
+    logger.debug('starting software-processing threads')
+    for i, t in enumerate(sw_proc_threads):
+        logger.debug(
+            'starting software-processing thread',
+            software_processing_thread=t,
+            software_processing_thread_index=i,
+        )
+        t.start()
+    logger.debug('done starting software-processing threads')
+
+    sw_loading_ok = load_and_enqueue_software(
+        sw_queue,
+        SoftwareNamePatternFilter(args.software_name_pattern),
+    )
+
+    logger.debug('shutting down software queue')
+    sw_queue.shutdown()
+
+    logger.debug('joining software-processing threads')
+    for i, t in enumerate(sw_proc_threads):
+        logger.debug(
+            'joining software-processing thread',
+            software_processing_thread_index=i,
+            software_processing_thread=t,
+        )
+        t.join()
+    logger.debug('done joining software-processing threads')
+
+    ok = sw_loading_ok and all(sw_proc_thread_oks)
+    if not ok:
+        logger.error('one or more unrecoverable errors occurred')
+
+    exit_code = ExitCode.SUCCESS if ok else ExitCode.FAILURE
+    logger.info('exitting', exit_code=exit_code)
+    sys.exit(int(exit_code))
+
+if __name__ == '__main__':
+    main()

veridret/_cli.py

@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+The program's command-line interface.
+"""
+
+import argparse
+import dataclasses
+import enum
+import functools
+import logging
+import typing
+from typing import Final
+
+import regex
+
+import veridret
+from veridret._logging import Format as LogFormat
+from veridret._version_info import Fields as VersionInfoFields
+from veridret.logging import Level as RealLoggingLevel
+
+__all__: Final = [
+    'Args',
+    'parse',
+]
+
+def parse_regex(pattern: str) -> regex.Pattern[str]:
+    try:
+        return regex.compile(pattern)
+    except regex.error as e:
+        raise argparse.ArgumentTypeError(
+            f'invalid regular expression: {pattern!r}: {e}',
+        ) from e
+
+def parse_version_info_fields(fields: str) -> VersionInfoFields:
+    def acc_func(
+        acc: VersionInfoFields, index_char_pair: tuple[int, str],
+    ) -> VersionInfoFields:
+        match index_char_pair:
+            case _, 'n':
+                field = VersionInfoFields.NAME
+            case _, 'l':
+                field = VersionInfoFields.LOCAL
+            case _, 'u':
+                field = VersionInfoFields.UPSTREAM
+            case _, 'c':
+                field = VersionInfoFields.COMPARISON
+            case i, c:
+                raise ValueError(f'invalid character at position {i}: {c!r}')
+        return acc | field
+
+    try:
+        return functools.reduce(
+            acc_func,
+            enumerate(fields),
+            initial=VersionInfoFields(0),
+        )
+    except ValueError as e:
+        raise (
+            argparse.ArgumentTypeError(f'invalid FIELDS: {fields!r}: {e}')
+        ) from e
+
+class LoggingLevel(enum.Enum):
+    DEBUG = enum.auto()
+    INFO = enum.auto()
+    WARNING = enum.auto()
+    ERROR = enum.auto()
+    CRITICAL = enum.auto()
+    OFF = enum.auto()
+
+    @typing.override
+    def __str__(self) -> str:
+        return self.name.lower()
+
+    def get_logging_level(self) -> RealLoggingLevel | None:
+        match self:
+            case LoggingLevel.OFF:
+                return None
+            case _:
+                return getattr(logging, self.name)
+
+def parse_enum_uppercase[T: enum.Enum](value: str, cls: type[T]) -> T:
+    try:
+        return cls[value.upper()]
+    except KeyError as e:
+        choices = ', '.join(repr(x.name.lower()) for x in cls)
+        raise argparse.ArgumentTypeError(
+            f'invalid choice: {value!r} (choose from {choices})',
+        ) from e
+
+@dataclasses.dataclass(kw_only=True)
+class Args:
+    """
+    The parsed arguments of the program.
+    """
+
+    software_name_pattern: regex.Pattern[str] | None
+    version_info_fields: VersionInfoFields
+    max_job_count: int | None
+    job_queue_capacity: int | None
+    log_format: LogFormat
+    min_logging_level: RealLoggingLevel | None
+
+def parse() -> Args:
+    """
+    Parse the arguments to the program.
+
+    This function terminates the current process
+    if it cannot parse the program arguments into an ``Args``,
+    such as if the program arguments are incorrect
+    or if they include the command-line option ``--help``.
+
+    :return: The parsed program arguments.
+    """
+
+    parser = argparse.ArgumentParser(
+        description='''
+VerIdRet (Version-Identifier Retriever)
+is a program that retrieves the version identifiers
+of the locally installed and upstream versions of software.
+The program outputs the version information
+of each piece of software configured with it
+to standard output as a record,
+specifically a JSON object,
+in a JSON stream of MIME type application/json-seq.
+        ''',
+    )
+    parser.add_argument(
+        '-V', '--version',
+        action='version',
+        version=f'VerIdRet {veridret.__version__}',
+        help='''
+show the program's version information and exit
+        ''',
+    )
+    parser.add_argument(
+        '-n', '--name',
+        type=parse_regex,
+        metavar='PATTERN',
+        help='''
+process only software any substring of whose name matches this pattern,
+whose syntax and semantics
+are those of the patterns in the Python package "regex",
+overriding the default behavior
+of processing all software regardless of name
+        ''',
+    )
+    parser.add_argument(
+        '-f', '--fields',
+        type=parse_version_info_fields,
+        default='nluc',
+        help='''
+what fields to place in the record,
+a JSON object,
+of each piece of software's version information
+that is outputted to standard output;
+each character of FIELDS represents
+a field to include in the record,
+the allowed characters being
+'n' for the name of the software
+as the field "name",
+'l' for the locally installed version of the software
+as the field "local",
+'u' for the upstream version of the software
+as the field "upstream",
+and 'c' for the comparison,
+of the locally installed to the upstream version of the software,
+as the field "comparison";
+each field occurs at most once in the record,
+no matter how many times its character occurs in FIELDS;
+if computing the value of a field specified in FIELDS fails,
+then the record will not contain that field
+(computing the value of the field "name" never fails)
+[default: %(default)r]
+        ''',
+    )
+    parser.add_argument(
+        '-j', '--jobs',
+        type=int,
+        metavar='N',
+        help='''
+the maximum number of pieces of software to process in parallel;
+overrides the setting 'max_job_count'
+in the 'veridret.toml' configuration files
+        ''',
+    )
+    parser.add_argument(
+        '-Q', '--queue-capacity',
+        type=int,
+        metavar='N',
+        help='''
+the maximum number of unprocessed pieces of software
+to have queued for eventual processing;
+overrides the setting 'job_queue_capacity'
+in the 'veridret.toml' configuration files
+        ''',
+    )
+    parser.add_argument(
+        '-F', '--log-format',
+        metavar=f'{{{','.join(x.name.lower() for x in LogFormat)}}}',
+        type=lambda x: parse_enum_uppercase(x, LogFormat),
+        default=LogFormat.HUMAN,
+        help='''
+the program's log's format;
+case-insensitive;
+'human' writes each log entry to standard error upon a new line
+and formats the entry in a human-readable way;
+'json' formats each log entry
+as a JSON object of the form
+{
+    "event": "<log-message>",
+    "level": "<logging-level>"
+    [, ...]
+}
+and writes such objects together to standard error
+as a JSON stream of MIME type application/json-seq
+[default: '%(default)s']
+        ''',
+    )
+    parser.add_argument(
+        '-m', '--min-logging-level', '--logging-level',
+        metavar=f'{{{','.join(x.name.lower() for x in LoggingLevel)}}}',
+        type=lambda x: parse_enum_uppercase(x, LoggingLevel),
+        default=LoggingLevel.INFO,
+        help='''
+the minimum logging level;
+case-insensitive
+[default: '%(default)s']
+        ''',
+    )
+
+    args = parser.parse_args()
+    return Args(
+        software_name_pattern=args.name,
+        version_info_fields=args.fields,
+        max_job_count=args.jobs,
+        job_queue_capacity=args.queue_capacity,
+        log_format=args.log_format,
+        min_logging_level=args.min_logging_level.get_logging_level(),
+    )

veridret/_comparison.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+An enumeration representing
+the result of an ordered or unordered comparison.
+"""
+
+import enum
+import typing
+from typing import Any, Final
+
+__all__: Final = [
+    'Comparison',
+]
+
+class Comparison(enum.Enum):
+    """
+    An enumeration representing
+    the result of an ordered or unordered comparison.
+    """
+
+    LT = enum.auto()
+    EQ = enum.auto()
+    GT = enum.auto()
+    NE = enum.auto()
+
+    @typing.override
+    def __str__(self) -> str:
+        """
+        Convert this ``Comparison`` to a human-readable string.
+
+        :param self: This ``Comparison``.
+        :return: ``self.name``.
+        """
+
+        return self.name
+
+    def __neg__(self) -> Comparison:
+        """
+        Negate, or reflect, this ``Comparison``.
+
+        ``Comparison.LT`` and ``Comparison.GT`` are each other's reflection
+        while ``Comparison.EQ`` and ``Comparison.NE``
+        are each their own reflection.
+
+        :param self: This ``Comparison``.
+        :return: The negation, or reflection, of ``self``.
+        """
+
+        match self:
+            case Comparison.LT:
+                return Comparison.GT
+            case Comparison.EQ | Comparison.NE:
+                return self
+            case Comparison.GT:
+                return Comparison.LT
+
+    @staticmethod
+    def from_object_comparison(a: object, b: object) -> Comparison:
+        """
+        Compute the ``Comparison`` value
+        corresponding to the comparison between two objects.
+
+        :param a: The left-hand object to compare.
+        :param b: The right-hand object to compare.
+        :return:
+            If ``a < b`` does not raise a ``TypeError``,
+            then,
+            if ``a < b`` is true,
+            then the function returns ``Comparison.LT``,
+            else,
+            if ``a == b`` is true,
+            then the function returns ``Comparison.EQ``,
+            else the function returns ``Comparison.GT``;
+            if ``a < b`` does raise a ``TypeError``,
+            then,
+            if ``a == b`` is true,
+            then the function returns ``Comparison.EQ``,
+            else the function returns ``Comparison.NE``.
+        :raise Exception:
+            If ``a < b`` or ``a == b`` raises an exception,
+            then that exception is propagated,
+            except for a ``TypeError`` raised by ``a < b``.
+        """
+
+        try:
+            lt = typing.cast(Any, a) < b
+        except TypeError:
+            return Comparison.EQ if a == b else Comparison.NE
+
+        return (
+            Comparison.LT if lt
+            else Comparison.EQ if a == b
+            else Comparison.GT
+        )