github_rest_api 0.26.0__tar.gz

github_rest_api-0.26.0/.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+.idea/
+.theia/
+.vscode/
+*.ipr
+*.iws
+.ipynb_checkpoints/
+.coverage
+.mypy/
+.mypy_cache/
+.pytype/
+*.crc
+__pycache__/
+venv/
+.venv/
+target/
+dist/
+*.egg-info/
+doc*/_build/
+*.prof
+core

github_rest_api-0.26.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: github_rest_api
+Version: 0.26.0
+Summary: Simple wrapper of GitHub REST APIs.
+Author-email: Ben Du <longendu@yahoo.com>
+Requires-Python: <4,>=3.11
+Requires-Dist: psutil>=5.9.4
+Requires-Dist: requests>=2.28.2
+Description-Content-Type: text/markdown
+
+# GitHub REST APIs  |  [@GitHub](https://github.com/legendu-net/github_rest_api)  |  [@PyPI](https://pypi.org/project/github-rest-api/)
+
+Simple wrapper of GitHub REST APIs with a focus on making GitHub Actions automation easy.

github_rest_api-0.26.0/README.md

@@ -0,0 +1,3 @@
+# GitHub REST APIs  |  [@GitHub](https://github.com/legendu-net/github_rest_api)  |  [@PyPI](https://pypi.org/project/github-rest-api/)
+
+Simple wrapper of GitHub REST APIs with a focus on making GitHub Actions automation easy.

github_rest_api-0.26.0/github_rest_api/__init__.py

@@ -0,0 +1,5 @@
+"""GitHub REST APIs."""
+
+from .github import Organization, Repository, RepositoryType
+
+__all__ = ["Organization", "Repository", "RepositoryType"]

github_rest_api-0.26.0/github_rest_api/actions/__init__.py

@@ -0,0 +1 @@
+"""GitHub Actions related utils."""

github_rest_api-0.26.0/github_rest_api/actions/cargo/benchmark.py

