saltext.github 1.1.0__py3-none-any.whl

saltext/github/utils/gh/issues.py

@@ -0,0 +1,193 @@
+"""
+Operations on GitHub repository issues.
+"""
+
+import logging
+
+log = logging.getLogger(__name__)
+
+
+def get(conn, repo_name, number, *, owner=None):
+    """
+    Return the raw data of a single issue.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository the issue belongs to.
+
+    number
+        Issue number to retrieve.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    return conn.repo_query(owner, repo_name, "issues", str(number))
+
+
+def get_comments(conn, repo_name, number, since=None, *, owner=None):
+    """
+    Return the raw comment data for a single issue.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository the issue belongs to.
+
+    number
+        Issue number whose comments to retrieve.
+
+    since
+        Only comments updated at or after this time are returned. This is a
+        timestamp in ISO 8601 format: ``YYYY-MM-DDTHH:MM:SSZ``.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    params = {}
+    if since:
+        params["since"] = since
+    return conn.repo_query(
+        owner,
+        *(repo_name, "issues", str(number), "comments"),
+        params=params,
+    )
+
+
+def list_all(
+    conn,
+    repo_name,
+    *,
+    milestone=None,
+    state="open",
+    assignee=None,
+    creator=None,
+    mentioned=None,
+    labels=None,
+    sort="created",
+    direction="desc",
+    since=None,
+    per_page=None,
+    owner=None,
+):
+    """
+    Return the raw data of all issues in a repository matching the search
+    options. Pull requests are excluded.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository whose issues to list.
+
+    milestone
+        Number of a GitHub milestone, or a string of either ``*`` or ``none``.
+
+    state
+        Filter returned issues by their state. Can be either ``open``,
+        ``closed``, or ``all``. Default is ``open``.
+
+    assignee
+        Filter returned issues by assigned user handle. Pass ``none``
+        (as a string) for issues with no assigned user or ``*`` for
+        issues assigned to any user.
+
+    creator
+        Filter by the username that created the issue.
+
+    mentioned
+        Filter issues for a user that's mentioned in the issue.
+
+    labels
+        Filter issues by associated labels. String of comma separated
+        label names. For example, ``bug,ui,@high``.
+
+    sort
+        Field to sort results by. Either ``created``, ``updated``, or
+        ``comments``. Default is ``created``.
+
+    direction
+        Sort direction. Either ``asc`` or ``desc``. Default is ``desc``.
+
+    since
+        Only list issues updated at or after this time. This is a
+        timestamp in ISO 8601 format: ``YYYY-MM-DDTHH:MM:SSZ``.
+
+    per_page
+        Pagination size, maximum 100.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    params = {}
+
+    # Build API arguments, as necessary.
+    if milestone:
+        params["milestone"] = milestone
+    if assignee:
+        params["assignee"] = assignee
+    if creator:
+        params["creator"] = creator
+    if mentioned:
+        params["mentioned"] = mentioned
+    if labels:
+        params["labels"] = labels
+    if since:
+        params["since"] = since
+    if per_page:
+        params["per_page"] = per_page
+
+    # Only pass the following API args if they're not the defaults listed.
+    if state and state != "open":
+        params["state"] = state
+    if sort and sort != "created":
+        params["sort"] = sort
+    if direction and direction != "desc":
+        params["direction"] = direction
+
+    issues = conn.repo_query(owner, repo_name, "issues", params=params)
+
+    # Pull requests are included in the issue list from GitHub.
+    # Let's not include those in the return.
+    return [issue for issue in issues if not issue.get("pull_request")]
+
+
+def format_issue(issue):
+    """
+    Format API return information into a more manageable
+    and useful dictionary for issue information.
+
+    Legacy function, only used by deprecated callers.
+
+    issue
+        Issue to format.
+    """
+    ret = {
+        "id": issue.get("id"),
+        "issue_number": issue.get("number"),
+        "state": issue.get("state"),
+        "title": issue.get("title"),
+        "user": issue.get("user").get("login"),
+        "html_url": issue.get("html_url"),
+    }
+
+    assignee = issue.get("assignee")
+    if assignee:
+        assignee = assignee.get("login")
+
+    labels = issue.get("labels")
+    label_names = []
+    for label in labels:
+        label_names.append(label.get("name"))
+
+    milestone = issue.get("milestone")
+    if milestone:
+        milestone = milestone.get("title")
+
+    ret["assignee"] = assignee
+    ret["labels"] = label_names
+    ret["milestone"] = milestone
+
+    return ret

saltext/github/utils/gh/labels.py

@@ -0,0 +1,142 @@
+"""
+Operations on GitHub repository (issue) labels.
+"""
+
+import logging
+from urllib.parse import quote
+
+from saltext.github.utils import filter_unset
+
+log = logging.getLogger(__name__)
+
+
+def _path(*suffix):
+    # Label names can contain characters that are invalid in URL paths
+    return ["labels"] + [quote(str(segment), safe="") for segment in suffix]
+
+
+def normalize_color(color):
+    """
+    Normalize a label color for comparisons: lowercase, no leading ``#``.
+
+    color
+        Hexadecimal color code to normalize.
+    """
+    if color is None:
+        return None
+    return color.lstrip("#").lower()
+
+
+def list_all(conn, repo_name, *, owner=None):
+    """
+    Return all labels of a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    return conn.repo_query(owner, repo_name, "labels")
+
+
+def get(conn, repo_name, name, *, owner=None):
+    """
+    Return the data of a single label.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    name
+        Label name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if the label does not exist.
+    """
+    return conn.repo_query(owner, repo_name, *_path(name))
+
+
+def create(conn, repo_name, name, *, color=None, description=None, owner=None):
+    """
+    Create a label in a repository. Returns the data of the created label.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    name
+        Label name.
+
+    color
+        Hexadecimal color code for the label, without the leading ``#``.
+        If unset, GitHub assigns a random one.
+
+    description
+        Short description of the label.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    data = filter_unset({"name": name, "color": normalize_color(color), "description": description})
+    return conn.repo_query(owner, repo_name, "labels", method="POST", data=data)
+
+
+def update(conn, repo_name, name, *, new_name=None, color=None, description=None, owner=None):
+    """
+    Update an existing label. Returns the data of the updated label.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    name
+        Current label name.
+
+    new_name
+        New name for the label.
+
+    color
+        Hexadecimal color code for the label, without the leading ``#``.
+
+    description
+        Short description of the label.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    data = filter_unset(
+        {"new_name": new_name, "color": normalize_color(color), "description": description}
+    )
+    return conn.repo_query(owner, repo_name, *_path(name), method="PATCH", data=data)
+
+
+def delete(conn, repo_name, name, *, owner=None):
+    """
+    Delete a label from a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    name
+        Label name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    conn.repo_query(owner, repo_name, *_path(name), method="DELETE")

saltext/github/utils/gh/members.py

@@ -0,0 +1,157 @@
+"""
+Operations on GitHub organization members.
+"""
+
+import logging
+
+from github.GithubException import UnknownObjectException
+
+from saltext.github.utils.gh.client import api_request
+
+log = logging.getLogger(__name__)
+
+
+@api_request
+def list_all(conn, *, owner=None, ignore_cache=False):
+    """
+    Return the logins of all members of an organization (cached).
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    owner
+        Organization to target. Defaults to the connection's owner.
+
+    ignore_cache
+        Bypass the cached member list.
+    """
+    owner = owner or conn.owner
+    key = ("members", owner.lower())
+    if key not in conn.cache or ignore_cache:
+        conn.cache[key] = [member.login for member in conn.get_org(owner).get_members()]
+    return conn.cache[key]
+
+
+@api_request
+def get_info(conn, login, *, owner=None):
+    """
+    Return information about a user, including their organization
+    membership state.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    login
+        User handle to look up.
+
+    owner
+        Organization to target. Defaults to the connection's owner.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if the user does not exist.
+    """
+    user = conn.client.get_user(login)
+
+    ret = {
+        "company": user.company,
+        "created_at": user.created_at,
+        "email": user.email,
+        "html_url": user.html_url,
+        "id": user.id,
+        "login": user.login,
+        "name": user.name,
+        "type": user.type,
+        "url": user.url,
+    }
+
+    org = conn.get_org(owner)
+    try:
+        membership = user.get_organization_membership(org)
+    except UnknownObjectException:
+        ret["membership_state"] = "nonexistent"
+        ret["in_org"] = False
+        return ret
+
+    ret["in_org"] = org.has_in_members(user)
+    ret["membership_state"] = membership.state
+
+    return ret
+
+
+@api_request
+def invite(conn, login, *, owner=None):
+    """
+    Invite a user into the organization. Returns whether the resulting
+    membership state is ``pending``.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    login
+        User handle to invite.
+
+    owner
+        Organization to target. Defaults to the connection's owner.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if the user does not exist.
+    """
+    user = conn.client.get_user(login)
+
+    # There is no public method that also returns the resulting membership state
+    _, data = conn.client.requester.requestJsonAndCheck(
+        "PUT", conn.get_org(owner).url + "/memberships/" + user.login
+    )
+
+    return data.get("state") == "pending"
+
+
+@api_request
+def remove(conn, login, *, owner=None):
+    """
+    Remove a user from the organization (if they are a member).
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    login
+        User handle to remove.
+
+    owner
+        Organization to target. Defaults to the connection's owner.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if the user does not exist.
+    """
+    user = conn.client.get_user(login)
+
+    org = conn.get_org(owner)
+    if org.has_in_members(user):
+        org.remove_from_members(user)
+
+    return True
+
+
+@api_request
+def list_without_mfa(conn, *, owner=None, ignore_cache=False):
+    """
+    Return the logins (lowercase) of all organization members without
+    MFA turned on (cached).
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    owner
+        Organization to target. Defaults to the connection's owner.
+
+    ignore_cache
+        Bypass the cached member list.
+    """
+    owner = owner or conn.owner
+    key = ("members_without_mfa", owner.lower())
+    if key not in conn.cache or ignore_cache:
+        conn.cache[key] = [
+            member.login.lower()
+            for member in conn.get_org(owner).get_members(filter_="2fa_disabled")
+        ]
+    return conn.cache[key]

saltext/github/utils/gh/milestones.py

@@ -0,0 +1,122 @@
+"""
+Operations on GitHub repository milestones.
+"""
+
+import logging
+
+from saltext.github.utils.gh.exceptions import GitHubNotFoundError
+
+log = logging.getLogger(__name__)
+
+
+def get(conn, repo_name, number, *, owner=None):
+    """
+    Return the raw data of a single milestone.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository the milestone belongs to.
+
+    number
+        Milestone number to retrieve.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    return conn.repo_query(owner, repo_name, "milestones", str(number))
+
+
+def list_all(
+    conn,
+    repo_name,
+    *,
+    state="open",
+    sort="due_on",
+    direction="asc",
+    per_page=None,
+    owner=None,
+):
+    """
+    Return the raw data of all milestones in a repository matching the
+    search options.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository whose milestones to list.
+
+    state
+        Filter milestones by their state. Either ``open``, ``closed``,
+        or ``all``. Default is ``open``.
+
+    sort
+        Field to sort results by. Either ``due_on`` or ``completeness``.
+        Default is ``due_on``.
+
+    direction
+        Sort direction. Either ``asc`` or ``desc``. Default is ``asc``.
+
+    per_page
+        Pagination size, maximum 100.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    params = {}
+
+    if per_page:
+        params["per_page"] = per_page
+
+    # Only pass the following API args if they're not the defaults listed.
+    if state and state != "open":
+        params["state"] = state
+    if sort and sort != "due_on":
+        params["sort"] = sort
+    if direction and direction != "asc":
+        params["direction"] = direction
+
+    return conn.repo_query(owner, repo_name, "milestones", params=params)
+
+
+def find_by_title(conn, repo_name, title, *, owner=None):
+    """
+    Return a milestone by its title. Since the GitHub API only addresses
+    milestones by number, this searches the complete list.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Name of the repository the milestone is part of.
+
+    title
+        Title of the milestone.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if no milestone carries the title.
+    """
+    milestones = list_all(conn, repo_name, state="all", owner=owner)
+    for milestone in milestones or []:
+        if milestone.get("title") == title:
+            return milestone
+    raise GitHubNotFoundError(f"Milestone {title} was not found in repository {repo_name}.")
+
+
+def format_milestone(milestone):
+    """
+    Trim milestone data to the fields that are useful in (CLI) output.
+
+    milestone
+        Milestone to format.
+    """
+    return {
+        key: value
+        for key, value in milestone.items()
+        if key not in ("creator", "html_url", "labels_url")
+    }