pftag 3.0.0__py3-none-any.whl

pftag/__init__.py

@@ -0,0 +1,43 @@
+"""pftag: a string template processor.
+
+Text with ``%{tags}`` in it is resolved at run time: each tag names a value from the
+core tags (``%{timestamp}``, ``%{hostname}``, ...) or from dictionaries the caller
+registers, and may be piped through functions, ``%{file|rmext|upper}``. Both a library
+and a command.
+
+Key components:
+    - Pftag: the engine, with ``process`` for text and ``argv_process`` for commands
+    - TagOptions, TagResult, ArgvResult: options in, results out
+    - FunctionRegistry: the functions, extensible
+    - __main__: the ``pftag`` command
+
+Typical usage:
+    from pftag import Pftag, TagOptions
+    Pftag(TagOptions(lookups={"run": {"subject": "sub-01"}}))("%{subject}-%{date}.log").result
+
+Dependencies:
+    - faker, optionally, for the dcmname function (``pip install 'pftag[names]'``)
+"""
+
+from __future__ import annotations
+
+__version__: str = "3.0.0"
+
+from pftag.functions import FunctionError, FunctionRegistry
+from pftag.models import ArgvResult, FunctionCall, TagOptions, TagResult, TagToken
+from pftag.pftag import CORE_TAGS, Pftag, TagSyntaxError, coreTag_value
+
+__all__ = [
+    "CORE_TAGS",
+    "ArgvResult",
+    "FunctionCall",
+    "FunctionError",
+    "FunctionRegistry",
+    "Pftag",
+    "TagOptions",
+    "TagResult",
+    "TagSyntaxError",
+    "TagToken",
+    "__version__",
+    "coreTag_value",
+]

pftag/__main__.py

