saltext.github 1.1.0__py3-none-any.whl

saltext/github/resources/github/modules/environment.py

@@ -0,0 +1,241 @@
+"""
+Manage the targeted repository's (deployment) environments.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: all functions operate on the
+repository the job was dispatched to. The ``profile`` parameter
+defaults to the :ghconf:`profile <resource:profile>` named in the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils import filter_fields
+from saltext.github.utils.gh import environments as gh_environments
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+__func_alias__ = {"list_": "list", "set_": "set"}
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def list_(*, fields=None, profile=None):
+    """
+    List the environments of the targeted repository, as a mapping of
+    environment name to details.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' environment.list
+
+    fields
+        Only include these fields in the output. A single field name
+        reduces each entry to the field's value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    environments = gh_environments.list_all(conn, repo_name, owner=owner)
+    return filter_fields({env["name"]: env for env in environments}, fields)
+
+
+def get(name, *, profile=None):
+    """
+    Return the data of a single environment of the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' environment.get release
+
+    name
+        Name of the environment.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_environments.get(conn, repo_name, name, owner=owner)
+
+
+def set_(
+    name,
+    *,
+    wait_timer=None,
+    prevent_self_review=None,
+    reviewers=None,
+    deployment_branch_policy=None,
+    profile=None,
+):
+    """
+    Create or update an environment of the targeted repository,
+    replacing its whole configuration. Unspecified settings are reset
+    to their defaults. Returns the data of the environment.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' environment.set release \\
+            deployment_branch_policy='{protected_branches: false, custom_branch_policies: true}'
+
+    name
+        Name of the environment.
+
+    wait_timer
+        Amount of time to delay a job after it is initially triggered,
+        in minutes.
+
+    prevent_self_review
+        Prevent a user who created a job from approving it.
+
+    reviewers
+        People or teams that may review jobs that reference the
+        environment, as a list of mappings with ``type`` (``User`` or
+        ``Team``) and ``id``.
+
+    deployment_branch_policy
+        Type of deployment branch policy for this environment, either
+        ``null`` (default) to allow all branches or a mapping with
+        ``protected_branches`` and ``custom_branch_policies`` booleans.
+        Branch name patterns for custom policies are managed separately,
+        see :py:func:`environment.add_branch_policy
+        <saltext.github.resources.github.modules.environment.add_branch_policy>`.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_environments.set_(
+        conn,
+        repo_name,
+        name,
+        wait_timer=wait_timer,
+        prevent_self_review=prevent_self_review,
+        reviewers=reviewers,
+        deployment_branch_policy=deployment_branch_policy,
+        owner=owner,
+    )
+
+
+def remove(name, *, profile=None):
+    """
+    Remove an environment from the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' environment.remove release
+
+    name
+        Name of the environment.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_environments.delete(conn, repo_name, name, owner=owner)
+    return True
+
+
+def list_branch_policies(environment, *, fields=None, profile=None):
+    """
+    List the deployment branch policies of an environment of the
+    targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' environment.list_branch_policies release
+
+    environment
+        Name of the environment.
+
+    fields
+        Only include these fields in the output. A single field name
+        reduces each entry to the field's value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return filter_fields(
+        gh_environments.list_branch_policies(conn, repo_name, environment, owner=owner),
+        fields,
+    )
+
+
+def add_branch_policy(environment, name, *, typ="branch", profile=None):
+    """
+    Add a deployment branch (or tag) policy to an environment of the
+    targeted repository. Returns the data of the created policy.
+
+    The environment's ``deployment_branch_policy`` must have ``custom_branch_policies`` enabled.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' environment.add_branch_policy release main
+
+    environment
+        Name of the environment.
+
+    name
+        Name pattern that branches (or tags) must match in order to
+        deploy to the environment.
+
+    typ
+        Target of this rule, either ``branch`` or ``tag``.
+        Defaults to ``branch``.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_environments.create_branch_policy(
+        conn, repo_name, environment, name, typ=typ, owner=owner
+    )
+
+
+def remove_branch_policy(environment, policy_id, *, profile=None):
+    """
+    Remove a deployment branch policy from an environment of the
+    targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' environment.remove_branch_policy release 12345
+
+    environment
+        Name of the environment.
+
+    policy_id
+        ID of the branch policy.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_environments.delete_branch_policy(conn, repo_name, environment, policy_id, owner=owner)
+    return True

saltext/github/resources/github/modules/grains.py

@@ -0,0 +1,18 @@
+"""
+Re-expose all builtin read-only ``grains`` functions in the ``github`` resource context.
+"""
+
+import salt.modules.grains
+from salt.utils.functools import namespaced_function
+
+global_dict = globals()
+
+equals = namespaced_function(salt.modules.grains.equals, global_dict)
+filter_by = namespaced_function(salt.modules.grains.filter_by, global_dict)
+get = namespaced_function(salt.modules.grains.get, global_dict)
+has_value = namespaced_function(salt.modules.grains.has_value, global_dict)
+item = namespaced_function(salt.modules.grains.item, global_dict)
+items = namespaced_function(salt.modules.grains.items, global_dict)
+ls = namespaced_function(salt.modules.grains.ls, global_dict)
+
+fetch = get

saltext/github/resources/github/modules/issue.py