@@ -0,0 +1,253 @@
+"""Benchmark action using cargo criterion."""
+
+from typing import Callable
+import tempfile
+from pathlib import Path
+import datetime
+import shutil
+from ..utils import (
+    config_git,
+    create_branch,
+    switch_branch,
+    push_branch,
+    gen_temp_branch,
+    commit_benchmarks,
+)
+from ...utils import run_cmd
+
+
+def _copy_last_dev_bench(bench_dir: Path) -> None:
+    branch = gen_temp_branch()
+    create_branch(branch)
+    switch_branch(branch="gh-pages", fetch=True)
+    src = bench_dir / "dev/criterion"
+    tmpdir = tempfile.mkdtemp()
+    if src.is_dir():
+        shutil.copytree(src, tmpdir, dirs_exist_ok=True)
+    switch_branch(branch=branch, fetch=False)
+    target = Path("target/criterion")
+    target.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(tmpdir, target, dirs_exist_ok=True)
+
+
+def _cargo_criterion(bench_dir: Path, env: str = "") -> None:
+    """Run `cargo criterion` to benchmark the specified branch.
+    Notice that a temp branch is created for benchmarking.
+
+    :param branch: The branch to benchmark.
+    """
+    _copy_last_dev_bench(bench_dir=bench_dir)
+    run_cmd(f"{env} cargo criterion --all-features --message-format=json")
+
+
+def _copy_bench_results(bench_dir: Path, storage: str) -> None:
+    """Copy benchmark results into the right directory of the gh-pages branch.
+    :param bench_dir: The root benchmark directory
+    (under the gh-pages branch).
+    :param storage: The directory relative to bench_dir for storing this benchmark results.
+    """
+    switch_branch("gh-pages", fetch=True)
+    src = Path("target/criterion")
+    dst = bench_dir / storage / "criterion"
+    dst.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, dst, dirs_exist_ok=True)
+
+
+def _git_push_gh_pages(bench_dir: Path, pr_number: str) -> str:
+    """Push benchmark results to a branch
+    with the pattern gh-pages_{pr_number}_yyyymmdd_HHMMSS.
+    :param bench_dir: The root benchmark directory
+    (under the gh-pages branch).
+    :return: The name of the pushed branch.
+    """
+    commit_benchmarks(bench_dir=bench_dir)
+    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    branch = f"gh-pages_{pr_number}_{timestamp}"
+    create_branch(branch=branch)
+    push_branch(branch=branch)
+    return branch
+
+
+def _rename_bench_reports(dirs: list[Path]):
+    for dir_ in dirs:
+        for path in dir_.glob("**/history.html"):
+            path.rename(path.with_name("index.html"))
+
+
+def _parse_metric_ci(path: str | Path) -> tuple[str, str, str]:
+    if isinstance(path, str):
+        path = Path(path)
+    if path.is_dir():
+        path = path / "index.html"
+    with path.open(encoding="utf-8") as fin:
+        lines = fin.readlines()
+
+    def _find_start_line(lines: list[str]) -> int | None:
+        for i, line in enumerate(lines):
+            if "Change in Value:" in line:
+                return i
+        return None
+
+    def _extract_value_from_line(line: str):
+        start = line.find(">")
+        if start == -1:
+            return "0"
+        end = line.find("<", start + 1)
+        if end == -1:
+            return "0"
+        return line[start + 1 : end].strip()
+
+    start = _find_start_line(lines)
+    if start is None:
+        return ("0", "0", "0")
+    lower = _extract_value_from_line(lines[start + 1])
+    middle = _extract_value_from_line(lines[start + 2])
+    upper = _extract_value_from_line(lines[start + 3])
+    return (lower, middle, upper)
+
+
+def _gen_report_links_markdown(
+    dir_: str | Path, extract_benchmark_name: Callable
+) -> str:
+    if isinstance(dir_, str):
+        dir_ = Path(dir_)
+    paths = (dir_ / "criterion/reports").iterdir()
+    paths = list(path for path in paths if path.is_dir())
+    paths.sort()
+    cips = [(_parse_metric_ci(p), p) for p in paths]
+    links = "\n".join(
+        _gen_report_link_markdown(cip, extract_benchmark_name) for cip in cips
+    )
+    links_sorted = "\n".join(
+        _gen_report_link_markdown(cip, extract_benchmark_name)
+        for cip in _sort_cips(cips)
+    )
+    return f"""## {dir_} - Sorted By Performance Change
+{links_sorted}
+## {dir_} - Sorted By Name
+{links}
+"""
+
+
+def _gen_report_link_markdown(
+    cip: tuple[tuple[str, str, str], Path], extract_benchmark_name: Callable
+) -> str:
+    ci, p = cip
+
+    def _gen_link_md(path: Path):
+        text = extract_benchmark_name(path)
+        path = "/".join(path.parts[1:])
+        link = f"{path}/index.html"
+        return f"[{text}]({link})"
+
+    return f"- {_gen_report_ci_markdown(ci)}  {_gen_link_md(p)}"
+
+
+def _gen_report_ci_markdown(ci: tuple[str, str, str]) -> str:
+    lower, middle, upper = ci
+
+    def _significance(lower: str, middle: str, upper: str) -> int:
+        def _reg_value(value: str):
+            return float(value.strip("%").strip())
+
+        lower = _reg_value(lower)
+        middle = _reg_value(middle)
+        upper = _reg_value(upper)
+        if abs(middle) < 1:
+            return 0
+        if lower < 0 and upper < 0:
+            return -1
+        if lower > 0 and upper > 0:
+            return 1
+        return 0
+
+    color = {0: "black", -1: "green", 1: "red"}[_significance(lower, middle, upper)]
+    return f'<span style="color:{color}"> [{lower}, <b>{middle}</b>, {upper}] </span>'
+
+
+def _sort_cips(
+    cips: list[tuple[tuple[str, str, str], Path]],
+) -> list[tuple[tuple[str, str, str], Path]]:
+    """Sort confidence intervals according to the average performance changes."""
+
+    def _avg_perf_change(elem: tuple[tuple[str, str, str], Path]) -> float:
+        perf_change = elem[0][1]
+        return -float(perf_change.replace("%", "").strip())
+
+    return sorted(cips, key=_avg_perf_change)
+
+
+def _clean_bench_dirs(bench_dir: Path, history: int) -> list[Path]:
+    dirs = sorted(bench_dir.glob("[1-9]*/"))
+    for path in dirs[:-history]:
+        shutil.rmtree(path)
+    dirs = dirs[-history:]
+    dev = bench_dir / "dev"
+    if dev.is_dir():
+        dirs.append(dev)
+    return dirs
+
+
+def _gen_markdown(dirs: list[Path], extract_benchmark_name) -> str:
+    sections = "\n".join(
+        _gen_report_links_markdown(dir_, extract_benchmark_name)
+        for dir_ in reversed(dirs)
+    )
+    return f"# Benchmarks\n{sections}\n"
+
+
+def gen_index_markdown(
+    bench_dir: str | Path = "bench",
+    history: int = 1,
+    extract_benchmark_name: Callable[[Path], str] = lambda path: path.stem,
+) -> None:
+    """Generate index.md under the benchmark directory.
+    :param bench_dir: The root benchmark directory (under the gh-pages branch).
+    :param history: The number of historical benchmark results to keep.
+    :param extract_benchmark_name: A function to extract a benchmark name from a path.
+    """
+    if isinstance(bench_dir, str):
+        bench_dir = Path(bench_dir)
+    dirs = _clean_bench_dirs(bench_dir=bench_dir, history=history)
+    _rename_bench_reports(dirs)
+    (bench_dir / "index.md").write_text(
+        _gen_markdown(dirs, extract_benchmark_name), encoding="utf-8"
+    )
+
+
+def benchmark(
+    local_repo_dir: str | Path,
+    pr_number: str,
+    bench_dir: str | Path = "bench",
+    storage: str = "",
+    extract_benchmark_name: Callable[[Path], str] = lambda path: path.stem,
+    env: str = "",
+) -> str:
+    """Benchmark using `cargo criterion` and push benchmark results to gh-pages.
+
+    :param local_repo_dir: Root directory of the local repository.
+    :param pr_number: The number of the corresponding PR.
+    :param bench_dir: The root benchmark directory (under the gh-pages branch).
+    :param storage: The directory relative to bench_dir for storing this benchmark results.
+    If not specified (empty or None), pr_number is used.
+    :param extract_benchmark_name: A function to extract a benchmark name from a path.
+    :param env: Environment variables configuration with the format `var1=val1 var2=val2`
+    for the command `cargo-criterion`).
+    """
+    if isinstance(bench_dir, str):
+        bench_dir = Path(bench_dir)
+    if not storage:
+        storage = pr_number
+    config_git(
+        local_repo_dir=local_repo_dir,
+        user_email="bench-bot@github.com",
+        user_name="bench-bot",
+    )
+    _cargo_criterion(bench_dir=bench_dir, env=env)  # _branch_*
+    _copy_bench_results(bench_dir=bench_dir, storage=storage)  # gh-pages
+    gen_index_markdown(
+        bench_dir=bench_dir, history=1, extract_benchmark_name=extract_benchmark_name
+    )
+    return _git_push_gh_pages(
+        bench_dir=bench_dir, pr_number=pr_number
+    )  # gh-pages_pr_yyyymmdd_hhmmss

