proj-flow 0.8.1__py3-none-any.whl → 0.9.0__py3-none-any.whl

proj_flow/__init__.py

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

proj_flow/__main__.py

@@ -2,7 +2,7 @@
 # This code is licensed under MIT license (see LICENSE for details)
 
 """
-The **proj_flow.__main__** allows *C++ flow* to be called as Python component.
+The **proj_flow.__main__** allows *Project Flow* to be called as Python component.
 """
 
 from .flow.cli import main

proj_flow/api/__init__.py

@@ -5,6 +5,15 @@
 The **proj_flow.api** contains public APIs, usable in third-party plugins.
 """
 
-from . import arg, completers, ctx, env, init, makefile, step
+from . import arg, completers, ctx, env, init, makefile, release, step
 
-__all__ = ["arg", "completers", "ctx", "env", "init", "makefile", "step"]
+__all__ = [
+    "arg",
+    "completers",
+    "ctx",
+    "env",
+    "init",
+    "makefile",
+    "release",
+    "step",
+]

proj_flow/api/arg.py

@@ -24,7 +24,7 @@ class Argument:
     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
+    completer: typing.Optional[_inspect.Function] = None
 
     def visit(self, parser: argparse.ArgumentParser, name: str):
         kwargs = {}
@@ -68,11 +68,16 @@ class FlagArgument(Argument):
 @dataclass
 class _Command:
     name: str
-    entry: typing.Optional[callable]  # type: ignore
+    entry: typing.Optional[_inspect.Function]
     doc: typing.Optional[str]
     subs: typing.Dict[str, "_Command"]
 
-    def add(self, names: typing.List[str], entry: callable, doc: typing.Optional[str]):  # type: ignore
+    def add(
+        self,
+        names: typing.List[str],
+        entry: _inspect.Function,
+        doc: typing.Optional[str],
+    ):
         name = names[0]
         rest = names[1:]
         if len(rest):
@@ -97,15 +102,18 @@ _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``.",
+    "proj_flow.cli.argument.Command": "The Command object attached to this @command function.",
 }
 
 
 def command(*name: str):
-    def wrap(entry: callable):  # type: ignore
+    def wrap(function: object):
+        entry = typing.cast(_inspect.Function, function)
         global _known_commands
-        _known_commands.add(list(name), entry, entry.__doc__)
+        orig_doc = inspect.getdoc(entry)
+        _known_commands.add(list(name), entry, orig_doc)
 
-        doc = inspect.getdoc(entry) or ""
+        doc = orig_doc or ""
         if doc:
             doc += "\n\n"
 

proj_flow/api/env.py

@@ -23,9 +23,7 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Callable, Dict, List, Optional, Union, cast
 
-import yaml
-
-from proj_flow.base import uname
+from proj_flow.base import plugins, uname
 from proj_flow.base.plugins import load_module_plugins
 
 platform = uname.uname()[0]
@@ -132,47 +130,29 @@ class FlowConfig:
             self.root = cfg.root
         else:
             self.root = os.path.abspath(root)
-            try:
-                with open(
-                    os.path.join(self.root, ".flow", "config.yml"),
-                    encoding="UTF-8",
-                ) as f:
-                    self._cfg = yaml.load(f, Loader=yaml.Loader)
-            except FileNotFoundError:
-                self._cfg = {}
+            self._cfg = plugins.load_data(
+                os.path.join(self.root, ".flow", "config.json")
+            )
 
             self._propagate_compilers()
-            self._load_plugins()
+            self._load_extensions()
 
     def _propagate_compilers(self):
         global _flow_config_default_compiler
         _flow_config_default_compiler = self.compiler_os_default
 
-    def _load_plugins(self):
-        std_plugins = importlib.import_module("proj_flow.plugins")
-        load_module_plugins(std_plugins)
+    def _load_extensions(self):
+        extensions = cast(List[str], self._cfg.get("extensions", []))
+        extensions.insert(0, "proj_flow.minimal")
 
-        local_plugins = os.path.abspath(os.path.join(self.root, ".flow", "extensions"))
-        if not os.path.exists(local_plugins):
-            return
-
-        if not os.path.isdir(local_plugins):
-            plugins = importlib.import_module(local_plugins)
-            load_module_plugins(plugins, can_fail=True)
-            return
-
-        sys.path.insert(0, local_plugins)
-
-        for root, dirnames, _ in os.walk(local_plugins):
-            for dirname in dirnames:
-                init = os.path.join(root, dirname, "__init__.py")
-                if not os.path.isfile(init):
-                    continue
-                plugins = importlib.import_module(dirname)
-                load_module_plugins(plugins, can_fail=True)
-            dirnames[:] = []
+        local_extensions = os.path.abspath(
+            os.path.join(self.root, ".flow", "extensions")
+        )
+        if os.path.isdir(local_extensions):
+            sys.path.insert(0, local_extensions)
 
-        sys.path.pop(0)
+        for extension in extensions:
+            importlib.import_module(extension)
 
     @property
     def entry(self) -> Dict[str, dict]:

proj_flow/api/release.py

@@ -0,0 +1,99 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.api.release** provides :class:`ProjectSuite` extension point.
+"""
+
+import os
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import NamedTuple, Optional, Union
+
+from proj_flow.api import env
+from proj_flow.base import registry
+
+
+class Arg(NamedTuple):
+    value: str
+    offset: int
+
+
+NO_ARG = Arg("", -1)
+
+
+class Decl(NamedTuple):
+    name: str
+    value: str
+    offset: int
+
+    def __str__(self):
+        return self.value
+
+    def asArg(self):
+        return Arg(self.value, self.offset)
+
+
+class Version(NamedTuple):
+    core: Arg
+    stability: Arg
+
+    def __str__(self):
+        return f"{self.core.value}{self.stability.value}"
+
+
+@dataclass
+class Project:
+    package_root: str
+    version: Version
+
+    @property
+    def archive_name(self):
+        return f"{self.package_root}-{self.version}"
+
+    @property
+    def tag_name(self):
+        return f"v{self.version}"
+
+
+class ProjectSuite(ABC):
+    @abstractmethod
+    def get_project(self, rt: env.Runtime) -> Optional[Project]: ...
+
+    def set_version(self, rt: env.Runtime, version: str):
+        core = re.split(r"([0-9]+\.[0-9]+\.[0-9]+)", version, maxsplit=1)[1]
+        stability = version[len(core) :]
+
+        project = self.get_project(rt)
+        if project:
+            self.patch_project(rt, project.version.core, core)
+
+        project = self.get_project(rt)
+        if project:
+            version_pos = project.version
+
+            if len(stability):
+                self.patch_project(rt, version_pos.stability, stability)
+            elif len(version_pos.stability.value):
+                self.patch_project(rt, version_pos.stability, "")
+
+    @abstractmethod
+    def get_version_file_path(self, rt: env.Runtime) -> Optional[str]: ...
+
+    def patch_project(self, rt: env.Runtime, pos: Arg, newValue: str):
+        path = self.get_version_file_path(rt)
+
+        if not path or not os.path.isfile(path):
+            return
+
+        with open(path, "r", encoding="UTF-8") as input:
+            text = input.read()
+
+        patched = text[: pos.offset] + newValue + text[pos.offset + len(pos.value) :]
+
+        with open(path, "w", encoding="UTF-8") as input:
+            input.write(patched)
+
+
+project_suites = registry.Registry[ProjectSuite]("ProjectSuite")