@@ -0,0 +1,284 @@
+"""The ``pftag`` command line and its manual.
+
+Key components:
+    - parser_build: the arguments
+    - synopsis: the manual text
+    - main: the entry point, honouring an explicit ``argv``
+
+Typical usage:
+    pftag --tag "run-%{timestamp|replace(:,-)}-on-%{hostname}.log"
+    pftag --lookupDictAdd '{"s": {"user": "chris"}}' --tag "%{user|md5(8)}"
+    pftag --man
+
+Dependencies:
+    - pftag.pftag, pftag.models
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from collections.abc import Sequence
+
+from pftag import __version__
+from pftag.models import TagOptions, TagResult
+from pftag.pftag import Pftag
+
+BANNER: str = r"""
+          __  _
+         / _|| |
+   _ __ | |_ | |_   __ _   __ _
+  | '_ \|  _|| __| / _` | / _` |
+  | |_) | |  | |_ | (_| || (_| |
+  | .__/|_|   \__| \__,_| \__, |
+  | |                      __/ |
+  |_|                     |___/
+
+                       string template processor
+
+        Text with %{tags} in it, resolved when the text is used. A tag
+        names a value and may pipe it through functions:
+
+            %{inputWorkingFile|rmext}.jpg
+            %{timestamp|replace(:,-)|md5(6)}
+
+                             -- version {version} --
+"""
+
+CLI_SELF: str = """
+        --tag <template>                                                        \\
+        [--lookupDictAdd <json>]                                                \\
+        [--strict]                                                              \\
+        [--json]                                                                \\
+        [--verbosity <level>]                                                   \\
+        [--man] [--synopsis] [--version]"""
+
+ARGS_SYNOPSIS: str = """
+    ARGUMENTS
+
+        --tag <template>
+        The template to process: any text, with tags written %{...}.
+
+        [--lookupDictAdd <json>]
+        Named lookup dictionaries to add, as a JSON object
+
+            '{"secrets": {"CUBEuser": "chris", "CUBEpassword": "chris1234"}}'
+
+        or a list of such objects. Each adds a group of tags, here
+        %{CUBEuser} and %{CUBEpassword}, that can be piped through functions
+        like any tag. A tag name is an identifier: letters, digits and
+        underscores, not starting with a digit. A name may be defined by one
+        dictionary only, unless it is always written qualified: %{secrets.CUBEuser}.
+
+        [--strict]
+        An unknown tag, or a bare %name of a known name outside braces (a 1.x
+        template), fails the run (exit 1) instead of being left as written.
+
+        [--json]
+        Print the whole result as JSON: the text, the tags found, the unknown
+        and 1.x-style tags, the functions applied, any errors.
+
+        [--verbosity <level>]
+        0 (the default) prints only the result; 1 adds warnings about 1.x-style
+        tags; higher levels log more.
+
+        [--man] [--synopsis] [--version]
+        The full manual, the brief one, the version.
+"""
+
+GRAMMAR: str = """
+    GRAMMAR
+
+        A tag is %{ followed by a head, optional functions, and }:
+
+            %{name}
+            %{name|function}
+            %{name|function(arg, arg)|function}
+            %{"literal text"|function}
+
+        Nothing outside %{...} is a tag: printf "%s", date +%Y%m%d and %20 in
+        a URL pass through untouched. Inside the braces % is ordinary, so
+        %{timestamp|strftime(%Y%m%d)} works. \\%{ is a literal "%{".
+
+        The head is a tag name, qualified with its dictionary's name when
+        two dictionaries define it (%{secrets.user}), or a quoted string that
+        starts a chain from literal text. Functions follow in pipe order,
+        left to right, each receiving the previous result. Arguments are
+        comma-separated inside parentheses, bare or quoted; a bare argument
+        is trimmed and may not contain , ) | or }; inside quotes, \\" \\' and
+        \\\\ escape. A function with no arguments may be written with or
+        without ().
+
+        Text after the closing } is kept: %{file|rmext}.txt keeps ".txt".
+        An unknown name is left as written and reported (see --strict). A
+        function that fails leaves its tag as written and fails the run.
+        Values are substituted once; a value containing %{...} is not
+        processed again.
+"""
+
+TAGS_AND_FUNCTIONS: str = """
+    TAGS
+
+        %{timestamp}  the current local time, ISO 8601 with offset
+        %{date}       today's date, YYYY-MM-DD
+        %{hostname}   the host name (in a container, the container id)
+        %{platform}   platform.system(), such as Linux
+        %{user}       the login name, or the numeric uid without a passwd entry
+        %{pid}        the process id
+
+        plus every tag in a registered lookup dictionary. %{core.timestamp}
+        reaches a core tag that a dictionary has shadowed.
+
+    FUNCTIONS
+
+        rmext                   drop the last extension: brain.nii.gz -> brain.nii
+        ext                     the last extension without its dot: gz
+        basename                the last path component
+        dirname                 the path without its last component
+        replace(a, b)           replace every a with b, literally
+        re(pattern, repl)       replace every regular-expression match
+        upper, lower            change case
+        strip[(chars)]          drop surrounding whitespace, or the given chars
+        pad(width[, char])      left-pad with char (default 0): 7 -> 0007
+        slice(stop) / slice(start, stop)
+                                characters by index, Python style
+        md5[(n)], sha256[(n)]   hex digest, cut to n characters
+        strftime(format)        format an ISO 8601 timestamp: %{timestamp|strftime(%Y%m%d)}
+        mask(pattern)           per position, * keeps the character, anything
+                                else replaces it; positions past the pattern
+                                are kept
+        dcmname[(seed)]         a LAST^FIRST pseudonym, stable for a seed (the
+                                value itself when no seed is given). Needs
+                                pip install 'pftag[names]'. A seeded hash
+                                wearing a name, not anonymization.
+
+        Carrying protected text safely, hashed rather than written:
+
+            %{"Subject12345"|sha256(8)}
+"""
+
+EXAMPLES: str = """
+    EXAMPLES
+
+        pftag --tag "run-%{timestamp}-on-%{hostname}.log"
+        pftag --tag "run-%{timestamp|replace(:,-)}-on-%{hostname}.log"
+        pftag --tag "run-%{timestamp|strftime(%Y%m%d-%H%M)}.log"
+        pftag --lookupDictAdd '{"s": {"user": "chris"}}' --tag "user %{user}, hash %{user|md5(8)}"
+        pftag --tag "100% done, %{date}"
+        pftag --tag "%{nope}" --strict        # exit 1
+"""
+
+VERBOSITY_LOG_LEVELS: dict[int, int] = {0: logging.ERROR, 1: logging.WARNING, 2: logging.INFO}
+
+
+def synopsis(shortOnly: bool = False) -> str:
+    """The manual text.
+
+    Args:
+        shortOnly: NAME and SYNOPSIS only.
+
+    Returns:
+        The text, without the banner.
+    """
+    short: str = (
+        """
+    NAME
+
+        pftag - resolve %{tags} in a template, with optional functions
+
+    SYNOPSIS
+
+        pftag \\"""
+        + CLI_SELF
+        + "\n"
+    )
+    if shortOnly:
+        return short
+    description: str = """
+    DESCRIPTION
+
+        pftag is both a command and a library for processing templates: text
+        whose %{tags} are resolved when the text is used, each optionally
+        piped through functions. The core tags describe the machine and the
+        moment; a program adds its own tags as named lookup dictionaries.
+        The pf* family uses it wherever a user writes a template on the
+        command line, such as pfdo_run's --exec string and pflog's
+        telemetry URLs. See docs/tags.adoc for the full reference.
+"""
+    return short + description + ARGS_SYNOPSIS + GRAMMAR + TAGS_AND_FUNCTIONS + EXAMPLES
+
+
+def parser_build() -> argparse.ArgumentParser:
+    """The command's parser.
+
+    Returns:
+        The parser; ``--help`` is the quick reference and points at ``--man``.
+    """
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
+        prog="pftag",
+        description="Resolve %%{tags} in a template, optionally through piped functions. Manual: pftag --man",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--tag", dest="tag", default="", help="the template to process")
+    parser.add_argument("--lookupDictAdd", dest="lookupDictAdd", default="", help="lookup dictionaries, JSON")
+    parser.add_argument("--strict", dest="strict", action="store_true", help="unknown or 1.x-style tags fail")
+    parser.add_argument("--json", dest="json", action="store_true", help="print the whole result as JSON")
+    parser.add_argument("--verbosity", dest="verbosity", type=int, default=0, help="0 prints only the result")
+    parser.add_argument("--man", dest="man", action="store_true", help="show the full manual and exit")
+    parser.add_argument("--synopsis", dest="synopsis", action="store_true", help="show the brief manual")
+    parser.add_argument("--version", action="version", version=f"pftag {__version__}")
+    return parser
+
+
+def options_fromArgs(args: argparse.Namespace) -> TagOptions:
+    """Turn parsed arguments into options."""
+    return TagOptions(strict=args.strict, tag=args.tag, json=args.json, verbosity=args.verbosity)
+
+
+def manual_print(shortOnly: bool) -> None:
+    """Print the banner and the manual."""
+    print(BANNER.replace("{version}", __version__))
+    print(synopsis(shortOnly))
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command.
+
+    Args:
+        argv: arguments without the program name; ``None`` reads ``sys.argv``.
+
+    Returns:
+        0 when the template was processed; 1 when ``--strict`` met an unknown or
+        1.x-style tag, a tag did not parse, or a function failed; 2 on bad arguments.
+    """
+    parser: argparse.ArgumentParser = parser_build()
+    args: argparse.Namespace = parser.parse_args(argv)
+    if args.man or args.synopsis:
+        manual_print(shortOnly=not args.man)
+        return 0
+    if not args.tag:
+        parser.error("--tag is required")
+    options: TagOptions = options_fromArgs(args)
+    logging.basicConfig(
+        level=VERBOSITY_LOG_LEVELS.get(options.verbosity, logging.DEBUG), format="%(message)s"
+    )
+    try:
+        tagger: Pftag = Pftag(options)
+        if args.lookupDictAdd:
+            tagger.lookups_addFromJson(args.lookupDictAdd)
+    except ValueError as err:
+        parser.error(str(err))
+    result: TagResult = tagger.process(options.tag)
+    if options.json:
+        print(json.dumps(result.toDict(), indent=4, sort_keys=True))
+    else:
+        print(result.result)
+    for error in result.errors:
+        print(error, file=sys.stderr)
+    return 0 if result.status else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pftag/functions.py