github_rest_api-0.26.0/github_rest_api/actions/cargo/profiling.py

@@ -0,0 +1,126 @@
+"""Utils for profiling Rust applications."""
+
+from typing import Iterable
+from pathlib import Path
+import time
+import datetime
+import subprocess as sp
+import psutil
+from .utils import build_project
+from ..utils import config_git, switch_branch, push_branch, commit_profiling
+from ...utils import partition, run_cmd
+
+
+def launch_application(cmd: list[str]) -> int:
+    """Launch the application to be profiled and return the pid of the process.
+    Notice that this works inside Docker containers too.
+    """
+    print(
+        "Launched application for profiling at ",
+        datetime.datetime.now(),
+        " using the following command:\n",
+        "    sp.Popen(cmd, stdout=sp.PIPE, stderr=sp.PIPE)\n",
+        "where cmd is as below:\n    ",
+        cmd,
+        "\n",
+        sep="",
+    )
+    proc = sp.Popen(cmd, stdout=sp.DEVNULL, stderr=sp.PIPE)  # pylint: disable=R1732
+    time.sleep(3)
+    status = proc.poll()
+    if status:
+        _, stderr = proc.communicate()
+        stderr = b"" if stderr is None else stderr
+        raise RuntimeError(
+            f"The launched application failed with the error code {status}!\n"
+            f"Stderr:\n{stderr.decode()}\n"
+        )
+    if status == 0:
+        raise ValueError(
+            "The launched application has already finished! "
+            "Please use a long running command instead."
+        )
+    return _find_process_id(proc)
+
+
+def _find_process_id(proc: sp.Popen) -> int:
+    pids = []
+    for process in psutil.process_iter():
+        if process.cmdline() == proc.args:
+            pids.append(process.pid)
+    return min(pids, key=lambda pid: abs(pid - proc.pid))
+
+
+def nperf(pid: int, prof_name: str, prof_dir: str | Path = ".") -> Path:
+    """Profile the given process using nperf (not-perf).
+    :param pid: The id of the process to be profiled.
+    :param prof_name: The name of the profiling.
+    :param prof_dir: The directory (the current working directory by default)
+    for saving profiling data.
+    """
+    if isinstance(prof_dir, str):
+        prof_dir = Path(prof_dir)
+    time = datetime.datetime.now()
+    yymmdd = time.strftime("%Y%m%d")
+    prof_dir.mkdir(exist_ok=True, parents=True)
+    data_file = prof_dir / f"{yymmdd}_{prof_name}"
+    run_cmd(f"nperf record -p {pid} -o '{data_file}'")
+    return _gen_flamegraph(data_file)
+
+
+def _gen_flamegraph(data_file: Path) -> Path:
+    flamegraph = data_file.with_name(data_file.name + ".svg")
+    run_cmd(f"nperf flamegraph '{data_file}' > '{flamegraph}'")
+    return flamegraph
+
+
+def _save_flamegraph(prof_dir: Path, history: int = 5):
+    yyyymmdd = (datetime.datetime.today() - datetime.timedelta(days=history)).strftime(
+        "%Y%m%d"
+    )
+    switch_branch("gh-pages", fetch=True)
+    for path in prof_dir.iterdir():
+        if path.suffix == "":
+            path.unlink()
+    svgs_keep, svgs_drop = partition(
+        lambda p: p.name > yyyymmdd, prof_dir.glob("*.svg")
+    )
+    for svg in svgs_drop:
+        svg.unlink()
+    _gen_markdown(svgs=sorted(svgs_keep, reverse=True), prof_dir=prof_dir)
+    commit_profiling(prof_dir=prof_dir)
+    yyyymmdd = datetime.datetime.now().strftime("%Y%m%d")
+    push_branch(branch="gh-pages", branch_alt="gh-pages_prof_" + yyyymmdd)
+
+
+def _gen_markdown(svgs: Iterable[Path], prof_dir: Path) -> None:
+    def _gen_link(svg: Path):
+        svg: str = svg.name
+        yyyymmdd = svg[:8]
+        prof_name = svg[9:-4]
+        return f"- [{prof_name} - {yyyymmdd}]({svg})"
+
+    links = "\n".join(_gen_link(svg) for svg in svgs)
+    markdown = f"# Profiling\n{links}"
+    (prof_dir / "index.md").write_text(markdown, encoding="utf-8")
+
+
+def profiling(
+    local_repo_dir: str | Path,
+    apps: dict[str, list[str]],
+    profile: str = "release",
+    prof_dir: str | Path = "profiling",
+):
+    """Profiling specified applications."""
+    if isinstance(prof_dir, str):
+        prof_dir = Path(prof_dir)
+    config_git(
+        local_repo_dir=local_repo_dir,
+        user_email="profiling-bot@github.com",
+        user_name="profiling-bot",
+    )
+    build_project(profile=profile)
+    for name, cmd in apps.items():
+        pid = launch_application(cmd=cmd)
+        nperf(pid=pid, prof_name=name, prof_dir=prof_dir)
+    _save_flamegraph(prof_dir=prof_dir)

