feat: better list-all support (#101)

* feat: better list-all support
* feat: two small helpers
* feat: get_check_description too

-----

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

.readthedocs.yml renamed to .readthedocs.yaml

@@ -1,4 +1,4 @@
-# .readthedocs.yml
+# .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 

docs/checks.md

@@ -29,7 +29,7 @@ the check passes, or `False` if the check fails. If you want a dynamic error
 explanation instead of the `check()` docstring, you can return a non-empty
 string from the check instead of `False`. Returning `None` makes a check
 "skipped". Docstrings/error messages can access their own object with `{self}`
-and check name with `{name}` (these are processed with `.format`, so escape `{}`
+and check name with `{name}` (these are processed with `.format()`, so escape `{}`
 as `{{}}`). The error message is in markdown format.
 
 If the check named in `requires` does not pass, the check is skipped.
@@ -101,7 +101,7 @@ def repo_review_checks() -> dict[str, General | PyProject]:
     return general | pyproject
 ```
 
-You tell repo review to use this function via an entry-point:
+You tell repo-review to use this function via an entry-point:
 
 ```toml
 [project.entry-points."repo_review.checks"]
@@ -154,3 +154,36 @@ def repo_review_checks(pyproject: dict[str, Any]) -> dict[str, PyProject]:
         case _:
             return {}
 ```
+
+### Handling empty generation
+
+If repo-review is listing all checks, a
+{class}`repo_review.ghpath.EmptyTraversable` is passed for `root` and
+`package`. This will appear to be a directory with no contents. If you have
+conditional checks, you should handle this case to support being listed as a
+possible check. As a helper for this case, a
+{func}`~repo_review.fixtures.list_all` fixture is provided that returns {obj}`True`
+only if a list-all operation is being performed. The above can then be written:
+
+```python
+def repo_review_checks(
+    list_all: bool, pyproject: dict[str, Any]
+) -> dict[str, PyProject]:
+    backends = {
+        "setuptools.build_api": "setuptools",
+        "scikit_build_core.build": "scikit-build",
+    }
+
+    if list_all:
+        return {"PP003": PP003(name="<backend>")}
+
+    match pyproject:
+        case {"build-system": {"build-backend": str(x)}} if x in backends:
+            return {"PP003": PP003(name=backends[x])}
+        case _:
+            return {}
+```
+
+```{versionadded} 0.8
+The {func}`~repo_review.fixtures.list_all` fixture.
+```

docs/fixtures.md

@@ -1,10 +1,11 @@
 # Fixtures
 
-Like pytest fixtures, fixtures in repo-review are requested by name. There are three built-in fixtures:
+Like pytest fixtures, fixtures in repo-review are requested by name. There are four built-in fixtures:
 
-- `root: Traversable` - The repository path. All checks or fixtures that depend on the root of the repository should use this.
-- `package: Traversable` - The path to the package directory. This is the same as `root` unless `--package-dir` is passed.
-- `pyproject: dict[str, Any]` - The `pyproject.toml` in the package if it exists, an empty dict otherwise.
+- `root`: {class}`~importlib.resources.abc.Traversable` - The repository path. All checks or fixtures that depend on the root of the repository should use this.
+- `package`: `~importlib.resources.abc.Traversable` - The path to the package directory. This is the same as `root` unless `--package-dir` is passed.
+- {func}`~repo_review.fixtures.pyproject`: `dict[str, Any]` - The `pyproject.toml` in the package if it exists, an empty dict otherwise.
+- {func}`~repo_review.fixtures.list_all`: `bool` - returns True if repo-review is just trying to collect all checks to list them.
 
 Repo-review doesn't necessarily assume any form or language for your repository,
 but since it already looks for configuration in `pyproject.toml`, this fixture

docs/index.md

@@ -6,6 +6,7 @@
 
 intro
 cli
+programmatic
 plugins
 fixtures
 checks
@@ -15,7 +16,6 @@ changelog
 ```
 
 ```{toctree}
-:maxdepth: 2
 :hidden:
 :caption: API
 

docs/programmatic.md

@@ -0,0 +1,94 @@
+# Programmatic usage
+
+You can use repo-review from other Python code, as well, such as with
+[`cog`][]. Also see [](./webapp.md).
+
+## Processors
+
+The core of repo-review is the {func}`repo_review.processor.process` function. Use it like this:
+
+```python
+root = Path(".")
+processed = repo_review.processor.process(root, select=set(), ignore=set(), subdir=".")
+```
+
+The `root` parameter can be any
+{class}`~importlib.resources.abc.Traversable`. The keyword arguments are
+optional (defaults are shown). This returns a {class}`~typing.NamedTuple`,
+{class}`~repo_review.processor.ProcessReturn`. `.families` is a dict mapping
+family names to {class}`~repo_review.families.Family` and `.results` is a list
+of {class}`~repo_review.processor.Result`s. If you want, you can turn the results
+list into a simple list of dicts with {func}`~repo_review.processor.as_simple_dict`.
+
+### Getting the family name
+
+A common requirement is getting the "nice" family name given the short name.
+There's a tiny helper for this, {func}`repo_review.families.get_family_name`:
+
+```python
+family_name = get_family_name(families, family)
+```
+
+.. versionadded:: 0.8
+
+## Listing all possible checks
+
+You can also get a list of checks:
+
+```python
+collected = repo_review.processor.collect_all()
+```
+
+This returns a {class}`~repo_review.processor.CollectionReturn`. You can access the `.checks`,
+`.families`, and `.fixtures`, all are dicts.
+
+.. versionadded:: 0.8
+
+### Getting the check properties
+
+A common requirement is getting the url from the
+{class}`~repo_review.checks.Check`. While a
+{class}`~repo_review.processor.Result` already has the URL fully rendered,
+checks do not; they are directly returned by plugins. There's a tiny helper
+for this, {func}`repo_review.checks.get_check_url`:
+
+```python
+url = get_check_url(name, check)
+```
+
+.. versionadded:: 0.8
+
+You can also use a helper to get `__doc__` with the correct substitution, as well:
+
+```python
+doc = get_check_description(name, check)
+```
+
+.. versionadded:: 0.8
+
+### Example: cog
+
+Here's an example of using this to fill out a README with [`cog`][], formatting all possible checks in markdown:
+
+```md
+<!-- [[[cog
+import itertools
+
+from repo_review.processor import collect_all
+from repo_review.checks import get_check_url, get_check_description
+from repo_review.families import get_family_name
+
+collected = collect_all()
+print()
+for family, grp in itertools.groupby(collected.checks.items(), key=lambda x: x[1].family):
+    print(f'### {get_family_name(collected.families, family)}')
+    for code, check in grp:
+        url = get_check_url(code, check)
+        link = f"[`{code}`]({url})" if url else f"`{code}`"
+        print(f"- {link}: {get_check_description(code, check)}")
+    print()
+]]] -->
+<!-- [[[end]]] -->
+```
+
+[`cog`]: https://nedbatchelder.com/code/cog

noxfile.py

@@ -92,7 +92,7 @@ def docs(session: nox.Session) -> None:
     if args.builder != "html" and args.serve:
         session.error("Must not specify non-HTML builder with --serve")
 
-    session.install(".[docs]")
+    session.install("-e.[docs]")
     session.chdir("docs")
 
     if args.builder == "linkcheck":
@@ -104,6 +104,7 @@ def docs(session: nox.Session) -> None:
     session.run(
         "sphinx-build",
         "-n",  # nitpicky mode
+        "--keep-going",  # show all errors
         "-T",  # full tracebacks
         "-b",
         args.builder,

pyproject.toml

@@ -73,6 +73,7 @@ repo-review = "repo_review.__main__:main"
 
 [project.entry-points."repo_review.fixtures"]
 pyproject = "repo_review.fixtures:pyproject"
+list_all = "repo_review.fixtures:list_all"
 
 
 [tool.hatch]

src/repo_review/__main__.py

@@ -26,10 +26,11 @@
 from . import __version__
 from ._compat.importlib.resources.abc import Traversable
 from ._compat.typing import assert_never
-from .families import Family
-from .ghpath import EmptyTraversable, GHPath
+from .checks import get_check_description, get_check_url
+from .families import Family, get_family_name
+from .ghpath import GHPath
 from .html import to_html
-from .processor import Result, _collect_all, as_simple_dict, process
+from .processor import Result, as_simple_dict, collect_all, process
 
 __all__ = ["main"]
 
@@ -45,15 +46,22 @@ def list_all(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
     if not value or ctx.resilient_parsing:
         return
 
-    _, checks, families = _collect_all(EmptyTraversable())
-    if len(checks) == 0:
+    collected = collect_all()
+    if len(collected.checks) == 0:
         msg = "No checks registered. Please install a repo-review plugin."
         raise click.ClickException(msg)
 
-    for family, grp in itertools.groupby(checks.items(), key=lambda x: x[1].family):
-        rich.print(f'  [dim]# {families[family].get("name", family)}')
+    for family, grp in itertools.groupby(
+        collected.checks.items(), key=lambda x: x[1].family
+    ):
+        rich.print(f"  [dim]# {get_family_name(collected.families, family)}")
         for code, check in grp:
-            rich.print(f'  "{code}",  [dim]# {check.__doc__}')
+            url = get_check_url(code, check)
+            doc = get_check_description(code, check)
+            link = f"[link={url}]{code}[/link]" if url else code
+            comment = f" [dim]# {doc}" if doc else ""
+            rich.print(f'  "{link}",{comment}')
+
     ctx.exit()
 
 
@@ -70,7 +78,7 @@ def rich_printer(
     )
 
     for family, results_list in itertools.groupby(processed, lambda r: r.family):
-        family_name = families[family].get("name", family)
+        family_name = get_family_name(families, family)
         tree = rich.tree.Tree(f"[bold]{family_name}[/bold]:")
         for result in results_list:
             style = (
@@ -206,8 +214,8 @@ def main(
     ignore_list = {x.strip() for x in ignore.split(",") if x}
     select_list = {x.strip() for x in select.split(",") if x}
 
-    _, checks, _ = _collect_all(package, subdir=package_dir)
-    if len(checks) == 0:
+    collected = collect_all(package, subdir=package_dir)
+    if len(collected.checks) == 0:
         msg = "No checks registered. Please install a repo-review plugin."
         raise click.ClickException(msg)
 

src/repo_review/checks.py

@@ -6,7 +6,7 @@
 
 from .fixtures import apply_fixtures
 
-__all__ = ["Check", "collect_checks", "is_allowed"]
+__all__ = ["Check", "collect_checks", "is_allowed", "get_check_url"]
 
 
 class Check(Protocol):
@@ -83,3 +83,31 @@ def is_allowed(select: Set[str], ignore: Set[str], name: str) -> bool:
     if name in ignore or name.rstrip("0123456789") in ignore:
         return False
     return True
+
+
+def get_check_url(name: str, check: Check) -> str:
+    """
+    Get the url from a check instance. Will return an empty string if missing.
+    Will process string via format.
+
+    :param name: The name of the check (letters and number)
+    :param check: The check to process.
+    :return: The final URL.
+
+    .. versionadded:: 0.8
+    """
+    return getattr(check, "url", "").format(self=check, name=name)
+
+
+def get_check_description(name: str, check: Check) -> str:
+    """
+    Get the doc from a check instance. Will return an empty string if missing.
+    Will process string via format.
+
+    :param name: The name of the check (letters and number)
+    :param check: The check to process.
+    :return: The final doc.
+
+    .. versionadded:: 0.8
+    """
+    return (check.__doc__ or "").format(self=check, name=name)

src/repo_review/families.py

@@ -2,8 +2,9 @@
 
 import importlib.metadata
 import typing
+from collections.abc import Mapping
 
-__all__ = ["Family", "collect_families"]
+__all__ = ["Family", "collect_families", "get_family_name"]
 
 
 def __dir__() -> list[str]:
@@ -36,3 +37,17 @@ def collect_families() -> dict[str, Family]:
         for ep in importlib.metadata.entry_points(group="repo_review.families")
         for name, family in ep.load()().items()
     }
+
+
+def get_family_name(families: Mapping[str, Family], family: str) -> str:
+    """
+    Returns the "nice" family name if there is one, otherwise the (input)
+    family short name.
+
+    :param families: A dict of family short names to :class:`.Family`'s.
+    :param family: The short name of a family.
+    :return: The nice family name if there is one, otherwise the short name is returned.
+
+    .. versionadded:: 0.8
+    """
+    return families.get(family, {}).get("name", family)

src/repo_review/fixtures.py

@@ -9,9 +9,11 @@
 
 from ._compat import tomllib
 from ._compat.importlib.resources.abc import Traversable
+from .ghpath import EmptyTraversable
 
 __all__ = [
     "pyproject",
+    "list_all",
     "compute_fixtures",
     "apply_fixtures",
     "collect_fixtures",
@@ -28,6 +30,8 @@ def pyproject(package: Traversable) -> dict[str, Any]:
     empty dict if no pyproject.toml found.
 
     :param package: The package fixture.
+
+    :return: The pyproject.toml dict or an empty dict if no file found.
     """
     pyproject_path = package.joinpath("pyproject.toml")
     if pyproject_path.is_file():
@@ -36,6 +40,20 @@ def pyproject(package: Traversable) -> dict[str, Any]:
     return {}
 
 
+def list_all(root: Traversable) -> bool:
+    """
+    Fixture: Is True when this is trying to produce a list of all checks.
+
+    :param root: The root fixture.
+
+    :return: True only if trying to make a list of all checks/fixtures/families.
+
+    .. versionadded:: 0.8
+    """
+
+    return isinstance(root, EmptyTraversable)
+
+
 def compute_fixtures(
     root: Traversable,
     package: Traversable,