proj_flow/api/step.py

@@ -5,10 +5,12 @@
 The **proj_flow.api.step** exposes APIs used by run extensions.
 """
 
+import os
 from abc import ABC, abstractmethod
 from typing import List, cast
 
 from proj_flow.api.env import Config, Runtime
+from proj_flow.base import inspect as _inspect
 from proj_flow.base import matrix
 
 
@@ -77,7 +79,8 @@ def _register_step(step: Step):
 
     name = step.name
     if name in [step.name for step in __steps]:
-        raise NameError(f"Step {name} already registered")
+        if "READTHEDOCS" not in os.environ:
+            raise NameError(f"Step {name} already registered")
 
     __steps.append(step)
 
@@ -115,7 +118,7 @@ def _name_list(label: str, names: List[str], template="`{}`") -> str:
     return f"\n:{label}: {prefix}{em[-1]}"
 
 
-def _make_private(f: callable):
+def _make_private(f: _inspect.Function):
     if f.__doc__:
         f.__doc__ += "\n\n:meta private:\n"
     else:
@@ -171,3 +174,10 @@ def register(cls=None):
         return impl
 
     return impl(cls)
+
+
+def verbose_info():
+    for step in __steps:
+        print(
+            f'-- Step: adding "{step.name}" from `{step.__module__}.{step.__class__.__name__}`'
+        )

proj_flow/base/__init__.py

@@ -6,6 +6,6 @@ The **proj_flow.base** contains low-level tools for higher-level parts of the
 library.
 """
 
