saltext.github 1.1.0__py3-none-any.whl

saltext/github/utils/gh/repos.py

@@ -0,0 +1,465 @@
+"""
+Operations on GitHub repositories. Repository listing and creation are
+organization-scoped, everything else works on any owner's repositories.
+"""
+
+import base64
+import logging
+import time
+
+from github.GithubException import UnknownObjectException
+from salt.exceptions import CommandExecutionError
+
+from saltext.github.utils import filter_unset
+from saltext.github.utils.gh.cache import MISS
+from saltext.github.utils.gh.client import api_request
+from saltext.github.utils.gh.exceptions import GitHubNotFoundError
+
+log = logging.getLogger(__name__)
+
+
+def to_dict(repo):
+    """
+    Render a PyGithub ``Repository`` object into a plain dictionary,
+    excluding GitHub's deprecated alias fields (``watchers_count``,
+    ``watchers``, ``forks``, ``open_issues``).
+    """
+    ret = {}
+    ret["id"] = repo.id
+    ret["name"] = repo.name
+    ret["full_name"] = repo.full_name
+    ret["owner"] = repo.owner.login
+    ret["private"] = repo.private
+    ret["visibility"] = repo.visibility
+    ret["html_url"] = repo.html_url
+    ret["clone_url"] = repo.clone_url
+    ret["ssh_url"] = repo.ssh_url
+    ret["description"] = repo.description
+    ret["fork"] = repo.fork
+    ret["archived"] = repo.archived
+    ret["disabled"] = repo.disabled
+    ret["is_template"] = repo.is_template
+    ret["homepage"] = repo.homepage
+    ret["license"] = repo.license.spdx_id if repo.license else None
+    ret["topics"] = repo.topics
+    ret["custom_properties"] = repo.custom_properties
+    ret["size"] = repo.size
+    ret["stargazers_count"] = repo.stargazers_count
+    ret["language"] = repo.language
+    ret["forks_count"] = repo.forks_count
+    ret["open_issues_count"] = repo.open_issues_count
+    ret["default_branch"] = repo.default_branch
+    ret["created_at"] = repo.created_at.isoformat() if repo.created_at else None
+    ret["updated_at"] = repo.updated_at.isoformat() if repo.updated_at else None
+    ret["pushed_at"] = repo.pushed_at.isoformat() if repo.pushed_at else None
+    ret["has_discussions"] = repo.has_discussions
+    ret["has_downloads"] = repo.has_downloads
+    ret["has_issues"] = repo.has_issues
+    ret["has_pages"] = repo.has_pages
+    ret["has_projects"] = repo.has_projects
+    ret["has_wiki"] = repo.has_wiki
+    return ret
+
+
+@api_request
+def list_all(conn, *, owner=None, ignore_cache=False):
+    """
+    Return all repositories of an owner as PyGithub ``Repository``
+    objects (cached).
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    owner
+        Owner whose repositories to list. Defaults to the connection's
+        owner. Private repositories of users other than the
+        authenticated one are not visible.
+
+    ignore_cache
+        Bypass the cached repository list.
+    """
+    owner = owner or conn.owner
+    key = ("repos", owner.lower())
+    if key not in conn.cache or ignore_cache:
+        if conn.owner_type(owner) == "Organization":
+            found = conn.get_org(owner).get_repos()
+        elif conn.is_auth_user(owner):
+            # Listing the authenticated user's repos directly includes
+            # private ones, which /users/{owner}/repos does not carry.
+            found = conn.auth_user.get_repos(affiliation="owner")
+        else:
+            found = conn.client.get_user(owner).get_repos()
+        repos = []
+        for repo in found:
+            repos.append(repo)
+            # Cache a copy of each repo for single lookups
+            conn.cache[("repo_info", owner.lower(), repo.name.lower())] = to_dict(repo)
+        conn.cache[key] = repos
+    return conn.cache[key]
+
+
+@api_request
+def get_info(conn, name, *, owner=None, ignore_cache=False):
+    """
+    Return information about a single repository as a dictionary (cached).
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Repository name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    ignore_cache
+        Bypass the cached repository information.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if the repository does not exist.
+    """
+    owner = owner or conn.owner
+    key = ("repo_info", owner.lower(), name.lower())
+    if key not in conn.cache or ignore_cache:
+        try:
+            # With lazy fetching, client.get_repo returns a Repository object
+            # even if the repo does not exist - the exception is only raised
+            # once attributes of the object are accessed.
+            repo = conn.client.get_repo(f"{owner}/{name}")
+            conn.cache[key] = to_dict(repo)
+        except UnknownObjectException as exc:
+            raise GitHubNotFoundError(
+                f"The '{name}' repository belonging to '{owner}' could not be found.",
+                status=exc.status,
+                data=exc.data,
+            ) from exc
+    return conn.cache[key]
+
+
+def get_file_content(conn, name, path, *, owner=None, ignore_cache=False):
+    """
+    Return the decoded text content of a repository file via the
+    contents API, or ``None`` when the file is missing or unusable
+    (not a regular file, too large for the API to carry inline, not
+    valid UTF-8). Results are cached, including negative ones – also
+    persistently when the connection carries a store, validated against
+    the repository's ``pushed_at`` timestamp.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Repository name.
+
+    path
+        Path of the file inside the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    ignore_cache
+        Bypass the cached file content.
+    """
+    owner = owner or conn.owner
+    key = ("repo_file", owner.lower(), name.lower(), path)
+    if key in conn.cache and not ignore_cache:
+        return conn.cache[key]
+    content = MISS
+    pushed_at = None
+    if conn.store is not None:
+        pushed_at = _pushed_at(conn, name, owner)
+        if not ignore_cache:
+            content = conn.store.get_file(owner, name, path, pushed_at)
+    if content is MISS:
+        content = _fetch_file_content(conn, owner, name, path)
+        if conn.store is not None:
+            conn.store.set_file(owner, name, path, content, pushed_at)
+    conn.cache[key] = content
+    return content
+
+
+def _pushed_at(conn, name, owner):
+    """
+    Return a repository's last-push timestamp (from the cached repository
+    information, usually pre-warmed by a listing), or ``None`` when it
+    cannot be determined.
+    """
+    try:
+        return get_info(conn, name, owner=owner).get("pushed_at")
+    except CommandExecutionError:
+        return None
+
+
+def _fetch_file_content(conn, owner, name, path):
+    try:
+        res = conn.repo_query(owner, name, "contents", path)
+    except GitHubNotFoundError:
+        return None
+    if not isinstance(res, dict) or res.get("type") != "file":
+        log.warning("Path '%s' in %s/%s is not a file, skipping", path, owner, name)
+        return None
+    if res.get("encoding") != "base64":
+        log.warning(
+            "Cannot decode '%s' in %s/%s: unsupported encoding '%s'",
+            path,
+            owner,
+            name,
+            res.get("encoding"),
+        )
+        return None
+    try:
+        return base64.b64decode(res.get("content") or "").decode("utf-8")
+    except (ValueError, UnicodeDecodeError) as err:
+        log.warning("Failed decoding the content of '%s' in %s/%s: %s", path, owner, name, err)
+        return None
+
+
+def clear_file_cache(conn, name, *, owner=None):
+    """
+    Drop all cached file contents of one repository, including cached
+    negative lookups and persistently stored ones.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Repository name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    owner = owner or conn.owner
+    prefix = ("repo_file", owner.lower(), name.lower())
+    for key in [k for k in conn.cache if isinstance(k, tuple) and k[:3] == prefix]:
+        del conn.cache[key]
+    if conn.store is not None:
+        conn.store.flush_repo(owner, name)
+
+
+@api_request
+def get_teams(conn, name, *, owner=None):
+    """
+    Return the teams a repository belongs to.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Repository name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if the repository does not exist.
+    """
+    owner = owner or conn.owner
+    try:
+        repo = conn.client.get_repo(f"{owner}/{name}")
+        teams = repo.get_teams()
+        return [{"id": team.id, "name": team.name, "permission": team.permission} for team in teams]
+    except UnknownObjectException as exc:
+        raise GitHubNotFoundError(
+            f"The '{name}' repository belonging to '{owner}' could not be found.",
+            status=exc.status,
+            data=exc.data,
+        ) from exc
+
+
+@api_request
+def create(
+    conn,
+    name,
+    *,
+    owner=None,
+    description=None,
+    homepage=None,
+    private=None,
+    has_issues=None,
+    has_wiki=None,
+    has_downloads=None,
+    auto_init=None,
+    gitignore_template=None,
+    license_template=None,
+):
+    """
+    Create a new repository and wait for it to become visible.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Repository name to create.
+
+    owner
+        Owner to create the repository for. Defaults to the connection's
+        owner. The GitHub API only supports creating repositories
+        for organizations and the authenticated user.
+
+    description
+        Repository description.
+
+    homepage
+        URL with more information about the repository, e.g. rendered docs.
+
+    private
+        Repository visibility.
+
+    has_issues
+        Enable issues for this repository.
+
+    has_wiki
+        Enable the wiki for this repository.
+
+    has_downloads
+        Enable downloads for this repository.
+
+    auto_init
+        Create an initial commit with an empty README.
+
+    gitignore_template
+        Desired language or platform for a .gitignore, e.g. "Haskell".
+
+    license_template
+        Desired LICENSE template to apply, e.g. "mit" or "mozilla".
+    """
+    parameters = filter_unset(
+        {
+            "description": description,
+            "homepage": homepage,
+            "private": private,
+            "has_issues": has_issues,
+            "has_wiki": has_wiki,
+            "has_downloads": has_downloads,
+            "auto_init": auto_init,
+            "gitignore_template": gitignore_template,
+            "license_template": license_template,
+        }
+    )
+    owner = owner or conn.owner
+    if conn.owner_type(owner) == "Organization":
+        creator = conn.get_org(owner)
+    elif conn.is_auth_user(owner):
+        creator = conn.auth_user
+    else:
+        raise CommandExecutionError(
+            f"Cannot create a repository for '{owner}': the GitHub API only supports "
+            "creating repositories for organizations and the authenticated user."
+        )
+    repo = creator.create_repo(name, **parameters)
+
+    # Fetching a new repo's associations can 404 for a short while
+    # after creation, wait until it settles. User repos have no team
+    # associations, probe the repo itself there.
+    probe = get_teams if creator is not conn.auth_user else get_info
+    for attempt in range(3):
+        try:
+            probe(conn, name, owner=owner)
+            break
+        except GitHubNotFoundError:
+            log.info("Attempt %s to fetch new repo %s failed", attempt, name)
+            time.sleep(1)
+    else:
+        raise CommandExecutionError(f"Failed to verify repo {name} after creation.")
+
+    info = to_dict(repo)
+    conn.cache[("repo_info", owner.lower(), repo.name.lower())] = info
+    if ("repos", owner.lower()) in conn.cache:
+        conn.cache[("repos", owner.lower())].append(repo)
+    return info
+
+
+@api_request
+def update(
+    conn,
+    name,
+    *,
+    owner=None,
+    description=None,
+    homepage=None,
+    private=None,
+    has_issues=None,
+    has_wiki=None,
+    has_downloads=None,
+    default_branch=None,
+    allow_privacy_change=False,
+):
+    """
+    Update an existing repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Repository name to update.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    description
+        Repository description.
+
+    homepage
+        URL with more information about the repository, e.g. rendered docs.
+
+    private
+        Repository visibility. Changing this requires :ghconf:`allow_repo_privacy_changes`
+        to be enabled in the profile.
+
+    has_issues
+        Enable issues for this repository.
+
+    has_wiki
+        Enable the wiki for this repository.
+
+    has_downloads
+        Enable downloads for this repository.
+
+    default_branch
+        Default branch of the repository. Must already exist: Ignored during repo creation.
+
+    allow_privacy_change
+        Allow changing the repository's visibility. Defaults to false.
+    """
+    if private is not None and not allow_privacy_change:
+        raise CommandExecutionError(
+            f"The private field is set to be changed for repo {name} "
+            "but allow_repo_privacy_changes disallows this."
+        )
+    owner = owner or conn.owner
+    repo = conn.client.get_repo(f"{owner}/{name}")
+    parameters = filter_unset(
+        {
+            "description": description,
+            "homepage": homepage,
+            "private": private,
+            "has_issues": has_issues,
+            "has_wiki": has_wiki,
+            "has_downloads": has_downloads,
+            "default_branch": default_branch,
+        }
+    )
+    repo.edit(name, **parameters)
+    return get_info(conn, name, owner=owner, ignore_cache=True)  # Refresh cache
+
+
+@api_request
+def delete(conn, name, *, owner=None):
+    """
+    Delete a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Repository name to delete.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    owner = owner or conn.owner
+    repo = conn.client.get_repo(f"{owner}/{name}")
+    repo.delete()
+    conn.cache.pop(("repo_info", owner.lower(), name.lower()), None)
+    if ("repos", owner.lower()) in conn.cache:
+        list_all(conn, owner=owner, ignore_cache=True)  # Refresh the repo list cache

