repo_review package¶

Review repos with a set of checks defined by plugins.

Subpackages¶

repo_review.resources package

Submodules¶

repo_review.checks module¶

class repo_review.checks.Check(*args, **kwargs)[source]¶

Bases: Protocol

This is the check Protocol. Since Python doesn’t support optional Protocol members, the two optional members are required if you want to use this Protocol in a type checker. The members can be specified as class properties if you want.

check()[source]¶

This is a check. The docstring is used as the failure message if False is returned. Returning None is a skip. Returning True (or an empty string) is a pass. Can be a classmethod() or staticmethod(). Can take fixtures.

Return type:: bool | None | str

property family: str¶: The family is a string that the checks will be grouped by.

property requires: Set[str]¶: Requires is an (optional) set of checks that must pass for this check to run. Omitting this is like returning set().

property url: str¶: This is an (optional) URL to link to for this check. An empty string is identical to omitting this member.

repo_review.checks.collect_checks(fixtures)[source]¶

Produces a list of checks based on installed entry points. You must provide the evaluated fixtures so that the check functions have access to the fixtures when they are running.

Parameters:: fixtures (Mapping[str, Any]) – Fully evaluated dict of fixtures.
Return type:: dict[str, Check]

repo_review.checks.get_check_url(name, check)[source]¶

Get the url from a check instance. Will return an empty string if missing. Will process string via format.

Parameters:

name (str) – The name of the check (letters and number)
check (Check) – The check to process.

Return type:

str

Returns:

The final URL.

Added in version 0.8.

repo_review.checks.is_allowed(select, ignore, name)[source]¶

Skips the check if the name is in the ignore list or if the name without the number is in the ignore list. If the select list is not empty, only runs the check if the name or name without the number is in the select list.

Parameters:

select (Set[str]) – A set of names or prefixes to include. “*” selects all checks.
ignore (Set[str]) – A set of names or prefixes to exclude.
name (str) – The check to test.

Return type:

bool

Returns:

True if this check is allowed, False otherwise.

repo_review.checks.name_matches(name, selectors)[source]¶

Checks if the name is contained in the matchers. The selectors can be the exact name or just the non-number prefix. Returns the selector that matched, or an empty string if no match.

Parameters:

name (str) – The name to check.
expr – The expression to check against.
selectors (Set[str])

Return type:

str

Returns:

The matched selector if the name matches a selector, or an empty string if no match.

repo_review.families module¶

class repo_review.families.Family[source]¶

Bases: TypedDict

A typed Dict that is used to customize the display of families in reports.

description: str¶: An optional description that shows up under the family name.

name: str¶: Optional nice name to display instead of family key. Treated like family key if missing.

order: int¶: Checks are first sorted by this integer order, then alphabetically by family key. Treated like 0 if missing.

repo_review.families.collect_families(fixtures)[source]¶

Produces a dict mapping family keys to Family dicts based on installed entry points. You must provide the evaluated fixtures so that the family functions have access to the fixtures when they are running, usually used for descriptions.

Parameters:: fixtures (Mapping[str, Any]) – Fully evaluated dict of fixtures.
Return type:: dict[str, Family]

repo_review.families.get_family_name(families, family)[source]¶

Returns the “nice” family name if there is one, otherwise the (input) family short name.

Parameters:

families (Mapping[str, Family]) – A dict of family short names to Family’s.
family (str) – The short name of a family.

Return type:

str

Returns:

The nice family name if there is one, otherwise the short name is returned.

Added in version 0.8.

repo_review.families.sort_family_keys(families)[source]¶

Returns family keys sorted by order, then alphabetically by family key.

Parameters:: families (Mapping[str, Family]) – A dict of family short names to Family’s.
Return type:: list[str]

repo_review.files module¶

repo_review.files.collect_prefetch_files()[source]¶

Produces a mapping with keys "root" and/or "package" to sets of files that should be prefetched.

Entry-points whose name is "package" are collected under the "package" key (resolved relative to the package directory). All other entry-points (name "root" or empty) are collected under "root" (resolved relative to the repository root).

Return type:: dict[str, set[str]]
Returns:: A mapping with keys "root" and/or "package".

repo_review.files.prefetch_root()[source]¶

