proj-flow 0.20.3__tar.gz → 0.21.0__tar.gz

{proj_flow-0.20.3 → proj_flow-0.21.0}/CHANGELOG.rst

@@ -4,6 +4,20 @@ Changelog
 
 All notable changes to this project will be documented in this file.
 
+`0.21.0 <https://github.com/mzdun/proj-flow/compare/v0.20.3...v0.21.0>`_ (2026-02-03)
+=====================================================================================
+
+New Features
+------------
+
+- recursively list known commands (`991b120 <https://github.com/mzdun/proj-flow/commit/991b120df9da90fee9047d440c2d0cc133ce740c>`_)
+- **list**: wrap cmd help around terminal width (`64bd30c <https://github.com/mzdun/proj-flow/commit/64bd30cfd3c05da92be705a436f5d9cfcad14630>`_)
+
+Bug Fixes
+---------
+
+- **docs**: touchup on documentation (`4c374be <https://github.com/mzdun/proj-flow/commit/4c374be954f8af5597ba6a25f13cd332bf7bcc5e>`_)
+
 `0.20.3 <https://github.com/mzdun/proj-flow/compare/v0.20.2...v0.20.3>`_ (2026-01-30)
 =====================================================================================
 

{proj_flow-0.20.3 → proj_flow-0.21.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: proj-flow
-Version: 0.20.3
+Version: 0.21.0
 Summary: C++ project maintenance, automated
 Project-URL: Changelog, https://github.com/mzdun/proj-flow/blob/main/CHANGELOG.rst
 Project-URL: Documentation, https://proj-flow.readthedocs.io/en/latest/
 Project-URL: Homepage, https://pypi.org/project/proj-flow/
 Project-URL: Source Code, https://github.com/mzdun/proj-flow
 Author-email: Marcin Zdun <marcin.zdun@gmail.com>
+License-Expression: MIT
 License-File: LICENSE
 Keywords: C/C++,build-tool,c++,ci-cd,continuous-integration,cpp,dependencies,dependency-manager,developer,developer-tools,development,meta-build-tool,pipeline,tools-and-automation
 Classifier: Development Status :: 4 - Beta
@@ -17,13 +18,22 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Topic :: Software Development :: Build Tools
 Requires-Python: >=3.10
-Requires-Dist: argcomplete
+Requires-Dist: argcomplete~=3.5
 Requires-Dist: chevron2021
-Requires-Dist: prompt-toolkit
-Requires-Dist: pywebidl2
-Requires-Dist: pyyaml
-Requires-Dist: requests-cache
-Requires-Dist: toml
+Requires-Dist: prompt-toolkit~=3.0
+Requires-Dist: pywebidl2~=0.1
+Requires-Dist: pyyaml~=6.0
+Requires-Dist: requests-cache~=1.3
+Requires-Dist: toml~=0.10
+Provides-Extra: dev
+Requires-Dist: black~=25.0; extra == 'dev'
+Requires-Dist: build~=1.4; extra == 'dev'
+Requires-Dist: isort~=6.0; extra == 'dev'
+Requires-Dist: sphinx~=9.1; extra == 'dev'
+Requires-Dist: twine<=6.0.1; extra == 'dev'
+Requires-Dist: types-chevron~=0.14; extra == 'dev'
+Requires-Dist: types-pyyaml~=6.0; extra == 'dev'
+Requires-Dist: types-toml~=0.10; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Project Flow

{proj_flow-0.20.3 → proj_flow-0.21.0}/pyproject.toml

@@ -23,13 +23,13 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
 ]
 dependencies = [
-  "argcomplete",
+  "argcomplete~=3.5",
   "chevron2021",
-  "prompt_toolkit",
-  "PyYAML",
-  "toml",
-  "pywebidl2",
-  "requests_cache",
+  "prompt_toolkit~=3.0",
+  "PyYAML~=6.0",
+  "toml~=0.10",
+  "pywebidl2~=0.1",
+  "requests-cache~=1.3",
 ]
 description = "C++ project maintenance, automated"
 dynamic = ["version"]
