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

proj_flow/ext/python/rtdocs.py

@@ -0,0 +1,238 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.ext.python.steps.rtdocs** defines RTDocs step, which uses
+.readthedocs.yaml to build the HTML documentation.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, List, Optional, cast
+
+from proj_flow.api import env, step
+
+
+@step.register
+class RTDocs:
+    name = "RTD"
+
+    def platform_dependencies(self):
+        return ["python -m PyYAML"]
+
+    def is_active(self, config: env.Config, rt: env.Runtime) -> bool:
+        return os.path.isfile(os.path.join(rt.root, ".readthedocs.yaml"))
+
+    def run(self, config: env.Config, rt: env.Runtime) -> int:
+        import venv
+
+        import yaml
+
+        with open(os.path.join(rt.root, ".readthedocs.yaml")) as rtd_yaml:
+            data = yaml.load(rtd_yaml, Loader=yaml.Loader)
+
+            formats = ["html"]
+
+            build_jobs = cast(
+                Dict[str, List[str]], data.get("build", {}).get("jobs", {})
+            )
+
+            sphinx_configuration = cast(
+                Optional[str], data.get("sphinx", {}).get("configuration")
+            )
+
+            python_install = cast(
+                List[Dict[str, Any]], data.get("python", {}).get("install", [])
+            )
+
+        builder: Optional[Builder] = None
+
+        if sphinx_configuration:
+            sphinx_configuration = os.path.join(rt.root, sphinx_configuration)
+            builder = Sphinx(sphinx_configuration)
+
+        READTHEDOCS_OUTPUT = (
+            builder.READTHEDOCS_OUTPUT
+            if builder is not None
+            else os.path.join(rt.root, "docs/build")
+        )
+        os.environ["READTHEDOCS_OUTPUT"] = READTHEDOCS_OUTPUT
+        os.environ["READTHEDOCS"] = "True"
+
+        jobs: Dict[str, Callable[[], int]] = {
+            "create_environment": lambda: _activate_virtual_env(
+                venv, os.path.dirname(READTHEDOCS_OUTPUT)
+            ),
+        }
+        if len(python_install):
+            jobs["install"] = lambda: _install(python_install)
+
+        if builder:
+            for format in formats:
+                jobs[f"build/{format}"] = builder.wrap(format)
+
+        for name in build_jobs:
+            if name != "build":
+                jobs[name] = lambda: _script(build_jobs[name])
+                continue
+
+            build_jobs_build = cast(Dict[str, List[str]], build_jobs["build"])
+            for format in formats:
+                if format not in build_jobs_build:
+                    continue
+                jobs[f"build/{format}"] = lambda: _script(build_jobs_build[name])
+
+        for job in _job_listing:
+            try:
+                impl = jobs[job]
+            except KeyError:
+                continue
+            print(f"-- {job}")
+            result = impl()
+            if result:
+                return 1
+        return 0
+
+
+class Builder(ABC):
+    @property
+    @abstractmethod
+    def READTHEDOCS_OUTPUT(self) -> str: ...
+
+    @abstractmethod
+    def build(self, target: str) -> int: ...
+
+    def wrap(self, target: str) -> Callable[[], int]:
+        return lambda: self.build(target)
+
+
+class Sphinx(Builder):
+    READTHEDOCS_OUTPUT: str = ""
+
+    def __init__(self, config: str):
+        self.config = config
+        self.source = os.path.dirname(config)
+        self.READTHEDOCS_OUTPUT = os.path.join(os.path.dirname(self.source), "build")
+
+    def build(self, target: str):
+        builder = "latex" if target == "pdf" else target
+        return subprocess.run(
+            ["sphinx-build", "-M", builder, self.source, self.READTHEDOCS_OUTPUT],
+            shell=False,
+        ).returncode
+
+
+PYTHON_EXECUTABLE = sys.executable
+
+
+def _python(
+    *args: str,
+    module: Optional[str] = None,
+    capture_output: bool = True,
+) -> subprocess.CompletedProcess:
+    if module is not None:
+        return subprocess.run(
+            [PYTHON_EXECUTABLE, "-m", module, *args],
+            shell=False,
+            capture_output=capture_output,
+        )
+    return subprocess.run(
+        [PYTHON_EXECUTABLE, *args], shell=False, capture_output=capture_output
+    )
+
+
+def _pip(*args: str, capture_output: bool = False):
+    return _python(*args, module="pip", capture_output=capture_output)
+
+
+_build_targets = [
+    "html",
+    "htmlzip",
+    "pdf",
+    "epub",
+]
+
+_job_listing = [
+    # "post_checkout",
+    # "pre_system_dependencies",
+    # "post_system_dependencies",
+    "pre_create_environment",
+    "create_environment",
+    "post_create_environment",
+    "pre_install",
+    "install",
+    "post_install",
+    "pre_build",
+    *(f"build/{tgt}" for tgt in _build_targets),
+    "post_build",
+]
+
+
+@contextmanager
+def _cd(path: str):
+    prev = os.getcwd()
+    os.chdir(path)
+    try:
+        yield
+    finally:
+        os.chdir(prev)
+
+
+def _get_venv_path(root: str):
+    bindir = os.path.join(".venv", "bin")
+    scripts = os.path.join(".venv", "Scripts")
+
+    if os.path.isdir(os.path.join(root, bindir)):
+        return bindir
+
+    if os.path.isdir(os.path.join(root, scripts)):
+        return scripts
+
+    return None
+
+
+def _activate_virtual_env(venv, root: str):
+    global PYTHON_EXECUTABLE
+
+    with _cd(root):
+        exec_ext = ".exe" if sys.platform == "win32" else ""
+        python_exec = f"python{exec_ext}"
+        bindir = _get_venv_path(root)
+        has_venv = bindir is not None and os.path.isfile(
+            os.path.join(bindir, python_exec)
+        )
+
+        if not has_venv:
+            venv.create(".venv", with_pip=True, upgrade_deps=True)
+            bindir = _get_venv_path(root)
+
+        if bindir:
+            PATH = f"{os.path.abspath(bindir)}{os.pathsep}{os.environ['PATH']}"
+            os.environ["PATH"] = PATH
+        PYTHON_EXECUTABLE = shutil.which("python") or sys.executable
+    return 0
+
+
+def _install(deps: List[Dict[str, Any]]):
+    for dep in deps:
+        try:
+            requirements = dep["requirements"]
+        except KeyError:
+            continue
+
+        result = _pip("install", "-q", "-r", requirements).returncode
+        if result:
+            return result
+    return 0
+
+
+def _script(calls: List[str]):
+    for call in calls:
+        result = subprocess.run(call, shell=True).returncode
+        if result:
+            return result
+    return 0