This entry-point lists files that should be prefetched. This is a suggestion for async loading.

Return type:: set[str]

async repo_review.files.process_prefetch_files(start, /, files, *, subdir='')[source]¶

Process pre-fetch files. This runs in parallel with async loading.

files is a mapping with keys "root" and/or "package". Patterns under "root" are resolved relative to the repository root (start); patterns under "package" are resolved relative to the package directory (start / subdir, or start when subdir is empty).

Parameters:

start (GHPath)
files (Mapping[str, Set[str]])
subdir (str)

Return type:

None

repo_review.fixtures module¶

repo_review.fixtures.apply_fixtures(fixtures, func)[source]¶

Given the pre-computed dict of fixtures and a function, fill in any fixtures from that dict that it requests and return the result.

Parameters:

fixtures (Mapping[str, Any]) – Fully evaluated dict of fixtures.
func (Callable[..., TypeVar(T)]) – Some callable that can take fixtures.

Return type:

TypeVar(T)

repo_review.fixtures.collect_fixtures()[source]¶

Produces a dict of fixture callables based on installed entry points. You should call compute_fixtures() on the result to get the standard dict of fixture results that most other functions in repo-review expect.

Return type:: dict[str, Callable[[Traversable], Any]]
Returns:: A dict of unevaluated fixtures.

repo_review.fixtures.compute_fixtures(root, package, unevaluated_fixtures)[source]¶

Given the repo root Traversable, the package Traversable, and the dict of all fixture callables, compute the dict of fixture results.

Parameters:

root (Traversable) – The root of the repository
package (Traversable) – The path to the package (root / subdir)
unevaluated_fixtures (Mapping[str, Callable[..., Any]]) – The unevaluated mapping of fixture names to callables.

Return type:

dict[str, Any]

Returns:

The fully evaluated dict of fixtures.

repo_review.fixtures.list_all(root)[source]¶

Fixture: Is True when this is trying to produce a list of all checks.

Parameters:: root (Traversable) – The root fixture.
Return type:: bool
Returns:: True only if trying to make a list of all checks/fixtures/families.

Added in version 0.8.

repo_review.fixtures.pyproject(package)[source]¶

Fixture: The pyproject.toml structure from the package. Returned an empty dict if no pyproject.toml found.

Parameters:: package (Traversable) – The package fixture.
Return type:: dict[str, Any]
Returns:: The pyproject.toml dict or an empty dict if no file found.

repo_review.ghpath module¶

class repo_review.ghpath.EmptyTraversable(*, is_a_dir=True, _fake_name='not-a-real-path')[source]¶

Bases: Traversable

This is a Traversable representing an empty directory or a non-existent file.

Parameters:

is_a_dir (bool) – True to treat this like an empty dir.
_fake_name (str) – A customisable fake name.

is_a_dir: bool = True¶: True if this is supposed to be a directory

is_dir()[source]¶

Return True if self is a directory

Return type:: bool

is_file()[source]¶

Return True if self is a file

Return type:: bool

iterdir()[source]¶

Yield Traversable objects in self

Return type:: Iterator[EmptyTraversable]

joinpath(child)[source]¶

Return Traversable resolved with any descendants applied.

Each descendant should be a path segment relative to self and each may contain multiple levels separated by posixpath.sep (/).

Parameters:: child (str)
Return type:: EmptyTraversable

property name: str¶: Return a dummy name.

open(mode='r', encoding='utf-8')[source]¶

Overloads:

self, mode (Literal[‘r’]), encoding (str | None) → io.StringIO
self, mode (Literal[‘rb’]) → io.BytesIO

