saltext.github 1.1.0__py3-none-any.whl

saltext/github/utils/gh/statecores/labels.py

@@ -0,0 +1,116 @@
+"""
+State core managing repository labels.
+"""
+
+import logging
+
+from saltext.github.utils.gh import labels as gh_labels
+from saltext.github.utils.gh.exceptions import GitHubNotFoundError
+
+log = logging.getLogger(__name__)
+
+
+def present(conn, name, repo_name, *, color=None, description=None, owner=None, test=False):
+    """
+    Ensure a label is present in a repository and configured as
+    specified. Unspecified settings are left unmanaged.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the label.
+
+    repo_name
+        Name of the repository.
+
+    color
+        Hexadecimal color code for the label. A leading ``#``
+        is accepted.
+
+    description
+        Short description of the label.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    try:
+        current = gh_labels.get(conn, repo_name, name, owner=owner)
+    except GitHubNotFoundError:
+        current = None
+
+    if current is None:
+        ret["changes"]["created"] = name
+        if test:
+            ret["result"] = None
+            ret["comment"] = f"Label {name} would have been created"
+            return ret
+        gh_labels.create(conn, repo_name, name, color=color, description=description, owner=owner)
+        ret["comment"] = f"Label {name} has been created"
+        return ret
+
+    diff = {}
+    if color is not None and gh_labels.normalize_color(
+        current["color"]
+    ) != gh_labels.normalize_color(color):
+        diff["color"] = color
+    if description is not None and current.get("description") != description:
+        diff["description"] = description
+
+    if not diff:
+        ret["comment"] = f"Label {name} is already configured as specified"
+        return ret
+
+    ret["changes"]["old"] = {key: current.get(key) for key in diff}
+    ret["changes"]["new"] = diff
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Label {name} would have been updated"
+        return ret
+
+    gh_labels.update(conn, repo_name, name, owner=owner, **diff)
+    ret["comment"] = f"Label {name} has been updated"
+    return ret
+
+
+def absent(conn, name, repo_name, *, owner=None, test=False):
+    """
+    Ensure a label is absent from a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the label.
+
+    repo_name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    try:
+        gh_labels.get(conn, repo_name, name, owner=owner)
+    except GitHubNotFoundError:
+        ret["comment"] = f"Label {name} is already absent"
+        return ret
+
+    ret["changes"]["deleted"] = name
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Label {name} would have been removed"
+        return ret
+
+    gh_labels.delete(conn, repo_name, name, owner=owner)
+    ret["comment"] = f"Label {name} has been removed"
+    return ret

saltext/github/utils/gh/statecores/pages.py