proj_flow/ext/python/steps.py

@@ -0,0 +1,71 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.ext.python.steps** defines steps for building, installing and
+documenting.
+"""
+
+import importlib
+import os
+
+from proj_flow.api import env, release, step
+
+from . import rtdocs
+
+
+@step.register
+class Install:
+    name = "Install"
+
+    def platform_dependencies(self):
+        return ["python -m pip"]
+
+    def run(self, config: env.Config, rt: env.Runtime) -> int:
+        return rt.cmd("python", "-m", "pip", "install", rt.root)
+
+
+@step.register
+class Build:
+    name = "Build"
+
+    def platform_dependencies(self):
+        return ["python -m build"]
+
+    def run(self, config: env.Config, rt: env.Runtime) -> int:
+        build_main = importlib.import_module("build.__main__")
+        build_main.main([], "proj-flow build")
+        return 0
+
+
+@step.register
+class CheckTwine:
+    name = "Check Twine"
+
+    runs_after = ["Build"]
+
+    def platform_dependencies(self):
+        return ["twine"]
+
+    def run(self, config: env.Config, rt: env.Runtime) -> int:
+        filenames = []
+        for root, dirnames, filenames in os.walk("dist"):
+            dirnames[:] = []
+
+        _, project = release.project_suites.find(lambda suite: suite.get_project(rt))
+        archive_name = project and project.archive_name
+        if archive_name:
+            dot_suffix = f"{archive_name}."
+            dash_suffix = f"{archive_name}-"
+            filenames = [
+                filename
+                for filename in filenames
+                if filename.startswith(dot_suffix) or filename.startswith(dash_suffix)
+            ]
+
+        if len(filenames) == 0:
+            return 0
+
+        return rt.cmd(
+            "twine", "check", *(os.path.join(root, filename) for filename in filenames)
+        )

proj_flow/ext/python/version.py

@@ -0,0 +1,98 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.ext.python.steps** defines steps for building, installing and
+documenting.
+"""
+
+import os
+import re
+from typing import NamedTuple, Optional
+
+import toml
+
+from proj_flow.api import env, release
+
+
+class QuickProjectInfo(NamedTuple):
+    name: Optional[str] = None
+    path: Optional[str] = None
+    pattern: Optional[str] = None
+
+
+@release.project_suites.add
+class ProjectSuite(release.ProjectSuite):
+    def get_project(self, rt: env.Runtime) -> Optional[release.Project]:
+        name, path, pattern = self._pyproject_hatch(rt)
+        if name is None or path is None:
+            return None
+
+        try:
+            with open(os.path.join(rt.root, path), encoding="UTF-8") as infile:
+                text = infile.read()
+        except FileNotFoundError:
+            return None
+
+        if pattern is not None:
+            candidate = self._check(text, pattern)
+            return release.Project(name, candidate) if candidate else None
+
+        for varname in ["__version__", "VERSION"]:
+            for end in ['"', "'"]:
+                pattern = rf"{varname}\s*=\s*{end}v?(?P<version>[^{end}]+){end}"
+                candidate = self._check(text, pattern)
+                if candidate:
+                    return release.Project(name, candidate)
+
+        return None
+
+    def _check(self, text: str, pattern: str):
+        m = re.search(f"^{pattern}", text, flags=re.MULTILINE)
+        if not m:
+            return None
+        version, start = m.group("version"), m.start("version")
+        core = re.split(r"([0-9]+\.[0-9]+\.[0-9]+)", version, maxsplit=1)[1]
+        stability = version[len(core) :]
+
+        return release.Version(
+            release.Arg(core, start), release.Arg(stability, start + len(core))
+        )
+
+    def get_version_file_path(self, rt: env.Runtime) -> Optional[str]:
+        _, path, _ = self._pyproject_hatch(rt)
+        return path
+
+    def _pyproject_hatch(self, rt: env.Runtime):
+        pyproject_path = os.path.join(rt.root, "pyproject.toml")
+        try:
+            data = toml.load(pyproject_path)
+            project = data.get("project", {})
+            hatch = data.get("tool", {}).get("hatch", {})
+            wheels = (
+                hatch.get("build", {})
+                .get("targets", {})
+                .get("wheel", {})
+                .get("packages", [])
+            )
+
+            name = project.get("name")
+            if len(wheels) > 0:
+                first_wheel = wheels[0].split("/")[-1]
+                if first_wheel:
+                    name = first_wheel
+
+            dynamic = project.get("dynamic", [])
+            if "version" in dynamic:
+                version_dict = hatch.get("version", {})
+                return QuickProjectInfo(
+                    name=name,
+                    path=version_dict.get("path"),
+                    pattern=version_dict.get("pattern"),
+                )
+            return QuickProjectInfo(
+                name=name,
+                path="pyproject.toml",
+            )
+        except FileNotFoundError:
+            return QuickProjectInfo()

