proj-flow 0.8.1__py3-none-any.whl

proj_flow/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+__version__ = "0.8.1"

proj_flow/__main__.py

@@ -0,0 +1,10 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.__main__** allows *C++ flow* to be called as Python component.
+"""
+
+from .flow.cli import main
+
+main()

proj_flow/api/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.api** contains public APIs, usable in third-party plugins.
+"""
+
+from . import arg, completers, ctx, env, init, makefile, step
+
+__all__ = ["arg", "completers", "ctx", "env", "init", "makefile", "step"]

proj_flow/api/arg.py

@@ -0,0 +1,134 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.api.arg** is used by various commands to declare CLI arguments.
+"""
+
+import argparse
+import inspect
+import typing
+from dataclasses import dataclass, field
+
+from proj_flow.base import inspect as _inspect
+
+
+@dataclass
+class Argument:
+    help: str = ""
+    pos: bool = False
+    names: typing.List[str] = field(default_factory=list)
+    nargs: typing.Union[str, int, None] = None
+    opt: typing.Optional[bool] = None
+    meta: typing.Optional[str] = None
+    action: typing.Union[str, argparse.Action, None] = None
+    default: typing.Optional[typing.Any] = None
+    choices: typing.Optional[typing.List[str]] = None
+    completer: typing.Optional[callable] = None  # type: ignore
+
+    def visit(self, parser: argparse.ArgumentParser, name: str):
+        kwargs = {}
+        if self.help is not None:
+            kwargs["help"] = self.help
+        if self.nargs is not None:
+            kwargs["nargs"] = self.nargs
+        if self.meta is not None:
+            kwargs["metavar"] = self.meta
+        if self.default is not None:
+            kwargs["default"] = self.default
+        if self.action is not None:
+            kwargs["action"] = self.action
+        if self.choices is not None:
+            kwargs["choices"] = self.choices
+
+        names = (
+            [name] if self.pos else self.names if len(self.names) > 0 else [f"--{name}"]
+        )
+
+        if self.pos:
+            kwargs["nargs"] = "?" if self.opt else 1
+        else:
+            kwargs["dest"] = name
+            kwargs["required"] = not self.opt
+
+        action = parser.add_argument(*names, **kwargs)
+        if self.completer:
+            action.completer = self.completer  # type: ignore
+
+        return action
+
+
+class FlagArgument(Argument):
+    def __init__(self, help: str = "", names: typing.List[str] = []):
+        super().__init__(
+            help=help, names=names, opt=True, action="store_true", default=False
+        )
+
+
+@dataclass
+class _Command:
+    name: str
+    entry: typing.Optional[callable]  # type: ignore
+    doc: typing.Optional[str]
+    subs: typing.Dict[str, "_Command"]
+
+    def add(self, names: typing.List[str], entry: callable, doc: typing.Optional[str]):  # type: ignore
+        name = names[0]
+        rest = names[1:]
+        if len(rest):
+            try:
+                child = self.subs[name]
+            except KeyError:
+                child = _Command(name, None, None, {})
+                self.subs[name] = child
+
+            child.add(rest, entry, doc)
+            return
+
+        try:
+            child = self.subs[name]
+            child.entry = entry
+            child.doc = doc
+        except KeyError:
+            self.subs[name] = _Command(name, entry, doc, {})
+
+
+_known_commands = _Command("", None, None, {})
+_autodoc = {
+    "proj_flow.flow.configs.Configs": "Current configuration list.",
+    "proj_flow.api.env.Runtime": "Tools and print messages, while respecting ``--dry-run``, ``--silent`` and ``--verbose``.",
+}
+
+
+def command(*name: str):
+    def wrap(entry: callable):  # type: ignore
+        global _known_commands
+        _known_commands.add(list(name), entry, entry.__doc__)
+
+        doc = inspect.getdoc(entry) or ""
+        if doc:
+            doc += "\n\n"
+
+        for arg in _inspect.signature(entry):
+            help = ""
+            for meta in arg.metadata:
+                if isinstance(meta, Argument):
+                    help = meta.help
+                    if help:
+                        break
+
+            if not help:
+                full_name = f"{arg.type.__module__}.{arg.type.__name__}"
+                help = _autodoc.get(full_name, "")
+
+            doc += f":param {_inspect.type_name(arg.type)} {arg.name}: {help}\n"
+
+        entry.__doc__ = doc
+
+        return entry
+
+    return wrap
+
+
+def get_commands():
+    return _known_commands

proj_flow/api/completers.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.api.completers** defines :py:mod:`argcomplete` functions for
+``-C``, ``--step`` and ``-D``.
+"""
+
+import os
+from typing import Any, Dict, List, Union, cast
+
+import yaml
+
+from proj_flow import api
+
+
+def cd_completer(prefix, **kwargs):
+    target_dir = os.path.dirname(prefix)
+    incomplete_part = os.path.basename(prefix)
+    try:
+        names = os.listdir(target_dir or ".")
+    except Exception:
+        return  # empty iterator
+
+    for name in names:
+        if not name.startswith(incomplete_part):
+            continue
+        full = os.path.join(target_dir, name)
+        if not os.path.isdir(full):
+            continue
+
+        yield f"{full}{os.sep}"
+
+
+def step_completer(prefix: str, parser, **kwargs):
+    flow_cfg = cast(api.env.FlowConfig, parser.flow)
+
+    comma_sep = prefix.split(",")
+    start = ",".join(comma_sep[:-1])
+    if len(comma_sep) > 1:
+        start += ","
+
+    current = comma_sep[-1].lower()
+    for step in flow_cfg.steps:
+        name = cast(str, step.name)
+        if name.lower().startswith(current):
+            candidate = current + name[len(current) :]
+            yield start + candidate
+
+
+def _str_arg(arg: Union[bool, str]):
+    if isinstance(arg, bool):
+        return "ON" if arg else "OFF"
+    return str(arg)
+
+
+def matrix_completer(prefix: str, parser, **kwargs):
+    flow_cfg = cast(api.env.FlowConfig, parser.flow)
+
+    matrix_yml = os.path.join(flow_cfg.root, ".flow", "matrix.yml")
+    with open(matrix_yml, "r", encoding="UTF-8") as contents:
+        data: Dict[str, List[Any]] = yaml.load(contents, Loader=yaml.Loader).get(
+            "matrix", {}
+        )
+
+    comma_sep = prefix.split(",")
+    start = ",".join(comma_sep[:-1])
+    if len(comma_sep) > 1:
+        start += ","
+
+    current = comma_sep[-1].split("=", 1)
+
+    if len(current) == 1:
+        completions: List[str] = []
+        for key in data:
+            if key.startswith(current[0]):
+                completions.append(f"{start}{key}=")
+        if len(completions) != 1:
+            return completions
+
+        current = completions[0].split("=", 1)
+
+    try:
+        args = data[current[0]]
+    except KeyError:
+        return
+
+    completions: List[str] = []
+    for arg in map(_str_arg, args):
+        if arg.startswith(current[1]):
+            completions.append(f"{start}{current[0]}={arg}")
+
+    return completions