@@ -0,0 +1,177 @@
+"""
+State core managing a repository's GitHub Pages site.
+"""
+
+import logging
+
+from saltext.github.utils import filter_unset
+from saltext.github.utils.gh import pages as gh_pages
+from saltext.github.utils.gh.exceptions import GitHubNotFoundError
+
+log = logging.getLogger(__name__)
+
+
+def present(
+    conn,
+    name,
+    repo_name,
+    *,
+    build_type=None,
+    source_branch=None,
+    source_path=None,
+    cname=None,
+    https_enforced=None,
+    owner=None,
+    test=False,
+):
+    """
+    Ensure GitHub Pages are enabled for a repository and configured as
+    specified. Unspecified settings are left unmanaged.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        State name (reported back unchanged).
+
+    repo_name
+        Name of the repository.
+
+    build_type
+        Process by which the site is built, either ``legacy``
+        (deploy from a branch) or ``workflow`` (GitHub Actions).
+
+    source_branch
+        For ``legacy`` builds, the repository branch to publish from.
+
+    source_path
+        For ``legacy`` builds, the repository directory to publish from,
+        either ``/`` or ``/docs``.
+
+    cname
+        Custom domain for the site.
+
+    https_enforced
+        Enforce HTTPS for the site.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    try:
+        current = gh_pages.get(conn, repo_name, owner=owner)
+    except GitHubNotFoundError:
+        current = None
+
+    if current is None:
+        ret["changes"]["created"] = repo_name
+        if test:
+            ret["result"] = None
+            ret["comment"] = f"Pages would have been enabled for {repo_name}"
+            return ret
+        gh_pages.create(
+            conn,
+            repo_name,
+            build_type=build_type,
+            source=gh_pages.build_source(source_branch, source_path),
+            owner=owner,
+        )
+        if cname is not None or https_enforced is not None:
+            extra = {"https_enforced": https_enforced}
+            if cname is not None:
+                extra["cname"] = cname
+            gh_pages.update(conn, repo_name, owner=owner, **extra)
+        ret["comment"] = f"Pages have been enabled for {repo_name}"
+        return ret
+
+    current_source = current.get("source") or {}
+    desired = filter_unset(
+        {
+            "build_type": build_type,
+            "source_branch": source_branch,
+            "source_path": source_path,
+            "cname": cname,
+            "https_enforced": https_enforced,
+        }
+    )
+    current_flat = {
+        "build_type": current.get("build_type"),
+        "source_branch": current_source.get("branch"),
+        "source_path": current_source.get("path"),
+        "cname": current.get("cname"),
+        "https_enforced": current.get("https_enforced"),
+    }
+    diff = {key: val for key, val in desired.items() if current_flat[key] != val}
+
+    if not diff:
+        ret["comment"] = f"Pages for {repo_name} are already configured as specified"
+        return ret
+
+    ret["changes"]["old"] = {key: current_flat[key] for key in diff}
+    ret["changes"]["new"] = diff
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Pages configuration for {repo_name} would have been updated"
+        return ret
+
+    update_kwargs = dict(diff)
+    if "source_branch" in diff or "source_path" in diff:
+        # The source is submitted as a single object, carry over the
+        # unchanged half
+        update_kwargs.setdefault("source_branch", current_flat["source_branch"])
+        update_kwargs.setdefault("source_path", current_flat["source_path"])
+    gh_pages.update(
+        conn,
+        repo_name,
+        build_type=update_kwargs.get("build_type"),
+        source=gh_pages.build_source(
+            update_kwargs.get("source_branch"), update_kwargs.get("source_path")
+        ),
+        cname=update_kwargs.get("cname", ...),
+        https_enforced=update_kwargs.get("https_enforced"),
+        owner=owner,
+    )
+    ret["comment"] = f"Pages configuration for {repo_name} has been updated"
+    return ret
+
+
+def absent(conn, name, repo_name, *, owner=None, test=False):
+    """
+    Ensure GitHub Pages are disabled for a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        State name (reported back unchanged).
+
+    repo_name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    try:
+        gh_pages.get(conn, repo_name, owner=owner)
+    except GitHubNotFoundError:
+        ret["comment"] = f"Pages are already disabled for {repo_name}"
+        return ret
+
+    ret["changes"]["deleted"] = repo_name
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Pages would have been disabled for {repo_name}"
+        return ret
+
+    gh_pages.delete(conn, repo_name, owner=owner)
+    ret["comment"] = f"Pages have been disabled for {repo_name}"
+    return ret

saltext/github/utils/gh/statecores/repo.py