github_rest_api-0.26.0/github_rest_api/actions/cargo/utils.py

@@ -0,0 +1,10 @@
+"""Util functions for building GitHub Actions for Rust projects."""
+
+from ...utils import run_cmd
+
+
+def build_project(profile: str = "release") -> None:
+    """Build the Rust project.
+    :param profile: The profile for building.
+    """
+    run_cmd(f"RUSTFLAGS=-Awarnings cargo build --profile {profile}")

github_rest_api-0.26.0/github_rest_api/actions/utils.py

@@ -0,0 +1,92 @@
+"""Util functions for GitHub actions."""
+
+from typing import Iterable
+from pathlib import Path
+import random
+from ..utils import run_cmd
+
+
+class FailToPushToGitHubException(Exception):
+    """Exception for failure to push a branch to GitHub."""
+
+    def __init__(self, branch: str, branch_alt: str):
+        msg = f"Failed to push the branch {branch} to GitHub!"
+        if branch_alt:
+            msg += f" Pushed to {branch_alt} instead."
+        super().__init__(msg)
+
+
+def config_git(local_repo_dir: str | Path, user_email: str, user_name: str):
+    """Config Git.
+    :param local_repo_dir: The root directory of the project.
+    :param user_email: The email of the user (no need to be a valid one).
+    :param user_name: The name of the user.
+    """
+    cmd = f"""git config --global --add safe.directory {local_repo_dir} \
+            && git config --global user.email "{user_email}" \
+            && git config --global user.name "{user_name}"
+        """
+    run_cmd(cmd)
+
+
+def create_branch(branch: str) -> None:
+    """Create a new local branch.
+    :param branch: The new local branch to create.
+    """
+    run_cmd(f"git checkout -b {branch}")
+
+
+def switch_branch(branch: str, fetch: bool) -> None:
+    """Switch to another branch.
+    :param branch: The branch to checkout.
+    :param fetch: If true, fetch the branch from remote first.
+    """
+    if fetch:
+        run_cmd(f"git fetch origin {branch}")
+    run_cmd(f"git checkout {branch}")
+
+
+def gen_temp_branch(
+    prefix: str = "_branch_", chars: Iterable[str | int] = range(10), nrand: int = 10
+) -> str:
+    """Generate a name for a (temp) branch.
+    :param prefix: The prefix of the name.
+    :param chars: An iterable of characters to sample from to form the suffix of the name.
+    :param nrand: The number of characters for the suffix of the name.
+    """
+    if not isinstance(chars, (list, tuple)):
+        chars = list(chars)
+    chars = random.sample(chars, nrand)
+    return prefix + "".join(str(char) for char in chars)
+
+
+def push_branch(branch: str, branch_alt: str = ""):
+    """Try pushing a local Git branch to remote.
+    On failure, fork an alternative branch (if specified) and push it to GitHub.
+    :param branch: The local branch to push to GitHub.
+    :param branch_alt: An alternative branch name to push to GitHub.
+    """
+    try:
+        run_cmd(f"git push origin {branch}")
+    except Exception as err:
+        if branch_alt:
+            cmd = f"""git checkout {branch} \
+                && git checkout -b {branch_alt} \
+                && git push origin {branch_alt}
+                """
+            run_cmd(cmd)
+        raise FailToPushToGitHubException(branch, branch_alt) from err
+
+
+def commit_benchmarks(bench_dir: str | Path):
+    """Commit changes in the benchmark directory.
+    :param bench_dir: The benchmark directory.
+    """
+    run_cmd(f"git add {bench_dir} && git commit -m 'add benchmarks'")
+
+
+def commit_profiling(prof_dir: str | Path):
+    """Commit changes in the profiling directory.
+    :param prof_dir: The profiling directory.
+    """
+    run_cmd(f"git add {prof_dir} && git commit -m 'update profiling results'")

