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.)

stouputils upload_to_github examples
validate_credentials(credentials: dict[str, dict[str, str]]) → tuple[str, dict[str, str]][source]

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]][source]

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[source]

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[source]

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[source]

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[source]

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[source]

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][source]

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]][source]

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[source]

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[source]

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[source]

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[source]

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[source]

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"]
        }
)