Source code for saltext.github.utils.gh.pages

"""
Operations on GitHub Pages sites of repositories.
"""

import logging

from saltext.github.utils import filter_unset

log = logging.getLogger(__name__)




def build_source(branch=None, path=None):
    """
    Build a Pages ``source`` payload from branch and path, or ``None``
    when both are unset.

    branch
        Repository branch to publish from.

    path
        Repository directory to publish from, either ``/`` or ``/docs``.
    """
    source = filter_unset({"branch": branch, "path": path})
    return source or None





def get(conn, repo_name, *, owner=None):
    """
    Return information about the GitHub Pages site 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.

    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
    if the repository has no Pages site.
    """
    return conn.repo_query(owner, repo_name, "pages")





def create(conn, repo_name, *, build_type=None, source=None, owner=None):
    """
    Configure a GitHub Pages site for a repository.
    Returns the data of the created site.

    conn
        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.

    repo_name
        Repository name.

    build_type
        Process by which the site is built, either ``legacy``
        (deploy from a branch) or ``workflow`` (GitHub Actions).

    source
        For ``legacy`` builds, the deployment source as a mapping with
        ``branch`` and ``path``.

    owner
        Owner of the repository. Defaults to the connection's owner.
    """
    return conn.repo_query(
        owner,
        repo_name,
        "pages",
        method="POST",
        data=filter_unset({"build_type": build_type, "source": source}),
    )





def update(
    conn, repo_name, *, build_type=None, source=None, cname=..., https_enforced=None, owner=None
):
    """
    Update the GitHub Pages site configuration of a repository.

    conn
        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.

    repo_name
        Repository name.

    build_type
        Process by which the site is built, either ``legacy``
        (deploy from a branch) or ``workflow`` (GitHub Actions).

    source
        For ``legacy`` builds, the deployment source as a mapping with
        ``branch`` and ``path``.

    cname
        Custom domain for the site. Pass ``None`` explicitly
        to remove it.

    https_enforced
        Enforce HTTPS for the site.

    owner
        Owner of the repository. Defaults to the connection's owner.
    """
    data = filter_unset(
        {"build_type": build_type, "source": source, "https_enforced": https_enforced}
    )
    if cname is not ...:
        data["cname"] = cname
    conn.repo_query(owner, repo_name, "pages", method="PUT", data=data)





def delete(conn, repo_name, *, owner=None):
    """
    Delete the GitHub Pages site 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.
    """
    conn.repo_query(owner, repo_name, "pages", method="DELETE")