proj_flow/ext/re_structured_changelist.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2025 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.ext.re_structured_text** .
+"""
+
+from proj_flow.log.rich_text.api import changelog_generators
+from proj_flow.log.rich_text.re_structured_text import ChangelogGenerator
+
+
+@changelog_generators.add
+class Plugin(ChangelogGenerator):
+    pass

proj_flow/flow/__init__.py

@@ -2,10 +2,10 @@
 # This code is licensed under MIT license (see LICENSE for details)
 
 """
-The **proj_flow.flow** contains the inner workings of various *C++ flow*
+The **proj_flow.flow** contains the inner workings of various *Project Flow*
 components.
 """
 
-from . import cli, configs, dependency, init, interact, layer, steps
+from . import configs, dependency, init, interact, layer, steps
 
-__all__ = ["cli", "configs", "dependency", "init", "interact", "layer", "steps"]
+__all__ = ["configs", "dependency", "init", "interact", "layer", "steps"]

proj_flow/flow/configs.py

@@ -17,7 +17,9 @@ from proj_flow.base import matrix
 
 
 def _compiler_inner(
-    value: str, used_compilers: Dict[str, List[List[str]]], config_names: Dict[str, List[str]]
+    value: str,
+    used_compilers: Dict[str, List[List[str]]],
+    config_names: Dict[str, List[str]],
 ):
     compiler, names = matrix.find_compiler(value, config_names)
     if compiler not in used_compilers:
@@ -26,7 +28,9 @@ def _compiler_inner(
     return compiler
 
 
-def _compiler(used_compilers: Dict[str, List[List[str]]], config_names: Dict[str, List[str]]):
+def _compiler(
+    used_compilers: Dict[str, List[List[str]]], config_names: Dict[str, List[str]]
+):
     return lambda value: _compiler_inner(value, used_compilers, config_names)
 
 
@@ -43,12 +47,15 @@ _TRUE = {"true", "on", "yes", "1"}
 _boolean_sanitizer = _boolean("with-sanitizer")
 
 
-def _types(used_compilers: Dict[str, List[List[str]]], config_names: Dict[str, List[str]]):
+def _types(
+    used_compilers: Dict[str, List[List[str]]], config_names: Dict[str, List[str]]
+):
     return {
         "compiler": _compiler(used_compilers, config_names),
         "sanitizer": _boolean_sanitizer,
     }
 
+
 def _config(config: List[str], only_host: bool, types: Dict[str, Callable[[str], Any]]):
     args = {}
     for arg in config:
@@ -112,10 +119,15 @@ def _load_flow_data(rt: env.Runtime):
 class Configs:
     usable: List[env.Config] = []
 
-    def __init__(self, rt: env.Runtime, args: argparse.Namespace):
-        super()
+    def __init__(
+        self, rt: env.Runtime, args: argparse.Namespace, expand_compilers=True
+    ):
         configs, keys = _load_flow_data(rt)
 
+        if len(configs) == 0 and len(keys) == 0:
+            self.usable = [env.Config({}, keys)]
+            return
+
         used_compilers: Dict[str, List[List[str]]] = {}
 
         types = _types(used_compilers=used_compilers, config_names=rt.compiler_names)
@@ -140,6 +152,10 @@ class Configs:
             or not matrix.matches_any(config, postproc_exclude)
         ]
 
+        if not expand_compilers:
+            self.usable = [env.Config(conf, keys) for conf in usable]
+            return
+
         self.usable = []
         for conf in usable:
             try:

proj_flow/flow/dependency.py

@@ -10,7 +10,7 @@ import sys
 from dataclasses import dataclass
 from enum import Enum
 from importlib.metadata import version as package_version
-from typing import Callable, List, Set, Tuple
+from typing import Callable, List, Set, Tuple, cast
 
 from proj_flow.base import cmd
 
@@ -27,7 +27,7 @@ def _ver(ver: str) -> Version:
     chunks = [int(v.strip()) for v in ver.split(".")]
     while len(chunks) < 3:
         chunks.append(0)
-    return (*chunks[:3],)
+    return cast(Tuple[int, int, int], (*chunks[:3],))
 
 
 @dataclass
@@ -121,8 +121,8 @@ def verify(deps: List[Dependency]):
     for pkg in (dep for dep in uniq if dep.kind == DepKind.PYTHON_PKG):
         try:
             version = package_version(pkg.name)
-        except:
-            errors.add(f"{pkg.name}: Python package is missing")
+        except Exception as ex:
+            errors.add(f"{pkg.name}: Python package is missing: {ex}")
             continue
         msg = pkg.match_version(version)
         if msg is not None:
@@ -133,7 +133,9 @@ def verify(deps: List[Dependency]):
             errors.add(f"{app.name}: tool is missing")
             continue
         proc = cmd.run(app.name, "--version", capture_output=True)
-        if proc.returncode:
+        if not proc:
+            version = None
+        elif proc.returncode:
             if proc.stderr:
                 print(proc.stderr.rstrip(), file=sys.stderr)
             version = None
@@ -146,7 +148,7 @@ def verify(deps: List[Dependency]):
                 f"{app.name}: could not read version for `{app.version_expression}`"
             )
             continue
-        msg = app.match_version(version)
+        msg = version and app.match_version(version)
         if msg is not None:
             errors.add(msg)
 

proj_flow/flow/steps.py

@@ -6,15 +6,10 @@ The **proj_flow.flow.steps** allows loading both predefined and project-specific
 steps.
 """
 