mode may be ‘r’ or ‘rb’ to open as text or binary. Return a handle suitable for reading (same as pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

Parameters:

mode (Literal['r', 'rb'])
encoding (str | None)

read_bytes()[source]¶

Read contents of self as bytes

Return type:: bytes

read_text(encoding='utf-8')[source]¶

Read contents of self as text

Parameters:: encoding (str | None)
Return type:: str

class repo_review.ghpath.GHPath(*, repo, branch, path='', _info=<factory>, _fetched=<factory>)[source]¶

Bases: Traversable

This is a Traversable that can be used to navigate a GitHub repo without downloading it.

Will throw an KeyError if the response is not valid.

Parameters:

repo (str) – The repo name, in “org/repo” style.
branch (str) – The branch name. “HEAD” works too.
path (str) – A sub-path inside the repo. Defaults to the repo root.
_info (list[dict[str, str]]) – Some internal info stored to keep accesses fast.

Making new paths from this path will propagate the _fetched dict.

Parameters:: _fetched (dict[str, str])

async classmethod async_from_repo(repo, branch, path='')[source]¶

Async constructor that populates _info by fetching the GitHub tree using open_url_async instead of performing synchronous network IO in __post_init__.

Can throw a KeyError.

Parameters:

repo (str) – repository name in “org/repo” form
branch (str) – branch or ref to inspect
path (str) – optional path inside the repo

Return type:

Self

Returns:

A GHPath instance with _info populated

branch: str¶: The branch name.

glob(pattern)[source]¶

Yield paths matching the given glob-style pattern relative to this GHPath. Patterns support ** recursion via PurePosixPath.match.

Parameters:: pattern (str) – A glob pattern (e.g. "**/*.py" or "subdir/*.md").
Return type:: Iterator[GHPath]
Returns:: An iterator of GHPath instances matching the pattern.

is_dir()[source]¶

Return True if self is a directory

Return type:: bool

is_file()[source]¶

Return True if self is a file

Return type:: bool

iterdir()[source]¶

Yield Traversable objects in self

Return type:: Iterator[GHPath]

joinpath(child)[source]¶

Return Traversable resolved with any descendants applied.

Each descendant should be a path segment relative to self and each may contain multiple levels separated by posixpath.sep (/).

Parameters:: child (str)
Return type:: GHPath

property name: str¶: The final element of the path or the repo name.

open(mode='r', encoding='utf-8')[source]¶

Overloads:

self, mode (Literal[‘r’]), encoding (str | None) → io.StringIO
self, mode (Literal[‘rb’]) → io.BytesIO

Open the repo. This doesn’t support the full collection of options, only utf-8 and binary.

Parameters:

mode (Literal['r', 'rb']) – The mode, only "r" or "rb" supported.
encoding (str | None) – The encoding, only "utf-8" or None supported.

static open_url(url)[source]¶

This method can be overridden manually for WASM. Supports pyodide currently.

Parameters:: url (str)
Return type:: str

async static open_url_async(url)[source]¶

This method can be overridden manually for WASM. Supports pyodide currently.

Parameters:: url (str)
Return type:: str

path: str = ''¶: A path inside the repo

async prefetch()[source]¶

Prefetch a file. If the file doesn’t exist, this does nothing.

Return type:: None

read_bytes()[source]¶

Read contents of self as bytes

Return type:: bytes

read_text(encoding='utf-8')[source]¶

Read contents of self as text

Parameters:: encoding (str | None)
Return type:: str

repo: str¶: The repository name, in “org/repo” style.

repo_review.html module¶

repo_review.html.to_html(families, processed, status='empty')[source]¶

Convert the results of a repo review (families, processed) to HTML.

Parameters:

families (Mapping[str, Family]) – The family mapping.
processed (Sequence[Result]) – The list of processed results.
status (Literal['empty', 'passed', 'skips', 'errors']) – A string indicating the reason behind being empty. Will assume no checks ran if not given. This is only needed if you are filtering the results before calling this function.

Return type:

str

repo_review.processor module¶

class repo_review.processor.CollectionReturn(fixtures: dict[str, Any], checks: dict[str, Check], families: dict[str, Family])[source]¶

Bases: NamedTuple

Return type for collect_all().

Added in version 0.8.

Parameters:

fixtures (dict[str, Any])
checks (dict[str, Check])
families (dict[str, Family])

checks: dict[str, Check]¶: The checks dict, sorted by Family.

families: dict[str, Family]¶: A mapping of family strings to Family info dicts

fixtures: dict[str, Any]¶: The computed fixtures, as a dict

class repo_review.processor.ProcessReturn(families: dict[str, Family], results: list[Result])[source]¶

Bases: NamedTuple

Return type for process().

Parameters:

families (dict[str, Family])
results (list[Result])

families: dict[str, Family]¶: A mapping of family strings to Family info dicts

results: list[Result]¶: The results list

class repo_review.processor.Result(*, family, name, description, result, skip_reason='', err_msg='', url='')[source]¶

Bases: object

This is the returned value from a processed check.

Parameters:

family (str)
name (str)
description (str)
result (bool | None)
skip_reason (str)
err_msg (str)
url (str)

description: str¶: The short description of what the check looks for

err_as_html()[source]¶

Produces HTML from the error message, assuming it is in markdown. Deprecated, use md_as_html() directly instead.

Return type:: str

err_msg: str = ''¶: The error message if the result is false, in markdown format

family: str¶: The family string

md_as_html()[source]¶

Process fields that are assumed to be markdown.

Added in version 0.12.1.

Return type:: Self

name: str¶: The name of the check

result: bool | None¶: The result, None means skip

skip_reason: str = ''¶: The reason for the skip, if given

url: str = ''¶: An optional URL (empty string if missing)

class repo_review.processor.ResultDict[source]¶

Bases: TypedDict

Helper to get the type in the JSON style returns. Basically identical to Result but in dict form and without the name.

description: str¶: The short description of what the check looks for

err_msg: str¶: The error message if the result is false, in markdown format

family: str¶: The family string

result: bool | None¶: The result, None means skip

skip_reason: str¶: The reason for the skip, if given (empty string if not)

url: str¶: An optional URL (empty string if missing)

repo_review.processor.as_simple_dict(results)[source]¶

Convert a results list into a simple dict of dicts structure. The name of the result turns into the key of the outer dict.

Parameters:: results (list[Result]) – The list of results.
Return type:: dict[str, ResultDict]

repo_review.processor.collect_all(root=None, subdir='')¶

Collect all checks. If root is not passed or None, then checks are collected with a EmptyTraversable. Any checks that are returned conditionally based on fixture results might not be collected unless list_all() is used.

Parameters:

root (Traversable | None) – If passed, this is the root of the repo (for fixture computation). None will use EmptyTraversable.
subdir (str) – The subdirectory (for fixture computation).

Return type:

CollectionReturn

Returns:

The collected fixtures, checks, and families. Families is guaranteed to include all families and be in order.

Added in version 0.8.

Changed in version 1.0: Now None is supported.

repo_review.processor.md_as_html(md_text)[source]¶

Heler function that converts markdown text to HTML. Strips paragraph tags from the result.

Parameters:: md_text (str) – The markdown text to convert.
Return type:: str

repo_review.processor.process(root, *, select=frozenset({}), ignore=frozenset({}), extend_select=frozenset({}), extend_ignore=frozenset({}), subdir='', collected=None)¶

Process the package and return a dictionary of results.

Parameters:

root (Traversable) – The Traversable to the repository to process.
select (Set[str]) – A list of checks to select. All checks selected if empty.
ignore (Set[str]) – A list of checks to ignore.
subdir (str) – The path to the package in the subdirectory, if not at the root of the repository.
collected (CollectionReturn | None) – The return from a collection run. Skips collecting checks and rerunning fixtures if given.
extend_select (Set[str])
extend_ignore (Set[str])

Return type:

ProcessReturn

Returns:

The families and a list of checks. Families is guaranteed to include all families and be in order.

repo_review.schema module¶

This accesses the schema for repo-review’s tool section.

repo_review.schema.get_schema(tool_name='repo-review')[source]¶

Get the stored complete schema for repo-review settings.

Parameters:: tool_name (str)
Return type:: dict[str, Any]

repo_review.testing module¶

Helpers for testing repo-review plugins.

repo_review.testing.compute_check(name, /, **fixtures)[source]¶

A helper function to compute a check given fixtures, intended for testing. Currently, all fixtures are required to be passed in as keyword arguments, transitive fixtures are not supported.

Parameters:

name (str) – The name of the check to compute.
fixtures (Any) – The fixtures to use when computing the check.

Return type:

Result

Returns:

The computed result.

Added in version 0.10.5.

repo_review.testing.toml_loads(contents, /)[source]¶

A helper function to quickly load a TOML string for Python 3.10+.

Parameters:: contents (str) – The TOML string to load.
Return type:: Any
Returns:: The loaded TOML.

Added in version 0.10.6.