proj_flow/api/ctx.py

@@ -0,0 +1,238 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.api.ctx** provides tools for preparing the project template.
+"""
+
+import datetime
+import inspect
+import os
+from dataclasses import dataclass
+from typing import Callable, Dict, Iterable, List, Optional, Union
+
+from proj_flow.base import cmd
+
+package_root = os.path.dirname(os.path.dirname(__file__))
+template_dir = "template"
+
+
+StrOrBool = Union[str, bool]
+Values = Union[StrOrBool, List[str]]
+SettingsType = Dict[str, StrOrBool]
+
+
+@dataclass
+class Setting:
+    json_key: str
+    prompt: str = ""
+    value: Union[Values, Callable[[], Values]] = ""
+    fix: Optional[str] = None
+    force_fix: bool = False
+
+    def calc_value(self, previous: SettingsType):
+        if isinstance(self.value, Callable):
+            kwargs = {}
+
+            params = inspect.signature(self.value).parameters
+            if "settings" in params:
+                kwargs["settings"] = previous
+
+            return self.value(**kwargs)
+
+        return self.value
+
+
+def register_init_setting(*setting: Setting, is_hidden=False):
+    (hidden if is_hidden else defaults).extend(setting)
+
+
+def register_switch(key: str, prompt: str, enabled: bool):
+    switches.append(Setting(key, prompt, value=enabled))
+
+
+def register_internal(key: str, value: any):
+    internals[key] = value
+
+
+def _git_config(name: str):
+    def wrap():
+        proc = cmd.run("git", "config", name, capture_output=True)
+        if proc is None or proc.returncode != 0:
+            return None
+        return proc.stdout.strip()
+
+    return wrap
+
+
+def move_to_front(preferred: str, values: Iterable[str]):
+    result: List[str] = []
+
+    has_preferred = False
+    for value in values:
+        if value == preferred:
+            has_preferred = True
+        else:
+            result.append(value)
+
+    if has_preferred:
+        result.insert(0, preferred)
+
+    return result
+
+
+def _list_ext():
+    return move_to_front(".cpp", sorted(_fileext.keys()))
+
+
+def _as_mustache(basename: str):
+    name, ext = os.path.splitext(basename)
+    return ext == ".mustache" and name or None
+
+
+def _enum_licenses():
+    root = os.path.abspath(os.path.join(package_root, template_dir, "licenses"))
+    for _, dirnames, filenames in os.walk(root):
+        dirnames[:] = []
+        iter = filter(lambda x: x is not None, map(_as_mustache, filenames))
+        return move_to_front("MIT", iter)
+    return []
+
+
+def _filter(
+    src: Callable[[SettingsType], StrOrBool],
+    flt: Callable[[StrOrBool], StrOrBool],
+):
+    def impl(settings: SettingsType):
+        return flt(src(settings))
+
+    return impl
+
+
+def _get_nothing(_: SettingsType) -> StrOrBool:
+    return ""
+
+
+def _map(internal_key: str):
+    def impl(key: str):
+        mapped = internals.get(internal_key)
+        if not isinstance(mapped, dict):
+            return None
+        return mapped.get(key)
+
+    return impl
+
+
+def _get_key(key: str):
+    def impl(settings: SettingsType):
+        return settings.get(key, "")
+
+    return impl
+
+
+def _build_fixup(settings: SettingsType, fixup: str):
+    fixup_refs = fixup.split("{")
+    result = fixup_refs.pop(0)
+    for ref_expr in fixup_refs:
+        ref_text, verbose = ref_expr.split("}")
+        filter_path = ref_text.split("$")
+
+        ref = filter_path.pop(0)
+        code = _get_nothing if ref == "" else _get_key(ref)
+
+        for filter_name in filter_path:
+            flt = _filters.get(filter_name)
+            if flt is None:
+                if filter_name.startswith("map:"):
+                    internal_key = filter_name[4:]
+                    code = _filter(code, _map(internal_key))
+                continue
+            code = _filter(code, flt)
+
+        value = code(settings)
+
+        if result:
+            result += value
+        else:
+            result = value
+
+        if verbose:
+            result += verbose
+
+    return result
+
+
+def _fixed(fixup: str):
+    def wrap(settings: SettingsType):
+        return _build_fixup(settings, fixup)
+
+    return wrap
+
+
+internals = {}
+
+switches: List[Setting] = []
+
+defaults: List[Setting] = [
+    Setting(
+        "PROJECT.NAME",
+        "Project name",
+        lambda: os.path.basename(os.path.abspath("")) or "?project-name?",
+    ),
+    Setting("PROJECT.DESCRIPTION", "Project description"),
+    Setting(
+        "PROJECT.EMAIL",
+        "Valid email, e.g. for CODE_OF_CONDUCT",
+        _git_config("user.email"),
+    ),
+    Setting(
+        "COPY.YEAR",
+        "Year for copyright notices",
+        str(datetime.date.today().year),
+    ),
+    Setting(
+        "COPY.HOLDER",
+        "Holder of the copyright",
+        _git_config("user.name"),
+    ),
+    Setting("COPY.LICENSE", "License", _enum_licenses),
+    Setting(
+        "INCLUDE_PREFIX",
+        'Prefix for includes (as in #include "{PREFIX}/version.hpp")',
+        _fixed("{PROJECT.NAME}"),
+    ),
+    Setting(
+        "NAME_PREFIX",
+        "CMake variable name prefix",
+        _fixed("{PROJECT.NAME$safe$upper}"),
+    ),
+    Setting(
+        "NAMESPACE",
+        "C++ namespace for the project",
+        _fixed("{PROJECT.NAME$safe}"),
+    ),
+    Setting("EXT", "Extension for code files", _list_ext),
+    Setting("SRCDIR", "Directory for code files", "src"),
+    Setting(
+        "INCLUDEDIR",
+        "Directory for include files",
+        "include",
+        "{INCLUDEDIR}/{INCLUDE_PREFIX}",
+        force_fix=True,
+    ),
+]
+
+hidden: List[Setting] = [
+    Setting("EXT.cxx", fix="{EXT}"),
+    Setting("EXT.hxx", fix="{EXT.cxx$header}"),
+]
+
+_fileext = {".cc": ".hh", ".cxx": ".hxx", ".cpp": ".hpp"}
+
+
+_filters: Dict[str, Callable[[StrOrBool], StrOrBool]] = {
+    "safe": lambda value: value.replace("-", "_"),
+    "upper": lambda value: value.upper(),
+    "lower": lambda value: value.lower(),
+    "header": lambda cxx_ext: _fileext.get(cxx_ext, ".hpp"),
+}