@@ -0,0 +1,157 @@
+"""
+Inspect the targeted repository's issues (read-only).
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: all functions operate on the
+repository the job was dispatched to. The ``profile`` parameter
+defaults to the :ghconf:`profile <resource:profile>` named in the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils import filter_fields
+from saltext.github.utils.gh import issues as gh_issues
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+__func_alias__ = {"list_": "list"}
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def list_(
+    *,
+    milestone=None,
+    state="open",
+    assignee=None,
+    creator=None,
+    mentioned=None,
+    labels=None,
+    sort="created",
+    direction="desc",
+    since=None,
+    per_page=None,
+    fields=None,
+    profile=None,
+):
+    """
+    Return the issues in the targeted repository, based on the search
+    options. Pull requests are excluded.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' issue.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.
+
+    fields
+        Only include these fields in the output. A single field name
+        reduces each entry to the field's value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    issues = gh_issues.list_all(
+        conn,
+        repo_name,
+        milestone=milestone,
+        state=state,
+        assignee=assignee,
+        creator=creator,
+        mentioned=mentioned,
+        labels=labels,
+        sort=sort,
+        direction=direction,
+        since=since,
+        per_page=per_page,
+        owner=owner,
+    )
+    return filter_fields(issues, fields)
+
+
+def get(number, *, profile=None):
+    """
+    Return information about a single issue in the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' issue.get 514
+
+    number
+        Issue number to retrieve.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_issues.get(conn, repo_name, number, owner=owner)
+
+
+def get_comments(number, *, since=None, profile=None):
+    """
+    Return the comments of an issue in the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' issue.get_comments 514
+
+    number
+        Issue number for which to retrieve comments.
+
+    since
+        Only return comments updated at or after this time. This is a
+        timestamp in ISO 8601 format: ``YYYY-MM-DDTHH:MM:SSZ``.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_issues.get_comments(conn, repo_name, number, since=since, owner=owner)

saltext/github/resources/github/modules/label.py

@@ -0,0 +1,161 @@
+"""
+Manage the targeted repository's labels.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: all functions operate on the
+repository the job was dispatched to. The ``profile`` parameter
+defaults to the :ghconf:`profile <resource:profile>` named in the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils import filter_fields
+from saltext.github.utils.gh import labels as gh_labels
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+__func_alias__ = {"list_": "list"}
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def list_(*, fields=None, profile=None):
+    """
+    List the labels of the targeted repository, as a mapping of label
+    name to details.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' label.list
+
+    fields
+        Only include these fields in the output. A single field name
+        reduces each entry to the field's value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    labels = gh_labels.list_all(conn, repo_name, owner=owner)
+    return filter_fields({label["name"]: label for label in labels}, fields)
+
+
+def get(name, *, profile=None):
+    """
+    Return the data of a single label of the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' label.get bug
+
+    name
+        Name of the label.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_labels.get(conn, repo_name, name, owner=owner)
+
+
+def add(name, *, color=None, description=None, profile=None):
+    """
+    Create a label in the targeted repository.
+    Returns the data of the created label.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' label.add release color=00ff00
+
+    name
+        Name of the label.
+
+    color
+        Hexadecimal color code for the label, without the leading ``#``.
+        If unset, GitHub assigns a random one.
+
+    description
+        Short description of the label.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_labels.create(
+        conn, repo_name, name, color=color, description=description, owner=owner
+    )
+
+
+def edit(name, *, new_name=None, color=None, description=None, profile=None):
+    """
+    Update an existing label of the targeted repository.
+    Returns the data of the updated label.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' label.edit release color=00ff00
+
+    name
+        Current name of the label.
+
+    new_name
+        New name for the label.
+
+    color
+        Hexadecimal color code for the label, without the leading ``#``.
+
+    description
+        Short description of the label.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_labels.update(
+        conn,
+        repo_name,
+        name,
+        new_name=new_name,
+        color=color,
+        description=description,
+        owner=owner,
+    )
+
+
+def remove(name, *, profile=None):
+    """
+    Delete a label from the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' label.remove release
+
+    name
+        Name of the label.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_labels.delete(conn, repo_name, name, owner=owner)
+    return True

saltext/github/resources/github/modules/milestone.py

@@ -0,0 +1,103 @@
+"""
+Inspect the targeted repository's milestones (read-only).
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: all functions operate on the
+repository the job was dispatched to. The ``profile`` parameter
+defaults to the :ghconf:`profile <resource:profile>` named in the resource declaration.
+"""
+
+import logging
+
+from salt.exceptions import CommandExecutionError
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils import filter_fields
+from saltext.github.utils.gh import milestones as gh_milestones
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+__func_alias__ = {"list_": "list"}
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def list_(
+    *, state="open", sort="due_on", direction="asc", per_page=None, fields=None, profile=None
+):
+    """
+    Return the targeted repository's milestones.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' milestone.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.
+
+    fields
+        Only include these fields in the output. A single field name
+        reduces each entry to the field's value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    milestones = gh_milestones.list_all(
+        conn,
+        repo_name,
+        state=state,
+        sort=sort,
+        direction=direction,
+        per_page=per_page,
+        owner=owner,
+    )
+    return filter_fields(milestones, fields)
+
+
+def get(number=None, *, name=None, profile=None):
+    """
+    Return information about a single milestone in the targeted
+    repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' milestone.get 72
+        salt 'my-org/my-repo' milestone.get name=my_milestone
+
+    number
+        Milestone number to retrieve. If provided, overrides ``name``.
+
+    name
+        Title of the milestone to retrieve.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    if not (number or name):
+        raise CommandExecutionError("Either a milestone 'name' or 'number' must be provided.")
+
+    conn, owner, repo_name = _core_args(profile)
+    if number:
+        return gh_milestones.get(conn, repo_name, number, owner=owner)
+    return gh_milestones.find_by_title(conn, repo_name, name, owner=owner)