@@ -49,6 +49,7 @@ keywords = [
   'pipeline',
   'tools-and-automation',
 ]
+license = "MIT"
 name = "proj-flow"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -61,3 +62,21 @@ Homepage = "https://pypi.org/project/proj-flow/"
 
 [project.scripts]
 proj-flow = "proj_flow.cli:main"
+
+[project.optional-dependencies]
+dev = [
+  "build~=1.4",
+  "twine<=6.0.1",
+  "sphinx~=9.1",
+  "black~=25.0",
+  "isort~=6.0",
+  "types-PyYAML~=6.0",
+  "types-chevron~=0.14",
+  "types-toml~=0.10",
+]
+
+[tool.black]
+target-version = ["py310", "py311", "py312", "py313"]
+
+[tool.isort]
+profile = "black"

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/__init__.py

@@ -6,4 +6,4 @@ The **proj_flow** contains only ``__version__`` to be updated, nothing more.
 This is in an attempt to make this module easy to load initially.
 """
 
-__version__ = "0.20.3"
+__version__ = "0.21.0"

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/api/arg.py

@@ -159,6 +159,8 @@ def command(*name: str):
         doc = orig_doc or ""
         if doc:
             doc += "\n\n"
+        doc += f":call: ``proj-flow {' '.join(name)}``\n\n"
+        doc += f":call: ``./flow {' '.join(name)}``\n\n"
 
         for arg in _inspect.signature(entry):
             help = ""

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/api/env.py

@@ -173,11 +173,17 @@ def load_extensions(extensions: List[str]):
     for extension in extensions:
         try:
             importlib.import_module(extension)
-        except ModuleNotFoundError:
+        except ImportError as ex:
             print(
-                f"-- error: module `{extension}` was no found, ignoring",
+                f"-- error: loading module `{extension}` resulted in import error: {ex}",
                 file=sys.stderr,
             )
+        except BaseException as ex:
+            print(
+                f"-- error: there was an error while loading module `{extension}`: {ex}",
+                file=sys.stderr,
+            )
+
 
 class FlowConfig:
     _cfg: dict

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/api/step.py

@@ -87,8 +87,10 @@ def _register_step(step: Step, replace: bool):
                 return
 
         if "READTHEDOCS" not in os.environ:
-            raise NameError(f"Step {name} is marked as replacing, but there is no previous step with that name")
-        
+            raise NameError(
+                f"Step {name} is marked as replacing, but there is no previous step with that name"
+            )
+
     if name in [step.name for step in __steps]:
         if "READTHEDOCS" not in os.environ:
             raise NameError(f"Step {name} already registered")
@@ -133,6 +135,12 @@ def _make_private(f: _inspect.Function):
         f.__doc__ = ":meta private:\n"
 
 
+def _make_private_property(f):
+    if isinstance(f, property):
+        _make_private(cast(_inspect.Function, f))
+        return
+
+
 _dummy_config = Config(
     {
         "os": "${os}",
@@ -163,6 +171,9 @@ def _extend_docstring(conv, step: Step):
     doc = conv.__doc__ or "*Docstring is missing!*"
     conv.__doc__ = f"{doc}\n{info}"
 
+    _make_private_property(conv.name)
+    _make_private_property(conv.runs_before)
+    _make_private_property(conv.runs_after)
     _make_private(conv.is_active)
     _make_private(conv.run)
     _make_private(conv.platform_dependencies)

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/ext/cplusplus/cmake/presets.py

@@ -135,10 +135,14 @@ class Presets:
 
     @staticmethod
     def __load_file(filename: Path):
-        with open(filename, encoding="UTF-8") as f:
-            data = json.load(f)
-        includes = cast(list[str], data.get("include", []))
-        presets = cast(list[dict], data.get("configurePresets", []))
+        try:
+            with open(filename, encoding="UTF-8") as f:
+                data = json.load(f)
+            includes = cast(list[str], data.get("include", []))
+            presets = cast(list[dict], data.get("configurePresets", []))
+        except FileNotFoundError:
+            includes: list[str] = []
+            presets: list[dict] = []
 
         return (includes, presets)
 

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/ext/cplusplus/cmake/steps.py

@@ -22,14 +22,17 @@ class CMakeBase(api.step.Step):
 
     @property
     def name(self):
+        """:meta private:"""
         return self._name
 
     @property
     def runs_after(self):
+        """:meta private:"""
         return self._runs_after
 
     @property
     def runs_before(self):
+        """:meta private:"""
         return self._runs_before
 
     def __init__(
@@ -47,6 +50,7 @@ class CMakeBase(api.step.Step):
         return [f"cmake>={CMAKE_VERSION}"]
 
     def dep_with_tool(self, tool: str):
+        """:meta private:"""
         return [f"cmake>={CMAKE_VERSION}", f"{tool}>={CMAKE_VERSION}"]
 
 
@@ -64,7 +68,9 @@ class CMakeConfig(CMakeBase):
     def directories_to_remove(self, config: env.Config) -> List[str]:
         binary_dir = self.binary_dirs.get(f"{config.preset}-{config.build_generator}")
         if not binary_dir:
-            return []
+            if "READTHEDOCS" not in os.environ:
+                return []
+            return [f"build/{config.preset}"]
         return [binary_dir]
 
     def run(self, config: env.Config, rt: env.Runtime) -> int:
@@ -78,10 +84,10 @@ class CMakeConfig(CMakeBase):
                 value = value[1:]
 
             if value.startswith("config:"):
-                value = value[len("config:"):]
+                value = value[len("config:") :]
                 value = config.get_path(value)
             elif value.startswith("runtime:"):
-                value = value[len("runtime:"):]
+                value = value[len("runtime:") :]
                 value = getattr(rt, value, None)
 
             if is_flag:

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/ext/cplusplus/conan/__init__.py

@@ -23,7 +23,9 @@ CONAN_PROFILE_GEN = "_profile-build_type"
 class ConanConfig:
     """Configures the project for ``preset`` config using ``build_type`` config."""
 
+    #: :meta private:
     name = "Conan"
+    #: :meta private:
     runs_before = ["CMake"]
 
     def platform_dependencies(self):

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/ext/github/cli.py

@@ -32,9 +32,7 @@ def github():
 
 @arg.command("github", "matrix")
 def matrix(
-    pretty: typing.Annotated[
-        bool, arg.FlagArgument(help="Indent JSON document")
-    ],
+    pretty: typing.Annotated[bool, arg.FlagArgument(help="Indent JSON document")],
     official: typing.Annotated[
         bool, arg.FlagArgument(help="Cut matrix to release builds only")
     ],

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/ext/python/rtdocs.py

@@ -3,7 +3,7 @@
 
 """
 The **proj_flow.ext.python.rtdocs** defines RTDocs step (`"RTD"`), which uses
