fake-api-server.ci.surveillance.model.config.github

This module provides classes and methods for managing and deserializing GitHub-related data structures, including pull requests and their associated information.

GitHubInfo(pull_request) dataclass

Bases: _BaseModel

Represents GitHub-related information within a system model.

This class encapsulates the GitHub-related information, including details about pull requests. It provides a method to deserialize data from a mapping structure into an instance of the class for further use.

ATTRIBUTE	DESCRIPTION
pull_request	Encapsulates the details of a GitHub pull request. TYPE: PullRequestInfo

PullRequestInfo(title=str(), body=str(), draft=False, labels=list(), change_detail=ChangeDetail(), _NO_API_CHANGE_CONTENT='No changes.') dataclass

Bases: _BaseModel

Represents information related to a pull request, including metadata such as title, body, labels, and draft status, as well as details of the changes it encompasses.

This class encapsulates details of a pull request, such as its title, body description, whether it be marked as a draft or not, and associated labels. It can be used for creating or processing pull requests programmatically. The deserialize method allows reconstructing an instance of this class from a dictionary-like mapping, supporting specific use cases related to mappings and configuration items.

ATTRIBUTE	DESCRIPTION
title	The title of the pull request. TYPE: str
body	The body content of the pull request. TYPE: str
draft	Indicates if the pull request is marked as a draft. TYPE: bool
labels	List of labels associated with the pull request. TYPE: List[str]
change_detail	An object containing statistical and summary details of API changes. This property is new in version 0.2.0. TYPE: ChangeDetail

default_pr_body() classmethod

Generates and returns a default pull request body from a file.

This method reads the content of a Markdown file named pr-body.md located within a _static directory inside the surveillance directory of the project's file system structure. The _find_surveillance_lib_path helper function navigates through the file path hierarchy to locate the surveillance directory. If the pr-body.md file is not found in the expected path, an assertion is raised.

The returned content of the file can be used as a template for pull request bodies.

This function is new in version 0.2.0.

RETURNS	DESCRIPTION
str	The content of the pr-body.md file as a string representing the default pull request body.

RAISES	DESCRIPTION
AssertionError	If the default pull request body file (pr-body.md) is not found at the expected path.

Source code in fake_api_server_plugin/ci/surveillance/model/config/github.py

@classmethod
def default_pr_body(cls) -> str:
    """
    Generates and returns a default pull request body from a file.

    This method reads the content of a Markdown file named `pr-body.md` located within
    a `_static` directory inside the `surveillance` directory of the project's
    file system structure. The `_find_surveillance_lib_path` helper function navigates
    through the file path hierarchy to locate the `surveillance` directory. If the
    `pr-body.md` file is not found in the expected path, an assertion is raised.

    The returned content of the file can be used as a template for pull request bodies.

    !!! tip ""

        This function is new in version 0.2.0.

    :raises AssertionError: If the default pull request body file (`pr-body.md`) is
                            not found at the expected path.

    :return: The content of the `pr-body.md` file as a string representing
             the default pull request body.
    :rtype: str
    """

    def _find_surveillance_lib_path(_path: pathlib.Path) -> pathlib.Path:
        if _path.name == "surveillance":
            return _path
        return _find_surveillance_lib_path(_path.parent)

    surveillance = _find_surveillance_lib_path(pathlib.Path(os.path.abspath(__file__)))
    default_pr_body_md_file = pathlib.Path(surveillance, "_static", "pr-body.md")
    assert os.path.exists(default_pr_body_md_file), "Default PR body file not found."
    with open(str(default_pr_body_md_file), "r") as file_stream:
        return file_stream.read()

set_change_detail(change_detail)

Updates the body of the content based on the provided change details, altering it to reflect the statistical changes and API summary. Existing placeholders in the body are replaced with the relevant information derived from the change_detail object.

This function is new in version 0.2.0.

PARAMETER	DESCRIPTION
change_detail	Contains statistical and summary details of API changes that are used to update the body content. TYPE: ChangeDetail

RETURNS	DESCRIPTION
None	None

Source code in fake_api_server_plugin/ci/surveillance/model/config/github.py

def set_change_detail(self, change_detail: ChangeDetail) -> None:
    """
    Updates the body of the content based on the provided change details, altering it to
    reflect the statistical changes and API summary. Existing placeholders in the body
    are replaced with the relevant information derived from the `change_detail` object.

    !!! tip ""

        This function is new in version 0.2.0.

    :param change_detail: Contains statistical and summary details of API changes that are
        used to update the body content.
    :type change_detail: ChangeDetail

    :return: None
    """
    new_body = self.body

    # Process the details - statistics
    new_body = new_body.replace("{{ NEW_API_NUMBER }}", str(change_detail.statistical.add))
    new_body = new_body.replace("{{ CHANGE_API_NUMBER }}", str(change_detail.statistical.update))
    new_body = new_body.replace("{{ DELETE_API_NUMBER }}", str(change_detail.statistical.delete))

    # Process the details - summary
    for api_path, api_methods in change_detail.summary.add.items():
        new_body = new_body.replace("{{ ADD_API_SUMMARY }}", self._api_change_list(api_path, api_methods))
    for api_path, api_methods in change_detail.summary.update.items():
        new_body = new_body.replace("{{ CHANGE_API_SUMMARY }}", self._api_change_list(api_path, api_methods))
    for api_path, api_methods in change_detail.summary.delete.items():
        new_body = new_body.replace("{{ DELETE_API_SUMMARY }}", self._api_change_list(api_path, api_methods))

    new_body = new_body.replace("{{ ADD_API_SUMMARY }}", self._NO_API_CHANGE_CONTENT)
    new_body = new_body.replace("{{ CHANGE_API_SUMMARY }}", self._NO_API_CHANGE_CONTENT)
    new_body = new_body.replace("{{ DELETE_API_SUMMARY }}", self._NO_API_CHANGE_CONTENT)

    self.body = new_body