-import importlib
-import os
-import sys
 from dataclasses import dataclass
-from types import ModuleType
-from typing import List, Optional, Union, cast
+from typing import List, cast
 
 from proj_flow.api import env, step
-from proj_flow.base.plugins import load_module_plugins
 
 
 @dataclass
@@ -43,6 +38,7 @@ def _sort_steps():
                 if successor.name != name:
                     continue
                 successor.runs_after.append(plugin.name)
+                break
 
     for plugin in unsorted:
         runs_after: List[str] = []
@@ -71,12 +67,14 @@ def _sort_steps():
 
 
 def clean_aliases(cfg: env.FlowConfig):
+    cfg_steps = _sort_steps()
+    cfg.steps = cfg_steps
+
     entries = cfg.entry
     if not entries:
         return
 
-    valid_steps = _sort_steps()
-    step_names = {step.name for step in valid_steps}
+    step_names = {step.name for step in cfg_steps}
 
     keys_to_remove: List[str] = []
     for key in entries:
@@ -100,5 +98,4 @@ def clean_aliases(cfg: env.FlowConfig):
     for key in keys_to_remove:
         del entries[key]
 
-    cfg.steps = valid_steps
     cfg.aliases = [env.RunAlias.from_json(key, entries[key]) for key in entries]

proj_flow/log/__init__.py