-from . import cmd, matrix, plugins, uname
+from . import cmd, matrix, plugins, registry, uname
 
-__all__ = ["cmd", "matrix", "plugins", "uname"]
+__all__ = ["cmd", "matrix", "plugins", "registry", "uname"]

proj_flow/base/inspect.py

@@ -11,6 +11,14 @@ import typing
 from dataclasses import dataclass
 
 
+class Function(typing.Protocol):
+    """Replacement for :py:func:`callable` as universal argument type."""
+
+    __name__: str
+
+    def __call__(self, **kwarg) -> typing.Any: ...
+
+
 @dataclass
 class Argument:
     """Extracted argument type"""
@@ -27,7 +35,7 @@ class Argument:
     metadata: typing.List[typing.Any]
 
 
-def signature(call: callable) -> typing.Generator[Argument, None, None]:  # type: ignore
+def signature(call: Function) -> typing.Generator[Argument, None, None]:
     """
     Extract the arguments from the function and produces list of
     :class:`Argument` objects.
@@ -56,29 +64,6 @@ def signature(call: callable) -> typing.Generator[Argument, None, None]:  # type
         yield Argument(name=param_name, type=origin, metadata=metadata)
 
 
-def _union_args(t):
-    origin = typing.get_origin(t)
-
-    if origin is typing.Union:
-        args = typing.get_args(t)
-        for arg in args:
-            for candidate in _union_args(arg):
-                yield candidate
-        return
-
-    yield t
-
-
-def _unique_union_arg_names(t):
-    seen: typing.Set[str] = set()
-    for arg in _union_args(t):
-        name = type_name(arg)
-        if name in seen:
-            continue
-        seen.add(name)
-        yield name
-
-
 def type_name(t: type) -> str:
     """
     Converts a type to simplified string representing that type.
@@ -96,7 +81,12 @@ def type_name(t: type) -> str:
     origin = typing.get_origin(t)
 
     if origin is typing.Union:
-        return "|".join(_unique_union_arg_names(t))
+        args = typing.get_args(t)
+        names: typing.List[str] = []
+        for arg in args:
+            name = type_name(arg)
+            names.append(name)
+        return " | ".join(names)
 
     if origin is None:
         return "?"
@@ -112,22 +102,3 @@ def type_name(t: type) -> str:
         return f"{origin.__name__}[{arg_list}]"
 
     return typing.cast(str, origin.__name__)
-
-
-def union_arg(t: type) -> typing.Generator[typing.Any, None, None]:
-    """
-    Extract the arguments from :py:class:`typing.Union`. In case some of the
-    generic argument are unions themsleves, this function will flatten
-    the resulting list of types.
-
-    :param t: Type to ananlyze.
-    :returns: List of the argument, if the argument is a Union.
-    """
-
-    seen: typing.Set[str] = set()
-    for arg in _union_args(t):
-        name = type_name(arg)
-        if name in seen:
-            continue
-        seen.add(name)
-        yield arg

proj_flow/base/plugins.py

