stouputils.continuous_delivery.github module — stouputils 1.0.18 documentation

# stouputils.continuous_delivery.github module

This module contains utilities for continuous delivery on GitHub.

- upload_to_github: Upload the project to GitHub using the credentials and the configuration (make a release and upload the assets, handle existing tag, generate changelog, etc.)

validate_credentials(credentials: dict[str, dict[str, str]]) → tuple[str, dict[str, str]]

  Get and validate GitHub credentials

  Parameters:

    credentials (dict[str, dict[str, str]]) – Credentials for the GitHub API

  Returns:

    str: Owner (the username of the account to use)

    dict[str, str]: Headers (for the requests to the GitHub API)

  Return type:

    tuple[str, dict[str, str]]

validate_config(github_config: dict[str, Any]) → tuple[str, str, str, list[str]]

  Validate GitHub configuration

  Parameters:

    github_config (dict[str, str]) – Configuration for the GitHub project

  Returns:

    str: Project name on GitHub

    str: Version of the project

    str: Build folder path containing zip files to upload to the release

    list[str]: List of zip files to upload to the release

  Return type:

    tuple[str, str, str, list[str]]

handle_existing_tag(owner: str, project_name: str, version: str, headers: dict[str, str]) → bool

  Check if tag exists and handle deletion if needed

  Parameters:

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - version (str) – Version to check for existing tag

    - headers (dict[str, str]) – Headers for GitHub API requests

  Returns:

    True if the tag was deleted or if it was not found, False otherwise

  Return type:

    bool

delete_existing_release(owner: str, project_name: str, version: str, headers: dict[str, str]) → None

  Delete existing release for a version

  Parameters:

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - version (str) – Version of the release to delete

    - headers (dict[str, str]) – Headers for GitHub API requests

delete_existing_tag(tag_url: str, headers: dict[str, str]) → None

  Delete existing tag

  Parameters:

    - tag_url (str) – URL of the tag to delete

    - headers (dict[str, str]) – Headers for GitHub API requests

clean_version(version: str, keep: str = '') → str

  Clean a version string

  Parameters:

    - version (str) – The version string to clean

    - keep (str) – The characters to keep in the version string

  Returns:

    The cleaned version string

  Return type:

    str

      >>> clean_version("v1.e0.zfezf0.1.2.3zefz")
      '1.0.0.1.2.3'
      >>> clean_version("v1.e0.zfezf0.1.2.3zefz", keep="v")
      'v1.0.0.1.2.3'
      >>> clean_version("v1.2.3b", keep="ab")
      '1.2.3b'

version_to_float(version: str) → float

  Converts a version string into a float for comparison purposes. The version string is expected to follow the format of major.minor.patch.something_else…., where each part is separated by a dot and can be extended indefinitely.

  Parameters:

    version (str) – The version string to convert. (e.g. “v1.0.0.1.2.3”)

  Returns:

    The float representation of the version. (e.g. 0)

  Return type:

    float

      >>> version_to_float("v1.0.0")
      1.0
      >>> version_to_float("v1.0.0.1")
      1.000000001
      >>> version_to_float("v2.3.7")
      2.003007
      >>> version_to_float("v1.0.0.1.2.3")
      1.0000000010020031
      >>> version_to_float("v2.0") > version_to_float("v1.0.0.1")
      True

get_latest_tag(owner: str, project_name: str, version: str, headers: dict[str, str]) → tuple[str, str] | tuple[None, None]

  Get latest tag information

  Parameters:

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - version (str) – Version to remove from the list of tags

    - headers (dict[str, str]) – Headers for GitHub API requests

  Returns:

    SHA of the latest tag commit, None if no tags exist str|None: Version number of the latest tag, None if no tags exist

  Return type:

    str|None

get_commits_since_tag(owner: str, project_name: str, latest_tag_sha: str | None, headers: dict[str, str]) → list[dict[str, Any]]

  Get commits since last tag

  Parameters:

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - latest_tag_sha (str|None) – SHA of the latest tag commit

    - headers (dict[str, str]) – Headers for GitHub API requests

  Returns:

    List of commits since the last tag

  Return type:

    list[dict]

generate_changelog(commits: list[dict[str, Any]], owner: str, project_name: str, latest_tag_version: str | None, version: str) → str

  Generate changelog from commits. They must follow the conventional commits convention.

  Convention format: <type>: <description>

  Parameters:

    - commits (list[dict]) – List of commits to generate changelog from

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - latest_tag_version (str|None) – Version number of the latest tag

    - version (str) – Current version being released

  Returns:

    Generated changelog text

  Return type:

    str

  Source:

    https://www.conventionalcommits.org/en/v1.0.0/

create_tag(owner: str, project_name: str, version: str, headers: dict[str, str]) → None

  Create a new tag

  Parameters:

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - version (str) – Version for the new tag

    - headers (dict[str, str]) – Headers for GitHub API requests

create_release(owner: str, project_name: str, version: str, changelog: str, headers: dict[str, str]) → int

  Create a new release

  Parameters:

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - version (str) – Version for the new release

    - changelog (str) – Changelog text for the release

    - headers (dict[str, str]) – Headers for GitHub API requests

  Returns:

    ID of the created release

  Return type:

    int

upload_assets(owner: str, project_name: str, release_id: int, build_folder: str, headers: dict[str, str], endswith: list[str]) → None

  Upload release assets

  Parameters:

    - owner (str) – GitHub username

    - project_name (str) – Name of the GitHub repository

    - release_id (int) – ID of the release to upload assets to

    - build_folder (str) – Folder containing assets to upload

    - headers (dict[str, str]) – Headers for GitHub API requests

    - endswith (list[str]) – List of files to upload to the release (every file ending with one of these strings will be uploaded)

upload_to_github(credentials: dict[str, Any], github_config: dict[str, Any]) → str

  Upload the project to GitHub using the credentials and the configuration

  Parameters:

    - credentials (dict[str, Any]) – Credentials for the GitHub API

    - github_config (dict[str, Any]) – Configuration for the GitHub project

  Returns:

    Generated changelog text

  Return type:

    str

  Examples:

      > upload_to_github(
              credentials={
                      "github": {
                              "api_key": "ghp_...",
                              "username": "Stoupy"
                      }
              },
              github_config={
                      "project_name": "stouputils",
                      "version": "1.0.0",
                      "build_folder": "build",
                      "endswith": [".zip"]
              }
      )