saltext/github/utils/gh/resource.py

@@ -0,0 +1,35 @@
+"""
+Shared plumbing for the :py:mod:`github <saltext.github.resources.github>`
+resource type's execution and state modules.
+
+The functions here reference loader globals (``__resource__``,
+``__salt__``, ``__opts__``, ``__context__``), so consuming modules must
+rebind them to their own namespace via
+:func:`salt.utils.functools.namespaced_function`::
+
+    from salt.utils.functools import namespaced_function
+
+    from saltext.github.utils.gh import resource as gh_resource
+
+    _core_args = namespaced_function(gh_resource.core_args, globals())
+"""
+
+from saltext.github.utils.gh import profile as gh_profile
+
+
+def core_args(profile=None):
+    """
+    Return a connection for the targeted repository, along with the
+    repository's owner and name.
+
+    Salt's authoring docs promise ``__resource__`` inside state
+    overrides, but no released Salt packs it there — in state modules,
+    fall back to the ``repo.ident`` execution override, which does see it.
+    """
+    try:
+        rid = __resource__["id"]
+    except NameError:
+        rid = __salt__["repo.ident"]()["id"]
+    owner, _, repo_name = rid.partition("/")
+    conn = gh_profile.resource_conn(__opts__, __context__, profile=profile, owner=owner)
+    return conn, owner, repo_name

