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

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

@@ -4,6 +4,34 @@ Changelog
 
 All notable changes to this project will be documented in this file.
 
+`0.22.0 <https://github.com/mzdun/proj-flow/compare/v0.21.0...v0.22.0>`_ (2026-02-03)
+=====================================================================================
+
+New Features
+------------
+
+- get test-runner over from cov (`4829061 <https://github.com/mzdun/proj-flow/commit/4829061c153ea66b8c323766f82147d2e71ee5b7>`_)
+
+Bug Fixes
+---------
+
+- make CMake presets more accessible (`d78726f <https://github.com/mzdun/proj-flow/commit/d78726fd708804a04ee3170fa5e90e27a6fa3941>`_)
+- move ``rt.root`` to ``Path`` (`fe6f3e7 <https://github.com/mzdun/proj-flow/commit/fe6f3e7b6968a01f847599e06c67bfeb463d7802>`_)
+
+`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.22.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: proj-flow
-Version: 0.20.3
+Version: 0.22.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.22.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.22.0/schema/test-runner.yaml

@@ -0,0 +1,44 @@
+$schema: http://json-schema.org/draft-04/schema#
+type: object
+required: [args, expected]
+additionalProperties: false
+default: {}
+
+properties:
+  $schema: {type: string}
+  linear: {type: boolean}
+  disabled: {type: [boolean, string]}
+  lang: {type: string}
+  args: {type: string}
+  post: {type: [string, array], items: {type: string}}
+  expected: 
+    type: ["null", array]
+    items:
+      - type: integer
+      - $ref: "#/$defs/lines"
+      - $ref: "#/$defs/lines"
+  check:
+    type: object
+    properties: 
+      stdout: {$ref: "#/$defs/check"}
+      stderr: {$ref: "#/$defs/check"}
+  writes: {$ref: "#/$defs/dictionary"}
+  patches: {$ref: "#/$defs/dictionary"}
+  prepare: { $ref: "#/$defs/commands" }
+  cleanup: { $ref: "#/$defs/commands" }
+
+$defs:
+  dictionary:
+    type: object
+    properties:
+      ^$: {not: {}}
+      ^.+$: {type: string}
+  lines:
+    type: [string, array]
+    items: string
+  commands:
+    type: array
+    items: string
+  check:
+    type: enum
+    enum: [begin, end, all]

{proj_flow-0.20.3 → proj_flow-0.22.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.22.0"

{proj_flow-0.20.3 → proj_flow-0.22.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.22.0}/src/proj_flow/api/completers.py

@@ -57,7 +57,7 @@ def _str_arg(arg: Union[bool, str]):
 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")
+    matrix_yml = 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", {}

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

@@ -21,10 +21,12 @@ import subprocess
 import sys
 from dataclasses import dataclass
 from enum import Enum
+from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Union, cast
 
 from proj_flow.api import ctx
 from proj_flow.base import plugins, uname
+from proj_flow.base.cmake_presets import get_binary_dirs
 
 platform = uname.uname()[0]
 
@@ -32,6 +34,25 @@ platform = uname.uname()[0]
 _flow_config_default_compiler: Optional[Dict[str, str]] = None
 
 
+class CMakeBinaryDirsCache:
+    _dirs: dict[str, Path] | None = None
+    _loaded: bool = False
+
+    @property
+    def dirs(self):
+        if not self._loaded:
+            self._loaded = True
+            self._dirs = get_binary_dirs()
+
+        return self._dirs
+
+    def binary_dir(self, key: str):
+        return (self.dirs or {}).get(key)
+
+
+CMAKE_BINARY_DIRS = CMakeBinaryDirsCache()
+
+
 def default_compiler():
     try:
         return os.environ["DEV_CXX"]
@@ -152,7 +173,7 @@ def _flatten_dict(dst: ctx.SettingsType, defaults: Dict[str, Any], prefix=""):
         dst[this_key] = str(val)
 
 
-def _merge(cfg: dict, defaults: ctx.SettingsType, path: str):
+def _merge(cfg: dict, defaults: ctx.SettingsType, path: Path):
     config = plugins.load_data(path)
     if not isinstance(config, dict):
         return
@@ -173,35 +194,41 @@ def load_extensions(extensions: List[str]):
     for extension in extensions:
         try:
             importlib.import_module(extension)
-        except ModuleNotFoundError:
+        except ImportError as ex:
+            print(
+                f"-- error: loading module `{extension}` resulted in import error: {ex}",
+                file=sys.stderr,
+            )
+        except BaseException as ex:
             print(
-                f"-- error: module `{extension}` was no found, ignoring",
+                f"-- error: there was an error while loading module `{extension}`: {ex}",
                 file=sys.stderr,
             )
 
+
 class FlowConfig:
     _cfg: dict
     steps: list = []
     aliases: List[RunAlias] = []
-    root: str
+    root: Path
 
-    def __init__(self, cfg: Optional["FlowConfig"] = None, root: str = "."):
+    def __init__(self, cfg: Optional["FlowConfig"] = None, root: Path = Path()):
         if cfg is not None:
             self._cfg = cfg._cfg
             self.steps = cfg.steps
             self.aliases = cfg.aliases
             self.root = cfg.root
         else:
-            self.root = os.path.abspath(root)
+            self.root = root.absolute()
             defaults: ctx.SettingsType = {}
             dest: dict = {}
 
             _merge(
                 dest,
                 defaults,
-                os.path.join(os.path.expanduser("~"), ".config", "proj-flow.json"),
+                Path("~").expanduser() / ".config" / "proj-flow.json",
             )
-            _merge(dest, defaults, os.path.join(self.root, ".flow", "config.json"))
+            _merge(dest, defaults, self.root / ".flow" / "config.json")
 
             self._cfg = dest
             self._cfg["defaults"] = defaults
@@ -217,11 +244,9 @@ class FlowConfig:
         extensions = cast(List[str], self._cfg.get("extensions", []))
         extensions.insert(0, "proj_flow.minimal")
 
-        local_extensions = os.path.abspath(
-            os.path.join(self.root, ".flow", "extensions")
-        )
-        if os.path.isdir(local_extensions):
-            sys.path.insert(0, local_extensions)
+        local_extensions = (self.root / ".flow" / "extensions").resolve()
+        if local_extensions.is_dir():
+            sys.path.insert(0, local_extensions.as_posix())
 
         load_extensions(extensions)
 
@@ -459,8 +484,13 @@ class Config:
         return self.items.get("build_name", "")
 
     @property
-    def build_dir(self) -> str:
-        return os.path.join("build", self.preset)
+    def build_dir(self) -> Path:
+        cmake_binary_dir = CMAKE_BINARY_DIRS.binary_dir(
+            f"{self.preset}-{self.build_generator}"
+        )
+        if cmake_binary_dir:
+            return cmake_binary_dir
+        return Path("build") / self.preset
 
     @property
     def preset(self) -> str:

{proj_flow-0.20.3 → proj_flow-0.22.0}/src/proj_flow/api/release.py

@@ -113,5 +113,5 @@ def get_project(rt: env.Runtime):
 
     _, project = project_suites.find(wrap)
     if project is None:
-        rt.fatal(f"Cannot get project information from {rt.root}")
+        rt.fatal(f"Cannot get project information from {rt.root.as_posix()}")
     return project

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

@@ -7,6 +7,7 @@ The **proj_flow.api.step** exposes APIs used by run extensions.
 
 import os
 from abc import ABC, abstractmethod
+from pathlib import Path
 from typing import List, cast
 
 from proj_flow.api.env import Config, Runtime
@@ -34,7 +35,7 @@ class Step(ABC):
     def is_active(self, config: Config, rt: Runtime) -> bool:
         return True
 
-    def directories_to_remove(self, config: Config) -> List[str]:
+    def directories_to_remove(self, config: Config) -> List[Path]:
         return []
 
     @abstractmethod
@@ -59,7 +60,7 @@ class SerialStep(Step):
                 return False
         return True
 
-    def directories_to_remove(self, config: Config) -> List[str]:
+    def directories_to_remove(self, config: Config) -> List[Path]:
         return matrix.flatten(
             [child.directories_to_remove(config) for child in self.children]
         )
@@ -87,8 +88,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 +136,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}",
@@ -154,7 +163,10 @@ def _extend_docstring(conv, step: Step):
             _name_list("Requires", step.platform_dependencies(), template="``{}``"),
             _name_list(
                 "Removes",
-                step.directories_to_remove(_dummy_config),
+                [
+                    dirname.as_posix()
+                    for dirname in step.directories_to_remove(_dummy_config)
+                ],
                 template="``{}``",
             ),
         )
@@ -163,6 +175,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/src/proj_flow/ext/cplusplus/cmake/presets.py → proj_flow-0.22.0/src/proj_flow/base/cmake_presets.py

@@ -2,7 +2,7 @@
 # This code is licensed under MIT license (see LICENSE for details)
 
 """
-The **proj_flow.ext.cplusplus.cmake.presets** check build directories for CMake step.
+The **proj_flow.project.cplusplus.cmake_presets** check build directories for CMake step.
 """
 
 import json
@@ -11,7 +11,7 @@ import platform
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import cast
+from typing import Callable, TypeVar, cast
 
 
 class MacroType(Enum):
@@ -40,6 +40,7 @@ MACROS: dict[str, Path | str | MacroType] = {
 class Preset:
     name: str
     binary_dir: str | None
+    build_type: str | None
     generator: str | None
     inherits: list[str]
     file_dir: Path
@@ -82,12 +83,15 @@ class Presets:
         if dirname is None:
             return self.result
 
-        includes, presets = Presets.__load_file(filename)
-        self.__visit_includes(dirname, includes)
-        for preset in presets:
-            self.__visit_preset(dirname, preset)
-        for preset in self.result.values():
-            self.__merge_preset(preset)
+        try:
+            includes, presets = Presets.__load_file(filename)
+            self.__visit_includes(dirname, includes)
+            for preset in presets:
+                self.__visit_preset(dirname, preset)
+            for preset in self.result.values():
+                self.__merge_preset(preset)
+        except FileNotFoundError:
+            return None
 
         return self.result
 
@@ -109,9 +113,12 @@ class Presets:
         binary_dir = cast(str | None, preset.get("binaryDir"))
         generator = cast(str | None, preset.get("generator"))
         inherits = cast(list[str], preset.get("inherits", []))
+        cache = cast(dict, preset.get("cacheVariables", {}))
+        build_type = cast(str | None, cache.get("CMAKE_BUILD_TYPE"))
         self.result[name] = Preset(
             name=name,
             binary_dir=binary_dir,
+            build_type=build_type,
             generator=generator,
             inherits=inherits,
             file_dir=dirname,
@@ -132,6 +139,8 @@ class Presets:
                 preset.binary_dir = parent_preset.binary_dir
             if parent_preset.generator and not preset.generator:
                 preset.generator = parent_preset.generator
+            if parent_preset.build_type and not preset.build_type:
+                preset.build_type = parent_preset.build_type
 
     @staticmethod
     def __load_file(filename: Path):
@@ -143,18 +152,33 @@ class Presets:
         return (includes, presets)
 
 
+def binary_dir_from_preset(preset: Preset, cwd: Path):
+    path = preset.expand()
+    if not path:
+        return None
+    if path.is_relative_to(cwd):
+        path = path.relative_to(cwd)
+    return path
+
+
 def get_binary_dirs():
+    return visit_presets(binary_dir_from_preset)
+
+
+T = TypeVar("T")
+
+
+def visit_presets(mapper: Callable[[Preset, Path], T | None]):
     presets = Presets().visit_file(Path("CMakePresets.json"))
+    if presets is None:
+        return None
 
-    cwd = str(Path.cwd().as_posix()) + "/"
-    result: dict[str, str] = {}
+    cwd = Path.cwd()
+    result: dict[str, T] = {}
     for preset in presets.values():
-        dirname = preset.expand()
-        if dirname is None:
+        mapped = mapper(preset, cwd)
+        if mapped is None:
             continue
-        rel = str(dirname.as_posix())
-        if rel[: len(cwd)] == cwd:
-            rel = rel[len(cwd) :]
-        result[preset.name] = rel
+        result[preset.name] = mapped
 
     return result

{proj_flow-0.20.3 → proj_flow-0.22.0}/src/proj_flow/base/plugins.py

@@ -6,18 +6,23 @@ The **proj_flow.base.plugins** provide the plugin enumeration helpers.
 """
 
 import json
-import os
+from pathlib import Path
 from typing import cast
 
 import yaml
 
+try:
+    from yaml import CLoader as Loader
+except ImportError:
+    from yaml import Loader
 
-def load_yaml(filename: str):
+
+def load_yaml(filename: Path):
     with open(filename) as src:
-        return cast(dict, yaml.load(src, Loader=yaml.Loader))
+        return cast(dict, yaml.load(src, Loader=Loader))
 
 
-def load_json(filename: str):
+def load_json(filename: Path):
     with open(filename) as src:
         return cast(dict, json.load(src))
 
@@ -29,8 +34,8 @@ LOADERS = {
 }
 
 
-def load_data(filename: str):
-    prefix, ext = os.path.splitext(filename)
+def load_data(filename: Path):
+    ext = filename.suffix
     loader = LOADERS.get(ext.lower())
     if loader:
         try:
@@ -39,7 +44,7 @@ def load_data(filename: str):
             pass
 
     for new_ext, loader in LOADERS.items():
-        new_filename = prefix + new_ext
+        new_filename = filename.with_suffix(new_ext)
         try:
             return loader(new_filename)
         except Exception:

{proj_flow-0.20.3 → proj_flow-0.22.0}/src/proj_flow/cli/finder.py

@@ -9,6 +9,7 @@ contains ``-C`` argument.
 
 import os
 import shlex
+from pathlib import Path
 from typing import List
 
 from argcomplete import finders
@@ -43,7 +44,7 @@ class CompletionFinder(finders.CompletionFinder):
 
     def find_project(self):
         if not self.active():
-            return "."
+            return Path()
 
         comp_line = os.environ["COMP_LINE"]
         comp_point = int(os.environ["COMP_POINT"])
@@ -51,9 +52,9 @@ class CompletionFinder(finders.CompletionFinder):
         pos = find_dash_see(args)
 
         if pos < 0:
-            return "."
+            return Path()
 
-        return args[pos]
+        return Path(args[pos])
 
 
 autocomplete = CompletionFinder()

{proj_flow-0.20.3 → proj_flow-0.22.0}/src/proj_flow/dependency.py

@@ -57,14 +57,18 @@ class Dependency:
     version_expression: str
     kind: DepKind = DepKind.APP
 
-    def __lt__(self, rhs: "Dependency"):
+    def __lt__(self, rhs: object):
+        if not isinstance(rhs, Dependency):
+            return False
         if self.kind != rhs.kind:
             return self.kind.value < rhs.kind.value
         if self.name != rhs.name:
             return self.name < rhs.name
         return self.version_expression < rhs.version_expression
 
-    def __eq__(self, rhs: "Dependency"):
+    def __eq__(self, rhs: object):
+        if not isinstance(rhs, Dependency):
+            return False
         return (
             self.kind == rhs.kind
             and self.name == rhs.name

{proj_flow-0.20.3 → proj_flow-0.22.0}/src/proj_flow/ext/cplusplus/cmake/__init__.py

@@ -7,6 +7,6 @@ The **proj_flow.ext.cplusplus.cmake** provides ``"CMake"``, ``"Build"``,
 context.
 """
 
-from . import parser, presets, project, steps
+from . import parser, project, steps
 
-__all__ = ["parser", "presets", "project", "steps"]
+__all__ = ["parser", "project", "steps"]

{proj_flow-0.20.3 → proj_flow-0.22.0}/src/proj_flow/ext/cplusplus/cmake/parser.py

@@ -7,6 +7,7 @@ The **proj_flow.ext.cplusplus.cmake.parser** contains simple CMake parser.
 
 import os
 import re
+from pathlib import Path
 from typing import Iterator, List, NamedTuple, Optional
 
 from proj_flow.api.release import NO_ARG, Arg
@@ -76,7 +77,7 @@ def _command(cmd: Token, stream: Iterator[Token]):
     return result
 
 
-def _cmake(filename: str):
+def _cmake(filename: Path):
     commands: List[Command] = []
 
     with open(filename, "r", encoding="UTF-8") as f:
@@ -102,9 +103,9 @@ def _patch(directory: str, arg: Arg, value: str):
         input.write(patched)
 
 
-def get_project(dirname: str) -> Optional[CMakeProject]:
+def get_project(dirname: Path) -> Optional[CMakeProject]:
     try:
-        commands = _cmake(os.path.join(dirname, "CMakeLists.txt"))
+        commands = _cmake(dirname / "CMakeLists.txt")
     except FileNotFoundError:
         return None