github_rest_api-0.26.0/github_rest_api/github.py

@@ -0,0 +1,318 @@
+"""Simple wrapper of GitHub REST APIs."""
+
+from enum import StrEnum
+from typing import Any, Callable
+from pathlib import Path
+import requests
+
+
+def build_http_headers(token: str) -> dict[str, str]:
+    """Build headers for GitHub REST APIs.
+    :param token: The authentication token for GitHub REST APIs.
+    """
+    headers = {
+        "Accept": "application/vnd.github+json",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _is_rust(file: str) -> bool:
+    path = Path(file)
+    if path.name in ("Cargo.toml", "Cargo.lock"):
+        return True
+    if path.suffix == ".rs":
+        return True
+    return False
+
+
+class GitHub:
+    def __init__(self, token: str):
+        self._token = token
+        self._headers = build_http_headers(token)
+
+    def get(
+        self, url: str, raise_for_status: bool = True, **kwargs
+    ) -> requests.Response:
+        resp = requests.get(
+            url=url,
+            headers=self._headers,
+            timeout=10,
+            **kwargs,
+        )
+        if raise_for_status:
+            resp.raise_for_status()
+        return resp
+
+    def post(
+        self, url: str, headers=None, raise_for_status: bool = True, **kwargs
+    ) -> requests.Response:
+        if headers is None:
+            headers = self._headers
+        resp = requests.post(
+            url=url,
+            headers=headers,
+            timeout=10,
+            **kwargs,
+        )
+        if raise_for_status:
+            resp.raise_for_status()
+        return resp
+
+    def delete(self, url, raise_for_status: bool = True) -> requests.Response:
+        resp = requests.delete(url=url, headers=self._headers, timeout=10)
+        if raise_for_status:
+            resp.raise_for_status()
+        return resp
+
+    def put(self, url, raise_for_status: bool = True) -> requests.Response:
+        resp = requests.put(
+            url=url,
+            headers=self._headers,
+            timeout=10,
+        )
+        if raise_for_status:
+            resp.raise_for_status()
+        return resp
+
+
+class Repository(GitHub):
+    """Abstraction of a GitHub repository."""
+
+    def __init__(self, token: str, owner: str, repo: str):
+        """Initialize Repository.
+        :param token: An authorization token for GitHub REST APIs.
+        :param owner: The owner of the repository.
+        :param repo: The name of the repository.
+        """
+        super().__init__(token)
+        self._owner = owner
+        self._repo = repo
+        self._url_pull = f"https://api.github.com/repos/{owner}/{repo}/pulls"
+        self._url_branches = f"https://api.github.com/repos/{owner}/{repo}/branches"
+        self._url_refs = f"https://api.github.com/repos/{owner}/{repo}/git/refs"
+        self._url_issues = f"https://api.github.com/repos/{owner}/{repo}/issues"
+        self._url_releases = f"https://api.github.com/repos/{owner}/{repo}/releases"
+
+    def get_releases(self) -> list[dict[str, Any]]:
+        """List releases in this repository."""
+        return self.get(url=self._url_releases).json()
+
+    def get_release_latest(self) -> dict[str, Any]:
+        return self.get(url=f"{self._url_releases}/latest").json()
+
+    def get_release_assets(self, release: int) -> list[dict[str, Any]]:
+        return requests.get(url=f"{self._url_releases}/{release}/assets").json()
+
+    def create_release(self, json: dict[str, Any]):
+        """Create a release.
+
+        :param json: A dict containing the following info for the release.
+            - tag_name
+            - target_commitish
+            - name
+            - body
+            - draft
+            - prerelease
+            - generate_release_notes
+        It's passed to the json parameter of requests.post.
+        For more details, please refer to
+        https://docs.github.com/en/rest/releases/releases#create-a-release.
+        """
+        if not isinstance(json, dict):
+            raise ValueError("A dict value is required for `json`.")
+        return self.post(
+            url=self._url_releases,
+            json=json,
+        ).json()
+
+    def upload_release_asset(
+        self, release: int, name: str, path: str | Path
+    ) -> dict[str, Any]:
+        if isinstance(path, str):
+            path = Path(path)
+        with path.open(mode="rb") as fin:
+            return self.post(
+                url=f"{self._url_releases.replace('api', 'uploads', 1)}/{release}/assets",
+                params={
+                    "name": name,
+                },
+                headers=self._headers
+                | {
+                    "Content-Type": "application/octet-stream",
+                },
+                data=fin,
+            ).json()
+
+    def get_pull_requests(self) -> list[dict[str, Any]]:
+        """List pull requests in this repository."""
+        return self.get(url=self._url_pull).json()
+
+    def create_pull_request(self, json: dict[str, str]) -> dict[str, Any] | None:
+        """Create a pull request.
+
+        :param json: A dict containing info (e.g., base, head, title, body, etc.)
+        about the pull request to be created.
+        It's passed to the json parameter of requests.post.
+        """
+        if not isinstance(json, dict):
+            raise ValueError("A dict value is required for `json`.")
+        if not ("head" in json and "base" in json):
+            raise ValueError("The data dict must contains keys head and base!")
+        # return an existing PR
+        prs = self.get_pull_requests()
+        for pr in prs:
+            if pr["head"]["ref"] == json["head"] and pr["base"]["ref"] == json["base"]:
+                return pr
+        # creat a new PR
+        resp = self.post(
+            url=self._url_pull,
+            json=json,
+            raise_for_status=False,
+        )
+        if resp.status_code == 422:
+            return None
+        resp.raise_for_status()
+        return resp.json()
+
+    def merge_pull_request(self, pr_number: int) -> dict[str, Any]:
+        """Merge a pull request in this repository.
+        :param pr_number: The number of the pull quest to be merged.
+        """
+        if not isinstance(pr_number, int):
+            raise ValueError("An integer value is required for `pr_number`.")
+        return self.put(
+            url=f"{self._url_pull}/{pr_number}/merge",
+        ).json()
+
+    def update_branch(self, update: str, upstream: str) -> dict[str, Any] | None:
+        """Update a branch by creating a PR from upstream and then merge it.
+        :param update: The branch to update.
+        :param upstream: The upstream branch.
+        """
+        if not isinstance(update, str):
+            raise ValueError("A string value is required for `update`.")
+        if not isinstance(upstream, str):
+            raise ValueError("A string value is required for `upstream`.")
+        pr = self.create_pull_request(
+            {
+                "base": update,
+                "head": upstream,
+                "title": f"Merge {upstream} into {update}",
+            },
+        )
+        if pr is None:
+            return
+        return self.merge_pull_request(pr["number"])
+
+    def get_pull_request_files(self, pr_number: int) -> list[dict[str, Any]]:
+        """List changed files in the specified GitHub pull request.
+
+        :param pr_number: The number of the pull request.
+        """
+        if not isinstance(pr_number, int):
+            raise ValueError("An integer value is required for `pr_number`.")
+        return self.get(url=f"{self._url_pull}/{pr_number}/files").json()
+
+    def get_branches(self) -> list[dict[str, Any]]:
+        """List branches in this repository."""
+        return self.get(url=self._url_branches).json()
+
+    def delete_ref(self, ref: str) -> dict[str, Any]:
+        """Delete a reference from this repository.
+        :param ref: The reference to delete from this repository.
+        """
+        if not isinstance(ref, str):
+            raise ValueError("A string value is required for `ref`.")
+        return self.delete(
+            url=f"{self._url_refs}/{ref}",
+        ).json()
+
+    def delete_branch(self, branch: str) -> dict[str, Any]:
+        """Delete a branch from this repository.
+        :param branch: The branch to delete from this repository.
+        """
+        return self.delete_ref(ref=f"heads/{branch}")
+
+    def pr_has_change(
+        self, pr_number: int, pred: Callable[[str], bool] = lambda _: True
+    ) -> bool:
+        """Check whether a PR has any change satisfying pred.
+
+        :param pr_number: The number of the corresponding pull request.
+        :param pred: A boolean predictor (always true by default)
+        checking whether a single file has specific changes.
+        """
+        files = self.get_pull_request_files(pr_number)
+        return any(pred(file["filename"]) for file in files)
+
+    def pr_has_rust_change(
+        self, pr_number: int, pred: Callable[[str], bool] = _is_rust
+    ) -> bool:
+        """Check whether a PR has any Rust-related changes.
+
+        :param token: The authorization token for GitHub REST API.
+        :param pr_number: The number of the corresponding pull request.
+        :param pred: A customized boolean predictor checking Rust-related changes.
+        """
+        return self.pr_has_change(pr_number=pr_number, pred=pred)
+
+    def create_issue_comment(self, issue_number: int, body: str) -> dict[str, Any]:
+        """Add a new comment to an issue.
+
+        :param issue_number: The number of the issue.
+        :param body: Body text of the new comment.
+        """
+        if not isinstance(issue_number, int):
+            raise ValueError("An integer value is required for `issue_number`.")
+        if not isinstance(body, str):
+            raise ValueError("A string message is required for `body`.")
+        return self.post(
+            url=f"{self._url_issues}/{issue_number}/comments",
+            json={"body": body},
+            timeout=10,
+        ).json()
+
+
+class RepositoryType(StrEnum):
+    ALL = "all"
+    PUBLIC = "public"
+    PRIVATE = "private"
+
+
+class Organization(GitHub):
+    def __init__(self, token: str, owner: str):
+        """Initialize Repository.
+        :param token: An authorization token for GitHub REST APIs.
+        :param owner: The owner of the repository.
+        """
+        super().__init__(token)
+        self._owner = owner
+        self._url_repos = f"https://api.github.com/orgs/{owner}/repos"
+
+    def get_repositories(
+        self, type_: RepositoryType = RepositoryType.ALL
+    ) -> list[dict[str, Any]]:
+        """Get all accessible repositories.
+
+        :param type_: Type of repositories (e.g., public).
+        """
+        params = {
+            "type": type_,
+            "page": 1,
+            "per_page": 100,
+        }
+        repos = []
+        while True:
+            resp = self.get(url=self._url_repos, params=params)
+            resp.raise_for_status()
+            data = resp.json()
+            repos.extend(data)
+            if len(data) < params["per_page"]:  # ty: ignore[unsupported-operator]
+                return repos
+            params["page"] += 1  # ty: ignore[unsupported-operator]
+        return repos
+
+    def instantiate_repository(self, repo: str) -> Repository:
+        return Repository(token=self._token, owner=self._owner, repo=repo)

github_rest_api-0.26.0/github_rest_api/utils.py

@@ -0,0 +1,26 @@
+"""Some generally useful util functions."""
+
+from itertools import tee, filterfalse
+import logging
+import subprocess as sp
+
+
+def partition(pred, iterable):
+    """Use a predicate to partition entries into true entries and false entries.
+    :param pred: A function takes one parameter and return a boolean value.
+    :param iterable: An iterable of values to partition.
+    """
+    it1, it2 = tee(iterable)
+    return filter(pred, it1), filterfalse(pred, it2)
+
+
+def run_cmd(cmd: list | str, capture_output: bool = False) -> None:
+    """Run a shell command.
+
+    :param cmd: The command to run.
+    :param capture_output: Whether to capture stdout and stderr of the command.
+    """
+    proc = sp.run(
+        cmd, shell=isinstance(cmd, str), check=True, capture_output=capture_output
+    )
+    logging.debug(proc.args)

github_rest_api-0.26.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "github_rest_api"
+version = "0.26.0"
+description = "Simple wrapper of GitHub REST APIs."
+authors = [{ name = "Ben Du", email = "longendu@yahoo.com" }]
+requires-python = ">=3.11,<4"
+readme = "README.md"
+dependencies = [
+    "requests>=2.28.2",
+    "psutil>=5.9.4",
+]
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.407",
+    "ruff>=0.14.10",
+    "ty>=0.0.8",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["github_rest_api"]
+
+[tool.hatch.build.targets.wheel]
+include = ["github_rest_api"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"