saltext/github/utils/gh/rulesets.py

@@ -0,0 +1,191 @@
+"""
+Operations on GitHub repository and organization rulesets.
+"""
+
+import logging
+
+from salt.exceptions import CommandExecutionError
+
+log = logging.getLogger(__name__)
+
+
+def build_path(ruleset_type, *, owner=None, repo_name=None, org_name=None, ruleset_id=None):
+    """
+    Build the API path for ruleset operations.
+
+    ruleset_type
+        Ruleset type, either ``repo`` or ``org``.
+
+    owner
+        Owner of the repository. Required for ``repo`` rulesets
+        (the calling functions default it to the connection's owner).
+
+    repo_name
+        Repo name. Required for ``repo`` rulesets.
+
+    org_name
+        Org name. Required for ``org`` rulesets (the calling functions
+        default it to the connection's owner).
+
+    ruleset_id
+        ID of a specific ruleset to address.
+    """
+    if ruleset_type == "repo":
+        path = ["repos", owner, repo_name, "rulesets"]
+    elif ruleset_type == "org":
+        path = ["orgs", org_name, "rulesets"]
+    else:
+        raise CommandExecutionError(f"Invalid ruleset type: {ruleset_type}")
+    if ruleset_id is not None:
+        path.append(ruleset_id)
+    return path
+
+
+def check_params(ruleset_params, required=None):
+    """
+    Ensure a ruleset parameter payload is a mapping and contains all
+    required keys.
+
+    ruleset_params
+        Payload to check.
+
+    required
+        Optional set of parameter names that must be present.
+    """
+    if not isinstance(ruleset_params, dict):
+        raise CommandExecutionError("ruleset_params need to be a dict")
+    if required and (missing := set(required).difference(ruleset_params)):
+        raise CommandExecutionError(
+            f"The following ruleset_params are required, but not defined: {', '.join(missing)}"
+        )
+
+
+def list_all(
+    conn, ruleset_type, *, owner=None, repo_name=None, org_name=None, headers=None, per_page=None
+):
+    """
+    Return all rulesets of a repository or organization.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    Other parameters as described in :func:`build_path`. ``headers`` is a
+    mapping of extra headers to send.
+    """
+    path = build_path(
+        ruleset_type,
+        owner=owner or conn.owner,
+        repo_name=repo_name,
+        org_name=org_name or conn.owner,
+    )
+    return conn.query(path, headers=headers, per_page=per_page)
+
+
+def get(conn, ruleset_id, ruleset_type, *, owner=None, repo_name=None, org_name=None, headers=None):
+    """
+    Return the data of a specific ruleset.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    ruleset_id
+        ID of the ruleset to retrieve.
+
+    Other parameters as described in :func:`build_path`. ``headers`` is a
+    mapping of extra headers to send.
+    """
+    path = build_path(
+        ruleset_type,
+        owner=owner or conn.owner,
+        repo_name=repo_name,
+        org_name=org_name or conn.owner,
+        ruleset_id=ruleset_id,
+    )
+    return conn.query(path, headers=headers)
+
+
+def create(
+    conn, ruleset_params, ruleset_type, *, owner=None, repo_name=None, org_name=None, headers=None
+):
+    """
+    Create a new ruleset. Returns the data of the created ruleset.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    ruleset_params
+        Ruleset definition. Must contain at least ``name`` and ``enforcement``.
+
+    Other parameters as described in :func:`build_path`. ``headers`` is a
+    mapping of extra headers to send.
+    """
+    check_params(ruleset_params, required={"name", "enforcement"})
+    path = build_path(
+        ruleset_type,
+        owner=owner or conn.owner,
+        repo_name=repo_name,
+        org_name=org_name or conn.owner,
+    )
+    return conn.query(path, method="POST", data=ruleset_params, headers=headers)
+
+
+def update(
+    conn,
+    ruleset_id,
+    ruleset_params,
+    ruleset_type,
+    *,
+    owner=None,
+    repo_name=None,
+    org_name=None,
+    headers=None,
+):
+    """
+    Update an existing ruleset. Returns the data of the updated ruleset.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    ruleset_id
+        ID of the ruleset to update.
+
+    ruleset_params
+        Updated ruleset definition.
+
+    Other parameters as described in :func:`build_path`. ``headers`` is a
+    mapping of extra headers to send.
+    """
+    check_params(ruleset_params)
+    path = build_path(
+        ruleset_type,
+        owner=owner or conn.owner,
+        repo_name=repo_name,
+        org_name=org_name or conn.owner,
+        ruleset_id=ruleset_id,
+    )
+    return conn.query(path, method="PUT", data=ruleset_params, headers=headers)
+
+
+def delete(
+    conn, ruleset_id, ruleset_type, *, owner=None, repo_name=None, org_name=None, headers=None
+):
+    """
+    Delete a ruleset.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    ruleset_id
+        ID of the ruleset to delete.
+
+    Other parameters as described in :func:`build_path`. ``headers`` is a
+    mapping of extra headers to send.
+    """
+    path = build_path(
+        ruleset_type,
+        owner=owner or conn.owner,
+        repo_name=repo_name,
+        org_name=org_name or conn.owner,
+        ruleset_id=ruleset_id,
+    )
+    conn.query(path, method="DELETE", headers=headers)