Skip to content

github ¤

GitHub integration.

Functions:

  • new_project

    Create a new Insiders project on GitHub (public and private repositories).

new_project ¤

new_project(
    *,
    namespace: str,
    repo: str,
    description: str,
    repo_path: str | Path,
    insiders_repo_path: str | Path,
    insiders_namespace: str | None = None,
    insiders_repo: str | None = None,
    username: str | None = None,
    copier_template: str | None = None
) -> None

Create a new Insiders project on GitHub (public and private repositories).

Parameters:

  • namespace (str) –

    Namespace of the public repository.

  • repo (str) –

    Name of the public repository.

  • description (str) –

    Shared description.

  • repo_path (str | Path) –

    Local path in which to clone the public repository.

  • insiders_repo_path (str | Path) –

    Local path in which to clone the insiders repository.

  • insiders_namespace (str | None, default: None ) –

    Namespace of the insiders repository. Defaults to the public namespace.

  • insiders_repo (str | None, default: None ) –

    Name of the insiders repository. Defaults to the public name.

  • username (str | None, default: None ) –

    Username. Defaults to the public namespace value.

  • copier_template (str | None, default: None ) –

    Copier template to initialize the local insiders repository with.

Source code in src/insiders/github.py
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def new_project(
    *,
    namespace: An[str, Doc("Namespace of the public repository.")],
    repo: An[str, Doc("Name of the public repository.")],
    description: An[str, Doc("Shared description.")],
    repo_path: An[str | Path, Doc("Local path in which to clone the public repository.")],
    insiders_repo_path: An[str | Path, Doc("Local path in which to clone the insiders repository.")],
    insiders_namespace: An[
        str | None,
        Doc("Namespace of the insiders repository. Defaults to the public namespace."),
    ] = None,
    insiders_repo: An[str | None, Doc("Name of the insiders repository. Defaults to the public name.")] = None,
    username: An[str | None, Doc("Username. Defaults to the public namespace value.")] = None,
    copier_template: An[str | None, Doc("Copier template to initialize the local insiders repository with.")] = None,
) -> None:
    """Create a new Insiders project on GitHub (public and private repositories)."""
    username = username or namespace
    insiders_namespace = insiders_namespace or f"{username}-insiders"
    insiders_repo = insiders_repo or repo
    public_description = f"{description} Available to sponsors only."

    logger.debug("Creating new project with these settings:")
    logger.debug(f"- public repo:   {namespace}/{repo} cloned in {repo_path}")
    logger.debug(f"- insiders repo: {insiders_namespace}/{insiders_repo} cloned in {insiders_repo_path}")

    common_opts = ("--disable-wiki", "--homepage", f"https://{namespace}.github.io/{repo}")
    public_opts = ("--description", public_description, "--public", *common_opts)
    insiders_opts = ("--description", description, "--private", "--disable-issues", *common_opts)
    _gh_repo_create(f"{namespace}/{repo}", *public_opts)
    _gh_repo_create(f"{insiders_namespace}/{insiders_repo}", *insiders_opts)

    repo_path = Path(repo_path)
    run("git", "clone", f"git@github.com:{namespace}/{repo}", repo_path)
    repo_path.joinpath("README.md").write_text(
        dedent(
            f"""
            # {repo}

            {description}

            This project is currently available to [sponsors](https://github.com/sponsors/{username}) only.
            See https://{namespace}.github.io/{repo}/insiders.
            """,
        ).lstrip(),
    )

    workflow = repo_path / ".github" / "workflows" / "ci.yml"
    workflow.parent.mkdir(parents=True)
    workflow.write_text(
        dedent(
            """
            on:
                push:
            jobs:
                all:
                    runs-on: ubuntu-latest
                    steps:
                    - run: echo "Nothing to do!"
            """,
        ),
    )
    run("git", "-C", repo_path, "add", "-A")
    run("git", "-C", repo_path, "commit", "-m", "chore: Initial commit")
    run("git", "-C", repo_path, "push")

    insiders_repo_path = Path(insiders_repo_path)
    run("git", "clone", f"git@github.com:{insiders_namespace}/{insiders_repo}", insiders_repo_path)
    run("git", "-C", insiders_repo_path, "remote", "add", "upstream", f"git@github.com:{namespace}/{repo}")
    run("git", "-C", insiders_repo_path, "pull", "upstream", "main")

    defaults = {}
    if not copier_template and username == "pawamoy":
        if "handler for mkdocstrings" in description:
            copier_template = "gh:mkdocstrings/handler-template"
        else:
            copier_template = "gh:pawamoy/copier-pdm"
        defaults = {
            "project_name": repo,
            "project_description": description,
            "author_username": username,
            "repository_namespace": namespace,
            "repository_name": repo,
            "insiders": True,
            "insiders_repository_name": insiders_repo,
            "public_release": False,
        }
    if copier_template:
        run_copy(
            copier_template,
            insiders_repo_path,
            user_defaults=defaults,
            overwrite=True,
            unsafe=True,
        )

    commit_message = f"feat: Generate project with {copier_template} Copier template"
    run("git", "-C", insiders_repo_path, "add", "-A")
    run("git", "-C", insiders_repo_path, "commit", "-m", commit_message)
    run("git", "-C", insiders_repo_path, "push")