@@ -0,0 +1,257 @@
+"""The functions a tag's value can be piped through.
+
+A function takes the value so far and the arguments written in the template, and
+returns new text. Functions chain left to right: ``%{timestamp|replace(:,-)|md5(6)}``
+replaces the colons in the timestamp and hashes the result to six characters. The
+registry maps names to functions and is extensible; the pseudonym generator lives in
+``pftag.names`` and is registered only when its dependency is installed.
+
+Key components:
+    - TagFunction: the signature every function has
+    - FunctionRegistry: name to function, with the built-ins preloaded
+    - the built-ins: path parts, replacement, case, padding, slicing, hashing,
+      masking, time formatting
+
+Typical usage:
+    registry = FunctionRegistry()
+    registry.add("shout", lambda value, args: value.upper() + "!")
+
+Dependencies:
+    - standard library only
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import PurePosixPath
+
+TagFunction = Callable[[str, list[str]], str]
+
+MASK_KEEP: str = "*"
+
+
+class FunctionError(ValueError):
+    """A function was given arguments it cannot work with, or does not exist."""
+
+
+def args_count(name: str, args: list[str], atLeast: int, atMost: int | None = None) -> None:
+    """Fail clearly on a wrong number of arguments.
+
+    Args:
+        name: the function, for the message.
+        args: the arguments given.
+        atLeast: the minimum.
+        atMost: the maximum; None for no limit.
+
+    Raises:
+        FunctionError: when the count is outside the range.
+    """
+    if len(args) < atLeast or (atMost is not None and len(args) > atMost):
+        expected: str = str(atLeast) if atMost == atLeast else f"{atLeast} to {atMost or 'any'}"
+        raise FunctionError(f"{name} takes {expected} argument(s), got {len(args)}: {args}")
+
+
+def int_arg(name: str, text: str) -> int:
+    """An integer argument, or a clear failure."""
+    try:
+        return int(text)
+    except ValueError as err:
+        raise FunctionError(f"{name}: {text!r} is not an integer") from err
+
+
+def rmext(value: str, args: list[str]) -> str:
+    """Drop the last extension: ``brain.nii.gz`` becomes ``brain.nii``."""
+    args_count("rmext", args, 0, 0)
+    suffix: str = PurePosixPath(value).suffix
+    return value[: -len(suffix)] if suffix else value
+
+
+def ext(value: str, args: list[str]) -> str:
+    """The last extension without its dot: ``brain.nii.gz`` gives ``gz``."""
+    args_count("ext", args, 0, 0)
+    return PurePosixPath(value).suffix.lstrip(".")
+
+
+def basename(value: str, args: list[str]) -> str:
+    """The last path component."""
+    args_count("basename", args, 0, 0)
+    return PurePosixPath(value).name
+
+
+def dirname(value: str, args: list[str]) -> str:
+    """The path without its last component."""
+    args_count("dirname", args, 0, 0)
+    return str(PurePosixPath(value).parent)
+
+
+def replace(value: str, args: list[str]) -> str:
+    """Replace every occurrence of the first argument with the second, literally."""
+    args_count("replace", args, 2, 2)
+    return value.replace(args[0], args[1])
+
+
+def re_sub(value: str, args: list[str]) -> str:
+    """Replace every match of a regular expression with the second argument."""
+    args_count("re", args, 2, 2)
+    try:
+        return re.sub(args[0], args[1], value)
+    except re.error as err:
+        raise FunctionError(f"re: bad pattern {args[0]!r}: {err}") from err
+
+
+def upper(value: str, args: list[str]) -> str:
+    """Upper case."""
+    args_count("upper", args, 0, 0)
+    return value.upper()
+
+
+def lower(value: str, args: list[str]) -> str:
+    """Lower case."""
+    args_count("lower", args, 0, 0)
+    return value.lower()
+
+
+def strip(value: str, args: list[str]) -> str:
+    """Drop leading and trailing whitespace, or the characters in the argument."""
+    args_count("strip", args, 0, 1)
+    return value.strip(args[0]) if args else value.strip()
+
+
+def pad(value: str, args: list[str]) -> str:
+    """Left-pad to a width with a character (default ``0``): ``pad(4)`` turns ``7`` into ``0007``."""
+    args_count("pad", args, 1, 2)
+    width: int = int_arg("pad", args[0])
+    fill: str = args[1] if len(args) > 1 else "0"
+    if len(fill) != 1:
+        raise FunctionError(f"pad: fill must be one character, not {fill!r}")
+    return value.rjust(width, fill)
+
+
+def slice_(value: str, args: list[str]) -> str:
+    """Characters from the first index up to the second, Python style; one argument means a prefix."""
+    args_count("slice", args, 1, 2)
+    if len(args) == 1:
+        return value[: int_arg("slice", args[0])]
+    return value[int_arg("slice", args[0]) : int_arg("slice", args[1])]
+
+
+def md5(value: str, args: list[str]) -> str:
+    """The MD5 hex digest, cut to the first argument's length when given."""
+    args_count("md5", args, 0, 1)
+    digest: str = hashlib.md5(value.encode("utf-8")).hexdigest()  # a tag, not a secret
+    return digest[: int_arg("md5", args[0])] if args else digest
+
+
+def sha256(value: str, args: list[str]) -> str:
+    """The SHA-256 hex digest, cut to the first argument's length when given."""
+    args_count("sha256", args, 0, 1)
+    digest: str = hashlib.sha256(value.encode("utf-8")).hexdigest()
+    return digest[: int_arg("sha256", args[0])] if args else digest
+
+
+def strftime(value: str, args: list[str]) -> str:
+    """Format an ISO 8601 timestamp with a ``strftime`` pattern: ``strftime(%Y%m%d)``."""
+    args_count("strftime", args, 1, 1)
+    try:
+        moment: datetime = datetime.fromisoformat(value)
+    except ValueError as err:
+        raise FunctionError(f"strftime: {value!r} is not an ISO 8601 timestamp") from err
+    return moment.strftime(args[0])
+
+
+def mask(value: str, args: list[str]) -> str:
+    """Mask character by character.
+
+    For each position of the pattern, ``*`` keeps the value's character and any other
+    character replaces it; positions past the pattern are kept, so the result is never
+    shorter than the value.
+    """
+    args_count("mask", args, 1, 1)
+    pattern: str = args[0]
+    out: list[str] = []
+    for index, char in enumerate(value):
+        if index < len(pattern) and pattern[index] != MASK_KEEP:
+            out.append(pattern[index])
+        else:
+            out.append(char)
+    return "".join(out)
+
+
+class FunctionRegistry:
+    """Name to function, with the built-ins preloaded.
+
+    Attributes:
+        functions: the registered functions by name.
+
+    Example:
+        >>> FunctionRegistry().apply("upper", "abc", [])
+        'ABC'
+    """
+
+    def __init__(self) -> None:
+        self.functions: dict[str, TagFunction] = {
+            "rmext": rmext,
+            "ext": ext,
+            "basename": basename,
+            "dirname": dirname,
+            "replace": replace,
+            "re": re_sub,
+            "upper": upper,
+            "lower": lower,
+            "strip": strip,
+            "pad": pad,
+            "slice": slice_,
+            "md5": md5,
+            "sha256": sha256,
+            "strftime": strftime,
+            "mask": mask,
+        }
+        self.names_register()
+
+    def names_register(self) -> None:
+        """Register the pseudonym functions when their dependency is installed."""
+        try:
+            from pftag.names import dcmname
+        except ImportError:
+            return
+        self.functions["dcmname"] = dcmname
+
+    def add(self, name: str, function: TagFunction) -> None:
+        """Register a function, replacing any of the same name.
+
+        Args:
+            name: the name used in templates.
+            function: ``(value, args) -> str``.
+        """
+        self.functions[name] = function
+
+    def has(self, name: str) -> bool:
+        """Whether a function is registered."""
+        return name in self.functions
+
+    def names(self) -> list[str]:
+        """The registered names, sorted."""
+        return sorted(self.functions)
+
+    def apply(self, name: str, value: str, args: list[str]) -> str:
+        """Run a function.
+
+        Args:
+            name: a registered name.
+            value: the text so far.
+            args: the arguments written in the template.
+
+        Returns:
+            The function's result.
+
+        Raises:
+            FunctionError: if the name is unknown or the arguments are unusable.
+        """
+        if name not in self.functions:
+            if name == "dcmname":
+                raise FunctionError("dcmname needs the names extra: pip install 'pftag[names]'")
+            raise FunctionError(f"unknown function {name!r}; known: {', '.join(self.names())}")
+        return self.functions[name](value, args)