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.