@@ -6,9 +6,48 @@ The **proj_flow.base.plugins** provide the plugin enumeration helpers.
 """
 
 import importlib
+import json
 import os
 from types import ModuleType
-from typing import Optional
+from typing import Optional, cast
+
+import yaml
+
+
+def load_yaml(filename: str):
+    with open(filename) as src:
+        return cast(dict, yaml.load(src, Loader=yaml.Loader))
+
+
+def load_json(filename: str):
+    with open(filename) as src:
+        return cast(dict, json.load(src))
+
+
+LOADERS = {
+    ".json": load_json,
+    ".yml": load_yaml,
+    ".yaml": load_yaml,
+}
+
+
+def load_data(filename: str):
+    prefix, ext = os.path.splitext(filename)
+    loader = LOADERS.get(ext.lower())
+    if loader:
+        try:
+            return loader(filename)
+        except Exception:
+            pass
+
+    for new_ext, loader in LOADERS.items():
+        new_filename = prefix + new_ext
+        try:
+            return loader(new_filename)
+        except Exception:
+            pass
+
+    return {}
 
 
 def _load_plugins(directory: str, package: Optional[str], can_fail=False):
@@ -40,5 +79,5 @@ def load_module_plugins(mod: ModuleType, can_fail=False):
     spec = mod.__spec__
     if not spec:
         return
-    for location in spec.submodule_search_locations:
+    for location in spec.submodule_search_locations:  # type: ignore
         _load_plugins(location, spec.name, can_fail)

proj_flow/base/registry.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2024 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.base.registry**
+"""
+
+import typing
+
+T = typing.TypeVar("T")
+K = typing.TypeVar("K")
+
+
+class Registry(typing.Generic[T]):
+    """
+    Provides simple registry with the decorator attached to it, which
+    implements extension point for plugin system. An extension point is a
+    value created from this generic, with extendable interface type as
+    the generic argument.
+
+    Known decorators
+    ................
+
+    :data:`proj_flow.api.release.project_suites`
+        :Argument: :class:`ProjectSuite <proj_flow.api.release.ProjectSuite>`
+        :Used by: :func:`src.proj_flow.log.release.add_release`
+
+        Project version reader and updater, package file name builder.
+
+    :data:`proj_flow.log.release.version_updaters`
+        :Argument: :class:`VersionUpdaters <proj_flow.api.release.VersionUpdaters>`
+        :Used by: :func:`src.proj_flow.log.release.add_release`
+
+        Additional version updaters, for instance, path to schema reference on
+        GitHub.
+
+    :data:`proj_flow.log.rich_text.api.changelog_generators`
+        :Argument: :class:`ChangelogGenerator <proj_flow.log.rich_text.api.ChangelogGenerator>`
+        :Used by: :func:`src.proj_flow.ext.github.cli.release`
+
+        Changelog note generator used in CHANGELOG file. Not to confuse with
+        generator, which may be used internally by Hosting.add_release.
+
+    Example
+    .......
+
+    .. code-block:: python
+
+        class Animal(ABC)
+            @abstractmethod
+            def speak(self): ...
+
+        animals = Registry[Animal]("Animal")
+
+        def speak_all():
+            for animal in animals.get():
+                animal.speak()
+
+        @animals.add
+        class Dog(Animal):
+            def speak(self):
+                print("woof!")
+    """
+
+    name: str
+    container: typing.List[T]
+
+    def __init__(self, name: str):
+        self.name = name
+        self.container = []
+        _debug_copies.append(self)
+
+    def add(self, cls: typing.Type[T]):
+        obj: T = cls()
+        self.container.append(obj)
+        return cls
+
+    def get(self):
+        return self.container
+
+    def find(
+        self, filter: typing.Callable[[T], K]
+    ) -> typing.Tuple[typing.Optional[T], typing.Optional[K]]:
+        for item in self.container:
+            candidate = filter(item)
+            if candidate is not None:
+                return item, candidate
+        return None, None
+
+    def first(self) -> typing.Optional[T]:
+        try:
+            return next(self.container.__iter__())
+        except StopIteration:
+            return None
+
+
+_debug_copies: typing.List[Registry] = []
+
+
+def verbose_info():
+    for registry in _debug_copies:
+        for item in registry.container:
+            print(
+                f"-- {registry.name}: adding `{item.__module__}.{item.__class__.__name__}`"
+            )

proj_flow/cli/__init__.py

@@ -0,0 +1,55 @@
+# PYTHON_ARGCOMPLETE_OK
+
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.cli** provides command-line entry for the *Project Flow*.
+"""
+
+import argparse
+import os
+import sys
+from pprint import pprint
+from typing import Dict, Optional, Tuple
+
+from proj_flow.api import arg, env
+from proj_flow.cli import argument, finder
+from proj_flow.flow import steps
+
+__all__ = ["argument", "finder", "main"]
+
+
+def main():
+    """Entry point for ``proj-flow`` tool."""
+    try:
+        __main()
+    except KeyboardInterrupt:
+        sys.exit(1)
+
+
+def _change_dir():
+    root = argparse.ArgumentParser(
+        prog="proj-flow",
+        usage="proj-flow [-h] [--version] [-C [dir]] {command} ...",
+        add_help=False,
+    )
+    root.add_argument("-C", dest="cd", nargs="?")
+
+    args, _ = root.parse_known_args()
+    if args.cd:
+        os.chdir(args.cd)
+
+
+def __main():
+    _change_dir()
+
+    flow_cfg = env.FlowConfig(root=finder.autocomplete.find_project())
+    steps.clean_aliases(flow_cfg)
+
+    parser = argument.build_argparser(flow_cfg)
+    finder.autocomplete(parser)
+    args = parser.parse_args()
+    argument.expand_shortcuts(parser, args)
+
+    raise SystemExit(parser.find_and_run_command(args))