saltext.github 1.1.0__py3-none-any.whl

saltext/github/resources/github/modules/pages.py

@@ -0,0 +1,149 @@
+"""
+Manage the targeted repository's GitHub Pages site.
+
+.. 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.gh import pages as gh_pages
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def get(*, profile=None):
+    """
+    Return information about the GitHub Pages site of the targeted
+    repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' pages.get
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_pages.get(conn, repo_name, owner=owner)
+
+
+def setup(*, build_type=None, source_branch=None, source_path=None, profile=None):
+    """
+    Configure a GitHub Pages site for the targeted repository.
+    Returns the data of the created site.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' pages.setup build_type=workflow
+
+    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``.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_pages.create(
+        conn,
+        repo_name,
+        build_type=build_type,
+        source=gh_pages.build_source(source_branch, source_path),
+        owner=owner,
+    )
+
+
+def update(
+    *,
+    build_type=None,
+    source_branch=None,
+    source_path=None,
+    cname=...,
+    https_enforced=None,
+    profile=None,
+):
+    """
+    Update the GitHub Pages site configuration of the targeted
+    repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' pages.update build_type=workflow
+
+    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. Pass ``null`` explicitly to remove it,
+        omit to leave it unchanged.
+
+    https_enforced
+        Enforce HTTPS for the site.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_pages.update(
+        conn,
+        repo_name,
+        build_type=build_type,
+        source=gh_pages.build_source(source_branch, source_path),
+        cname=cname,
+        https_enforced=https_enforced,
+        owner=owner,
+    )
+    return True
+
+
+def remove(*, profile=None):
+    """
+    Delete the GitHub Pages site of the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' pages.remove
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_pages.delete(conn, repo_name, owner=owner)
+    return True

saltext/github/resources/github/modules/pull.py

@@ -0,0 +1,90 @@
+"""
+Inspect the targeted repository's pull requests (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 pulls as gh_pulls
+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",
+    head=None,
+    base=None,
+    sort="created",
+    direction="desc",
+    per_page=None,
+    fields=None,
+    profile=None,
+):
+    """
+    Return the pull requests in the targeted repository, based on the
+    search options.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' pull.list
+
+    state
+        Filter returned pull requests by their state. Can be either
+        ``open``, ``closed``, or ``all``. Default is ``open``.
+
+    head
+        Filter pull requests by head user and branch name in the format
+        ``user:ref-name``.
+
+    base
+        Filter pulls by base branch name, e.g. ``gh-pages``.
+
+    sort
+        Field to sort results by. Either ``created``, ``updated``,
+        ``popularity`` (comment count), or ``long-running`` (age, filtering
+        by pull requests updated within the last month). Default is ``created``.
+
+    direction
+        Sort direction. Either ``asc`` or ``desc``. Default is ``desc``.
+
+    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)
+    pulls = gh_pulls.list_all(
+        conn,
+        repo_name,
+        state=state,
+        head=head,
+        base=base,
+        sort=sort,
+        direction=direction,
+        per_page=per_page,
+        owner=owner,
+    )
+    return filter_fields(pulls, fields)

saltext/github/resources/github/modules/repo.py

@@ -0,0 +1,155 @@
+"""
+Manage the targeted repository's settings and inspect its identity
+and team associations.
+
+.. 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 profile as gh_profile
+from saltext.github.utils.gh import repos as gh_repos
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def ident():
+    """
+    Return the identity of the targeted repository as a mapping with
+    ``id`` (the resource ID), ``owner`` and ``repo``. Does not contact
+    the API.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' repo.ident
+    """
+    owner, _, repo_name = __resource__["id"].partition("/")
+    return {"id": __resource__["id"], "owner": owner, "repo": repo_name}
+
+
+def info(*, ignore_cache=False, profile=None):
+    """
+    Return information about the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' repo.info
+
+    ignore_cache
+        Bypass the use of cached repository information.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_repos.get_info(conn, repo_name, owner=owner, ignore_cache=ignore_cache)
+
+
+def get_teams(*, fields=None, profile=None):
+    """
+    Return the teams the targeted repository belongs to, as a mapping
+    of team name to details.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' repo.get_teams
+
+    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)
+    teams = gh_repos.get_teams(conn, repo_name, owner=owner)
+    return filter_fields({team["name"]: team for team in teams}, fields)
+
+
+def update(
+    *,
+    description=None,
+    homepage=None,
+    private=None,
+    has_issues=None,
+    has_wiki=None,
+    has_downloads=None,
+    default_branch=None,
+    profile=None,
+):
+    """
+    Update the targeted repository's settings.
+    Returns the refreshed repository information.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' repo.update description='Managed by Salt'
+
+    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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    allow_privacy_change = gh_profile.get_config_value(
+        profile or gh_profile.resource_owner_profile(__opts__, owner),
+        "allow_repo_privacy_changes",
+        opts=__opts__,
+        context=__context__,
+        default=False,
+    )
+    return gh_repos.update(
+        conn,
+        repo_name,
+        owner=owner,
+        description=description,
+        homepage=homepage,
+        private=private,
+        has_issues=has_issues,
+        has_wiki=has_wiki,
+        has_downloads=has_downloads,
+        default_branch=default_branch,
+        allow_privacy_change=allow_privacy_change,
+    )

saltext/github/resources/github/modules/ruleset.py

@@ -0,0 +1,144 @@
+"""
+Manage the targeted repository's rulesets.
+
+.. 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 resource as gh_resource
+from saltext.github.utils.gh import rulesets as gh_rulesets
+
+log = logging.getLogger(__name__)
+
+__func_alias__ = {"list_": "list"}
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def list_(*, per_page=None, fields=None, profile=None):
+    """
+    List all rulesets of the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' ruleset.list
+
+    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)
+    rulesets = gh_rulesets.list_all(
+        conn, "repo", owner=owner, repo_name=repo_name, per_page=per_page
+    )
+    return filter_fields(rulesets, fields)
+
+
+def get(ruleset_id, *, profile=None):
+    """
+    Return the data of a single ruleset of the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' ruleset.get 1234
+
+    ruleset_id
+        ID of the ruleset.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_rulesets.get(conn, ruleset_id, "repo", owner=owner, repo_name=repo_name)
+
+
+def add(ruleset_params, *, profile=None):
+    """
+    Create a new ruleset in the targeted repository.
+    Returns the data of the created ruleset.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' ruleset.add '{name: test, enforcement: active}'
+
+    ruleset_params
+        Ruleset definition. Must contain at least ``name`` and ``enforcement``.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_rulesets.create(conn, ruleset_params, "repo", owner=owner, repo_name=repo_name)
+
+
+def update(ruleset_id, ruleset_params, *, profile=None):
+    """
+    Update an existing ruleset of the targeted repository.
+    Returns the data of the updated ruleset.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' ruleset.update 1234 '{enforcement: disabled}'
+
+    ruleset_id
+        ID of the ruleset.
+
+    ruleset_params
+        Updated ruleset definition.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_rulesets.update(
+        conn, ruleset_id, ruleset_params, "repo", owner=owner, repo_name=repo_name
+    )
+
+
+def remove(ruleset_id, *, profile=None):
+    """
+    Delete a ruleset from the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' ruleset.remove 1234
+
+    ruleset_id
+        ID of the ruleset.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_rulesets.delete(conn, ruleset_id, "repo", owner=owner, repo_name=repo_name)
+    return True

saltext/github/resources/github/modules/saltutil.py

@@ -0,0 +1,24 @@
+"""
+Inspect running jobs on the managing minion.
+
+.. versionadded:: 1.1.0
+
+The stock :py:mod:`state <salt.modules.state>` execution module
+(re-exported for this resource type) performs conflict detection via
+``saltutil.is_running``. State runs for resources execute inline on the
+managing minion, so its job table is the correct one to consult. Both
+functions only need ``__opts__``, so the stock implementations are
+re-exported unchanged.
+"""
+
+import logging
+
+import salt.modules.saltutil as _stock
+from salt.utils.functools import namespaced_function
+
+log = logging.getLogger(__name__)
+
+running = namespaced_function(_stock.running, globals())
+is_running = namespaced_function(_stock.is_running, globals())
+
+__load__ = ["running", "is_running"]

saltext/github/resources/github/modules/state.py

@@ -0,0 +1,116 @@
+"""
+Apply states to the targeted repository.
+
+.. versionadded:: 1.1.0
+
+Salt's per-resource execution loader is deny-by-default, so a resource
+type must provide the ``state`` slot itself for ``state.apply`` and
+friends to be dispatchable to its resources. This module re-exports the
+stock :py:mod:`state <salt.modules.state>` execution module into the
+per-type loader via ``namespaced_function`` (the pattern recommended in
+Salt's resource state-authoring docs). The state engine then compiles
+and runs on the managing minion while every module call inside the
+rendered states dispatches through the per-resource loader — and thus
+through this extension's ``resources/github/states/`` overrides.
+
+Unlike the ``ssh`` resource type, no custom transport is needed: the
+GitHub API is reachable from the managing minion, so the stock
+implementations work unchanged. Only a few helpers that assume
+managing-minion dunders (``__pillar__``, grains-backed state disabling)
+are overridden below.
+"""
+
+import inspect
+import logging
+
+import salt.modules.state as _stock
+from salt.utils.functools import namespaced_function
+
+log = logging.getLogger(__name__)
+
+__func_alias__ = {"apply_": "apply"}
+
+# Only these functions are exposed as ``state.*`` for the github
+# resource type. Everything else from the stock module is namespaced
+# below purely so internal helper calls resolve against this module's
+# (loader-packed) globals, but stays unexposed. Notably absent:
+# queue/pause plumbing, ``disable``/``enable`` (grains-backed),
+# ``pkg`` (salt-thin transport) and ``event``.
+__load__ = [
+    "apply_",
+    "highstate",
+    "id_exists",
+    "running",
+    "show_highstate",
+    "show_low_sls",
+    "show_lowstate",
+    "show_sls",
+    "show_states",
+    "show_top",
+    "single",
+    "sls",
+    "sls_exists",
+    "sls_id",
+    "test",
+    "top",
+]
+
+
+def _namespace_stock():
+    """
+    Re-export every function defined in the stock module under this
+    module's globals. The public entry points call module-level helpers
+    (``_check_queue``, ``_get_test_value``, …) which access ``__salt__``
+    and friends — those helpers must be namespaced too, or they would
+    resolve dunders against the raw (unpacked) ``salt.modules.state``
+    module and fail with a ``NameError``.
+    """
+    for fname, func in list(vars(_stock).items()):
+        if inspect.isfunction(func) and func.__module__ == _stock.__name__:
+            globals()[fname] = namespaced_function(func, globals())
+
+
+_namespace_stock()
+
+
+# ---------------------------------------------------------------------------
+# Resource-context adjustments. Defined after the re-export so they
+# shadow the stock implementations.
+# ---------------------------------------------------------------------------
+
+
+def _get_initial_pillar(opts):
+    """
+    Use the managing minion's in-memory pillar when it matches the
+    requested pillarenv.
+
+    The stock implementation reads ``__pillar__``, which is not packed
+    into per-resource loaders. The managing minion's pillar contains the
+    resource declarations anyway, and reusing it avoids recompiling
+    pillar once per targeted repository.
+    """
+    pillar = __opts__.get("pillar")
+    if pillar and opts.get("pillarenv") == __opts__.get("pillarenv"):
+        try:
+            return pillar.value()
+        except AttributeError:
+            return pillar
+    return None
+
+
+def _get_pillar_errors(kwargs, pillar=None):
+    """
+    Stock implementation minus the in-memory ``__pillar__`` fallback,
+    which is not packed into per-resource loaders.
+    """
+    if kwargs.get("force"):
+        return None
+    return (pillar or {}).get("_errors")
+
+
+def _disabled(funs):  # pylint: disable=unused-argument
+    """
+    ``state.disable``/``state.enable`` (grains-backed) are not exposed
+    for the github resource type, so state runs can never be disabled.
+    """
+    return []

saltext/github/resources/github/modules/test.py

@@ -0,0 +1,29 @@
+"""
+Provide the ``test`` execution module for the ``github`` resource type.
+
+.. versionadded:: 1.1.0
+
+Its location in the per-type override directory makes it visible only
+to the ``github`` resource loader, so no ``__virtual__`` gate is needed.
+"""
+
+import logging
+
+log = logging.getLogger(__name__)
+
+
+def ping():
+    """
+    Return whether the targeted repository is reachable via the API.
+
+    Delegates to the connection module's ``ping()`` via
+    ``__resource_funcs__`` so the result reflects the actual state of
+    the resource rather than the managing minion.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' test.ping
+    """
+    return __resource_funcs__["github.ping"]()