@@ -5,6 +5,14 @@
 The **proj_flow.log** defines tools for generating various changelog views.
 """
 
-from . import commit, fmt, hosting, msg, release, rich_text
+from . import commit, error, fmt, hosting, msg, release, rich_text
 
-__all__ = ["commit", "fmt", "hosting", "msg", "release", "rich_text"]
+__all__ = [
+    "commit",
+    "error",
+    "fmt",
+    "hosting",
+    "msg",
+    "release",
+    "rich_text",
+]

proj_flow/log/commit.py

@@ -16,6 +16,7 @@ from enum import Enum
 from typing import Dict, List, NamedTuple, Optional, Tuple
 
 from proj_flow.api import env
+from proj_flow.base import registry
 
 COMMIT_SEP = "--{}".format(
     "".join(secrets.choice(string.ascii_letters + string.digits) for i in range(20))
@@ -227,8 +228,12 @@ class Hosting(ABC):
         ...
 
     @abstractmethod
-    def draft_a_release(
-        self, log: ChangeLog, setup: "LogSetup", git: "Git"
+    def add_release(
+        self,
+        log: ChangeLog,
+        setup: "LogSetup",
+        git: "Git",
+        draft: bool,
     ) -> ReleaseInfo:
         """
         Publish a release for current setup, putting the log into release
@@ -258,8 +263,8 @@ class NoHosting(Hosting):
     def reference_link(self, ref: str) -> Optional[str]:
         return None
 
-    def draft_a_release(
-        self, log: ChangeLog, setup: "LogSetup", git: "Git"
+    def add_release(
+        self, log: ChangeLog, setup: "LogSetup", git: "Git", draft: bool
     ) -> ReleaseInfo:
         return ReleaseInfo(draft_url=None)
 
@@ -461,3 +466,13 @@ class Git:
 
     def push_with_refs(self, remote: str, branch: str):
         return self.cmd("push", remote, branch, "--follow-tags", "--force-with-lease")
+
+
+class HostingFactory(ABC):
+    @abstractmethod
+    def from_repo(
+        self, git: Git, remote: Optional[str] = None
+    ) -> Optional[Hosting]: ...
+
+
+hosting_factories = registry.Registry[HostingFactory]("HostingFactory")

proj_flow/log/error.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2024 Marcin Zdun
+# This code is licensed under MIT license (see LICENSE for details)
+
+"""
+The **proj_flow.log.error** declares a number of exceptions, which can be
+raised during the changelog operations.
+"""
+
+
+class ReleaseError(Exception):
+    def __init__(self, message: str):
+        super().__init__()
+        self.message = message
+
+
+class NoProjectError(ReleaseError):
+    def __init__(self):
+        super().__init__("No project definition found.")
+
+
+class TagExistsError(ReleaseError):
+    def __init__(self, tag: str):
+        super().__init__(f"Tag {tag}] already exists.")
+        self.tag = tag
+
+
+class VersionNotAdvancing(Exception):
+    def __init__(self, version: str):
+        super().__init__()
+        self.message = f"[{version}] Version did not change, not doing anything."
+        self.version = version