@@ -0,0 +1,249 @@
+"""
+State core managing a repository's settings and team associations.
+"""
+
+import logging
+
+from salt.exceptions import CommandExecutionError
+
+from saltext.github.utils.gh import repos as gh_repos
+from saltext.github.utils.gh import teams as gh_teams
+from saltext.github.utils.gh.exceptions import GitHubNotFoundError
+from saltext.github.utils.gh.statecores import StateError
+from saltext.github.utils.gh.statecores import differs
+
+log = logging.getLogger(__name__)
+
+
+def _repo_settings_diff(ret, target, managed):
+    """
+    Record the settings of an existing repository that need updating
+    in ``ret`` and return them.
+    """
+    update_params = {
+        param: value
+        for param, value in managed.items()
+        if value is not None and differs(target[param], value)
+    }
+    if update_params:
+        ret["changes"]["old"] = {param: target[param] for param in update_params}
+        ret["changes"]["new"] = update_params
+    return update_params
+
+
+def _repo_teams_diff(ret, conn, name, teams, owner):
+    """
+    Record the team association changes of an existing repository in
+    ``ret`` and return them.
+    """
+    current_teams = {team["name"] for team in gh_repos.get_teams(conn, name, owner=owner)}
+    teams_added = sorted(set(teams) - current_teams)
+    teams_removed = sorted(current_teams - set(teams))
+    team_permissions = {}
+    for team_name in sorted(set(teams) & current_teams):
+        team_repos = gh_teams.list_repos(
+            conn, gh_teams.find(conn, team_name, owner=owner), owner=owner
+        )
+        current_permission = team_repos.get(name.lower(), {}).get("permission")
+        if current_permission != teams[team_name]:
+            team_permissions[team_name] = {"old": current_permission, "new": teams[team_name]}
+    if teams_added:
+        ret["changes"]["teams_added"] = teams_added
+    if teams_removed:
+        ret["changes"]["teams_removed"] = teams_removed
+    if team_permissions:
+        ret["changes"]["team_permissions"] = team_permissions
+    return teams_added, teams_removed, team_permissions
+
+
+def _set_team_repo(conn, name, team_name, permission, owner):
+    """
+    Add a repository to a team or update the team's permission on it.
+    """
+    gh_teams.add_repo(
+        conn, gh_teams.find(conn, team_name, owner=owner), name, permission=permission, owner=owner
+    )
+
+
+def present(
+    conn,
+    name,
+    *,
+    owner=None,
+    description=None,
+    homepage=None,
+    private=None,
+    has_issues=None,
+    has_wiki=None,
+    has_downloads=None,
+    auto_init=False,
+    gitignore_template=None,
+    license_template=None,
+    default_branch=None,
+    teams=None,
+    allow_privacy_change=False,
+    allow_create=True,
+    test=False,
+):
+    """
+    Ensure a repository is present and configured as specified.
+    Unspecified settings are left unmanaged.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    allow_privacy_change
+        Allow changing an existing repository's visibility (the
+        profile's :ghconf:`allow_repo_privacy_changes`). Defaults to false.
+
+    allow_create
+        Create the repository when it is missing. When disabled, a
+        missing repository raises instead (resource context, where the
+        repository's existence is a given). Defaults to true.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+
+    For the remaining parameters, see the ``github_repo.present`` state.
+    """
+    ret = {
+        "name": name,
+        "changes": {},
+        "result": True,
+        "comment": f"Repo {name} is present as specified",
+    }
+
+    # This is an optimization to cache all of the owner's repos up front.
+    # The first use of this state will collect all of the repos and save a bunch
+    # of API calls for future use.
+    gh_repos.list_all(conn, owner=owner)
+
+    try:
+        target = gh_repos.get_info(conn, name, owner=owner)
+    except GitHubNotFoundError:
+        if not allow_create:
+            raise CommandExecutionError(f"Repo {name} does not exist") from None
+        target = None
+
+    update_params = {}
+    teams_added, teams_removed, team_permissions = [], [], {}
+    if target is None:
+        ret["changes"]["created"] = name
+        if teams:
+            ret["changes"]["teams_added"] = sorted(teams)
+    else:
+        update_params = _repo_settings_diff(
+            ret,
+            target,
+            {
+                "description": description,
+                "homepage": homepage,
+                "private": private,
+                "has_issues": has_issues,
+                "has_wiki": has_wiki,
+                "has_downloads": has_downloads,
+                "default_branch": default_branch,
+            },
+        )
+        if teams is not None:
+            teams_added, teams_removed, team_permissions = _repo_teams_diff(
+                ret, conn, name, teams, owner
+            )
+
+    if not ret["changes"]:
+        return ret
+
+    verb = "created" if target is None else "updated"
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Repo {name} would have been {verb}"
+        return ret
+
+    applied = {}
+    try:
+        if target is None:
+            gh_repos.create(
+                conn,
+                name,
+                owner=owner,
+                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,
+            )
+            applied["created"] = name
+            for team_name in sorted(teams or {}):
+                _set_team_repo(conn, name, team_name, teams[team_name], owner)
+                applied.setdefault("teams_added", []).append(team_name)
+        else:
+            if update_params:
+                gh_repos.update(
+                    conn,
+                    name,
+                    owner=owner,
+                    allow_privacy_change=allow_privacy_change,
+                    **update_params,
+                )
+                applied["old"] = ret["changes"]["old"]
+                applied["new"] = ret["changes"]["new"]
+            for team_name in teams_added:
+                _set_team_repo(conn, name, team_name, teams[team_name], owner)
+                applied.setdefault("teams_added", []).append(team_name)
+            for team_name in teams_removed:
+                gh_teams.remove_repo(
+                    conn, gh_teams.find(conn, team_name, owner=owner), name, owner=owner
+                )
+                applied.setdefault("teams_removed", []).append(team_name)
+            for team_name, permission in team_permissions.items():
+                _set_team_repo(conn, name, team_name, teams[team_name], owner)
+                applied.setdefault("team_permissions", {})[team_name] = permission
+    except CommandExecutionError as err:
+        raise StateError(str(err), changes=applied) from err
+    ret["comment"] = f"Repo {name} has been {verb}"
+    return ret
+
+
+def absent(conn, name, *, owner=None, test=False):
+    """
+    Ensure a repository is absent.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    try:
+        gh_repos.get_info(conn, name, owner=owner)
+    except GitHubNotFoundError:
+        ret["comment"] = f"Repo {name} does not exist"
+        return ret
+
+    ret["changes"]["deleted"] = name
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Repo {name} would have been deleted"
+        return ret
+
+    gh_repos.delete(conn, name, owner=owner)
+    ret["comment"] = f"Repo {name} has been deleted"
+    return ret

saltext/github/utils/gh/statecores/rulesets.py

@@ -0,0 +1,115 @@
+"""
+State core managing repository rulesets.
+"""
+
+import logging
+
+from saltext.github.utils.gh import rulesets as gh_rulesets
+
+log = logging.getLogger(__name__)
+
+
+def present(conn, name, repo_name, *, ruleset_params=None, owner=None, test=False):
+    """
+    Ensure a repository ruleset is present and configured as specified.
+    Only the parameters included in ``ruleset_params`` are compared,
+    server-populated fields are ignored.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Ruleset name to manage.
+
+    repo_name
+        Name of the repository.
+
+    ruleset_params
+        Ruleset definition. Must contain at least ``enforcement``
+        when the ruleset needs to be created. ``name`` is pulled from
+        this state's ``name``.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    ruleset_params = dict(ruleset_params or {})
+    ruleset_params["name"] = name
+
+    rulesets = gh_rulesets.list_all(conn, "repo", owner=owner, repo_name=repo_name)
+    ruleset = next((rls for rls in rulesets or [] if rls["name"] == name), None)
+
+    if ruleset is None:
+        ret["changes"]["created"] = name
+        if test:
+            ret["result"] = None
+            ret["comment"] = f"Ruleset {name} would have been created"
+            return ret
+        gh_rulesets.create(conn, ruleset_params, "repo", owner=owner, repo_name=repo_name)
+        ret["comment"] = f"Ruleset {name} has been created"
+        return ret
+
+    ruleset_info = gh_rulesets.get(conn, ruleset["id"], "repo", owner=owner, repo_name=repo_name)
+
+    # Only diff the parameters that are being managed. The server
+    # response carries additional server-populated fields (id,
+    # timestamps, source, ...) that must not register as drift.
+    diff = {key: val for key, val in ruleset_params.items() if ruleset_info.get(key) != val}
+    if not diff:
+        ret["comment"] = f"Ruleset {name} is already configured as specified"
+        return ret
+
+    ret["changes"]["old"] = {key: ruleset_info.get(key) for key in diff}
+    ret["changes"]["new"] = diff
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Ruleset {name} would have been updated"
+        return ret
+
+    gh_rulesets.update(
+        conn, ruleset["id"], ruleset_params, "repo", owner=owner, repo_name=repo_name
+    )
+    ret["comment"] = f"Ruleset {name} has been updated"
+    return ret
+
+
+def absent(conn, name, repo_name, *, owner=None, test=False):
+    """
+    Ensure a repository ruleset is absent.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Ruleset name to manage.
+
+    repo_name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    rulesets = gh_rulesets.list_all(conn, "repo", owner=owner, repo_name=repo_name)
+    ruleset = next((rls for rls in rulesets or [] if rls["name"] == name), None)
+    if ruleset is None:
+        ret["comment"] = f"Ruleset {name} does not exist"
+        return ret
+
+    ret["changes"]["deleted"] = name
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Ruleset {name} would have been deleted"
+        return ret
+
+    gh_rulesets.delete(conn, ruleset["id"], "repo", owner=owner, repo_name=repo_name)
+    ret["comment"] = f"Ruleset {name} has been deleted"
+    return ret