-.readthedocs.yaml to build the HTML documentation.
+``.readthedocs.yaml`` to build the HTML documentation.
 """
 
 import os
@@ -20,7 +20,11 @@ from proj_flow.base import cmd
 
 @step.register
 class RTDocs:
-    name = "RTD"
+    """Runs the jobs defined by ``.readthedocs.yaml`` to build the docs"""
+
+    @property
+    def name(self):
+        return "RTD"
 
     def platform_dependencies(self):
         return ["python -m PyYAML"]
@@ -100,6 +104,8 @@ class RTDocs:
 
 
 class Builder(ABC):
+    """Base class for any recognized builder in the ``.readthedocs.yaml`` config."""
+
     @property
     @abstractmethod
     def READTHEDOCS_OUTPUT(self) -> str: ...
@@ -112,17 +118,40 @@ class Builder(ABC):
 
 
 class Sphinx(Builder):
-    READTHEDOCS_OUTPUT: str = ""
+    """Builder used, if Sphinx config is found in the config file.
+
+    :param config: filename of a Python script Sphinx should use for the configuration
+    """
+
+    @property
+    def READTHEDOCS_OUTPUT(self) -> str:
+        """A ``build/`` subdirectory placed in the same dir, as ``config`` parameter"""
+        return self.output
 
     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")
+        self.output = os.path.join(os.path.dirname(self.source), "build")
 
-    def build(self, target: str):
+    def build(self, target: str) -> int:
+        """Uses ``spinx-build`` to create the documentation.
+
+        :param target: name of the docs format from YAML config
+        :returns: exit code forwarded from the build tool
+        """
         builder = "latex" if target == "pdf" else target
+        print(shutil.which("sphinx-build"))
+
         return subprocess.run(
-            ["sphinx-build", "-M", builder, self.source, self.READTHEDOCS_OUTPUT],
+            [
+                PYTHON_EXECUTABLE,
+                "-m",
+                "sphinx.cmd.build",
+                "-M",
+                builder,
+                self.source,
+                self.READTHEDOCS_OUTPUT,
+            ],
             shell=False,
         ).returncode
 

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/minimal/list.py

@@ -6,12 +6,20 @@ The **proj_flow.minimal.list** implements ``./flow list`` command.
 """
 
 import os
