rest_api¶

Everything cpp-linter needs to talk to a git server.

All network interaction is delegated to a git_bot_feedback.GitClient. This module only adds the cpp-linter specific bits: constants, the markdown comment/summary formats, and the assembly of PR reviews.

cpp_linter.rest_api.THREAD_COMMENT_LIMIT = 65535¶

The maximum length of a thread comment.

cpp_linter.rest_api.make_comment(files: list[FileObj], format_checks_failed: int, tidy_checks_failed: int, clang_versions: ClangVersions, len_limit: None | int = None) → str[source]¶

Make a markdown comment from the given advice.

Parameters:¶

files: list[FileObj]¶

A list of objects, each describing a file’s information.

format_checks_failed: int¶

The amount of clang-format checks that have failed.

tidy_checks_failed: int¶

The amount of clang-tidy checks that have failed.

clang_versions: ClangVersions¶

The versions of the clang tools used.

len_limit: None | int = None¶

The length limit of the comment generated.

Returns:¶

The markdown comment as a str

cpp_linter.rest_api.create_review_comments(files: list[FileObj], tidy_tool: bool, summary_only: bool, review_comments: ReviewComments, repo_root: str)[source]¶

Creates a batch of comments for a specific clang tool’s PR review.

Parameters:¶

files: list[FileObj]¶

The list of files to traverse.

tidy_tool: bool¶

A flag to indicate if the suggestions should originate from clang-tidy.

summary_only: bool¶

A flag to indicate if only the review summary is desired.

review_comments: ReviewComments¶

An object (passed by reference) that is used to store the results.

repo_root: str¶

The path that the files’ names are relative to.

cpp_linter.rest_api.make_annotations(files: list[FileObj], style: str, path_prefix: str = '') → list[FileAnnotation][source]¶

Create annotations from the clang tools’ advice.

Parameters:¶

path_prefix: str = ''¶

The path of the repo root inside the git repository (see ~cpp_linter.common_fs.get_repo_root_prefix()). Annotations use paths relative to the git repository.

class cpp_linter.rest_api.LinterClient(git_client: GitClient | None = None)[source]¶

A thin wrapper of git_bot_feedback.GitClient that knows how to deliver cpp-linter’s results.

Parameters:¶

git_client: GitClient | None = None¶

A client to delegate to. If not provided, then one is created (and configured with cpp-linter’s user agent).

repo_root_prefix : str¶

The path of the --repo-root inside the git repository (see ~cpp_linter.common_fs.get_repo_root_prefix()). The changed files and the feedback use it to convert between file names relative to the repo root and file names relative to the git repository.

workspace_root() → Path | None[source]¶

The CI workspace’s root folder, as the CI platform’s environment variable gives it (for example GITHUB_WORKSPACE).

Returns:¶

None when not running in a supported CI platform, or when the variable cannot be read.

property event_name : str¶

The triggering event type’s name.

property is_pr_event : bool¶

Is the triggering event a pull request?

property debug_enabled : bool¶

Are debug logs enabled on the CI runner?

property has_token : bool¶

Is the token required to post comments/reviews available?

property client_kind : str¶

The kind of git client (e.g., ‘local’, ‘github’, ‘gitea’).

async get_changed_files(file_filter: FileFilter, lines_changed_only: int, diff_base: None | int | str = None, ignore_index: bool = False) → list[FileObj][source]¶

Fetch a list of the event’s changed files.

Parameters:¶

file_filter: FileFilter¶

A git_bot_feedback.FileFilter to filter files.

lines_changed_only: int¶

A value that dictates what file changes to focus on.

diff_base: None | int | str = None¶

The commit or ref to use as the base of the diff.

ignore_index: bool = False¶

Setting this flag to True will ignore any staged changes in the index when producing a diff.

Returns:¶

The changed files, named relative to the repo root.

set_exit_code(checks_failed: int, format_checks_failed: int | None = None, tidy_checks_failed: int | None = None) → int[source]¶

Set the action’s output values and show them in the log output.

Returns:¶

The checks_failed parameter.

start_log_group(name: str)[source]¶

Start a log group in the CI runner’s output.

Parameters:¶

name: str¶

The name of the log group.

end_log_group(name: str)[source]¶

Start a log group in the CI runner’s output.

Parameters:¶

name: str¶

The name of the log group.

async post_feedback(files: list[FileObj], args: Args, clang_versions: ClangVersions) → int[source]¶

Post the results according to the user’s CLI options.

Parameters:¶

files: list[FileObj]¶

A list of objects, each describing a file’s information.

args: Args¶

A namespace of arguments parsed from the CLI.

clang_versions: ClangVersions¶

The version of the clang tools used.

Returns:¶

The total number of checks that failed.