-from typing import Annotated, Dict, List, Set, cast
+import re
+import sys
+from typing import Annotated, Dict, Iterable, List, Set, cast
 
 from proj_flow import cli
 from proj_flow.api import arg, env, step
 from proj_flow.base import matrix
 
+if sys.platform == "win32":
+    import ctypes
+    import ctypes.wintypes
+else:
+    import termios
+
 
 @arg.command("list")
 def main(
@@ -39,10 +47,7 @@ def main(
         configs = True
 
     if builtin:
-        root = menu
-        while root.parent is not None:
-            root = root.parent
-        builtin_entries = list(sorted((cmd.name, cmd.doc) for cmd in root.children))
+        builtin_entries = list(sorted(_walk_menu(menu)))
         if not pipe and len(builtin_entries) > 0:
             print("Builtin commands")
             print("----------------")
@@ -54,7 +59,10 @@ def main(
 
             name = f"{bold}{entry_name}{reset}"
             if entry_doc:
-                print(f"- {name}: {entry_doc}")
+                print(f"- {name}:", end=" ")
+                _write_console_para(
+                    " ".join(para.split("\n")) for para in entry_doc.split("\n\n")
+                )
             else:
                 print(f"- {name}")
 
@@ -76,7 +84,8 @@ def main(
                 continue
 
             name = f"{bold}{run_alias.name}{reset}"
-            print(f"- {name}: {', '.join(run_alias.steps)}")
+            print(f"- {name}:", end=" ")
+            _write_console_para([", ".join(run_alias.steps)])
 
         printed_something = True
 
@@ -109,8 +118,10 @@ def main(
                 print(f"- {name}*")
 
         if some_unused:
-            print(
-                f"*step can only be run by explicitly calling through {bold}run{reset}."
+            _write_console_para(
+                [
+                    f"*step can only be run by explicitly calling through {bold}run{reset}."
+                ]
             )
 
         printed_something = True
@@ -147,7 +158,8 @@ def main(
                 value = ", ".join(values.get(key, empty))
                 name = f"{bold}{key}{reset}"
                 if value:
-                    print(f"- {name}: {value}")
+                    print(f"- {name}:", end=" ")
+                    _write_console_para([value])
                 else:
                     print(f"- {name}")
 
@@ -157,6 +169,110 @@ def main(
         print(f"Use {bold}--help{reset} to see, which listings are available")
 
 
+def _iterate_levels(menu: cli.argument.Command, prefix: str):
+    yield [(f"{prefix}{cmd.name}", cmd.doc) for cmd in menu.children]
+    for cmd in menu.children:
+        child_prefix = f"{prefix}{cmd.name} "
+        for layer in _iterate_levels(cmd, child_prefix):
+            yield layer
+
+
+def _walk_menu(menu: cli.argument.Command):
+    root = menu
+    while root.parent is not None:
+        root = root.parent
+
+    items: list[tuple[str, str]] = []
+    for layer in _iterate_levels(root, ""):
+        items.extend(layer)
+
+    return items
+
+
+def _cursor_pos():
+    if sys.platform == "win32":
+        old_stdin_mode = ctypes.wintypes.DWORD()
+        old_stdout_mode = ctypes.wintypes.DWORD()
+        kernel32 = ctypes.windll.kernel32
+        kernel32.GetConsoleMode(
+            kernel32.GetStdHandle(-10), ctypes.byref(old_stdin_mode)
+        )
+        kernel32.SetConsoleMode(kernel32.GetStdHandle(-10), 0)
+        kernel32.GetConsoleMode(
+            kernel32.GetStdHandle(-11), ctypes.byref(old_stdout_mode)
+        )
+        kernel32.SetConsoleMode(kernel32.GetStdHandle(-11), 7)
+    else:
+        old_stdin_mode = termios.tcgetattr(sys.stdin)
+        _ = termios.tcgetattr(sys.stdin)
+        _[3] = _[3] & ~(termios.ECHO | termios.ICANON)
+        termios.tcsetattr(sys.stdin, termios.TCSAFLUSH, _)
+    try:
+        _ = ""
+        sys.stdout.write("\x1b[6n")
+        sys.stdout.flush()
+        while not (_ := _ + sys.stdin.read(1)).endswith("R"):
+            pass
+        res = re.match(r".*\[(?P<y>\d*);(?P<x>\d*)R", _)
+    finally:
+        if sys.platform == "win32":
+            kernel32.SetConsoleMode(kernel32.GetStdHandle(-10), old_stdin_mode)
+            kernel32.SetConsoleMode(kernel32.GetStdHandle(-11), old_stdout_mode)
+        else:
+            termios.tcsetattr(sys.stdin, termios.TCSAFLUSH, old_stdin_mode)
+    if res:
+        return (int(res.group("x")), int(res.group("y")))
+    return (1, 1)
+
+
+def _write_console_para(text: Iterable[str]):
+    term_width = os.get_terminal_size().columns
+    margin = min(_cursor_pos()[0], term_width // 2) - 1
+    width = term_width - 1
+    pos = margin
+    for para in text:
+        for word in para.split():
+            if not word:
+                continue
+            word_len = len(word)
+            next_pos = pos + word_len + 1
+
+            if next_pos >= width:
+                orig = pos
+                if orig == margin:
+                    pos = margin - word_len
+                    print(word, end="")
+
+                print()
+                print(" " * margin, end="")
+
+                if orig != margin:
+                    pos = margin
+                    print(word, end=" ")
+            else:
+                print(word, end=" ")
+
+            pos += word_len + 1
+
+            continue
+            if (word_len + 1) > term_width:
+                first_word = pos == margin
+                if first_word:
+                    print(word, end="")
+
+                print(f"\n{' ' * margin}", end="")
+                pos = margin
+
+                if not first_word:
+                    print(word, "", end="")
+                    pos += word_len + 1
+                continue
+
+            print(word, "", end="")
+            pos += word_len + 1
+        print()
+
+
 def _load_flow_data(rt: env.Runtime):
     paths = [os.path.join(".flow", "matrix.yml")]
     m, keys = matrix.load_matrix(*paths)

{proj_flow-0.20.3 → proj_flow-0.21.0}/src/proj_flow/project/api.py

@@ -67,5 +67,6 @@ def get_project_type(id: str):
         raise ProjectNotFound(id)
     return result
 
+
 def load_common_init_setting_extensions():
     env.load_extensions(["proj_flow.ext.github.switches"])