stouputils 1.12.1__py3-none-any.whl

stouputils/continuous_delivery/github.pyi

@@ -0,0 +1,162 @@
+from ..decorators import handle_error as handle_error, measure_time as measure_time
+from ..io import clean_path as clean_path
+from ..print import info as info, progress as progress, warning as warning
+from .cd_utils import clean_version as clean_version, handle_response as handle_response, version_to_float as version_to_float
+from typing import Any
+
+GITHUB_API_URL: str
+PROJECT_ENDPOINT: str
+COMMIT_TYPES: dict[str, str]
+
+def validate_credentials(credentials: dict[str, dict[str, str]]) -> tuple[str, dict[str, str]]:
+    """ Get and validate GitHub credentials
+
+\tArgs:
+\t\tcredentials (dict[str, dict[str, str]]):\tCredentials for the GitHub API
+\tReturns:
+\t\ttuple[str, dict[str, str]]:
+\t\t\tstr:\t\t\tOwner (the username of the account to use)
+
+\t\t\tdict[str, str]:\tHeaders (for the requests to the GitHub API)
+\t"""
+def validate_config(github_config: dict[str, Any]) -> tuple[str, str, str, list[str]]:
+    """ Validate GitHub configuration
+
+\tArgs:
+\t\tgithub_config (dict[str, str]):\tConfiguration for the GitHub project
+\tReturns:
+\t\ttuple[str, str, str, list[str]]:
+\t\t\tstr: Project name on GitHub
+
+\t\t\tstr: Version of the project
+
+\t\t\tstr: Build folder path containing zip files to upload to the release
+
+\t\t\tlist[str]: List of zip files to upload to the release
+\t"""
+def handle_existing_tag(owner: str, project_name: str, version: str, headers: dict[str, str]) -> bool:
+    """ Check if tag exists and handle deletion if needed
+
+\tArgs:
+\t\towner\t\t\t(str):\t\t\t\tGitHub username
+\t\tproject_name\t(str):\t\t\t\tName of the GitHub repository
+\t\tversion\t\t\t(str):\t\t\t\tVersion to check for existing tag
+\t\theaders\t\t\t(dict[str, str]):\tHeaders for GitHub API requests
+\tReturns:
+\t\tbool: True if the tag was deleted or if it was not found, False otherwise
+\t"""
+def delete_existing_release(owner: str, project_name: str, version: str, headers: dict[str, str]) -> None:
+    """ Delete existing release for a version
+
+\tArgs:
+\t\towner\t\t\t(str):\t\t\t\tGitHub username
+\t\tproject_name\t(str):\t\t\t\tName of the GitHub repository
+\t\tversion\t\t\t(str):\t\t\t\tVersion of the release to delete
+\t\theaders\t\t\t(dict[str, str]):\tHeaders for GitHub API requests
+\t"""
+def delete_existing_tag(tag_url: str, headers: dict[str, str]) -> None:
+    """ Delete existing tag
+
+\tArgs:
+\t\ttag_url\t(str):\t\t\t\tURL of the tag to delete
+\t\theaders\t(dict[str, str]):\tHeaders for GitHub API requests
+\t"""
+def get_latest_tag(owner: str, project_name: str, version: str, headers: dict[str, str]) -> tuple[str, str] | tuple[None, None]:
+    """ Get latest tag information
+
+\tArgs:
+\t\towner\t\t\t(str):\t\t\t\tGitHub username
+\t\tproject_name\t(str):\t\t\t\tName of the GitHub repository
+\t\tversion\t\t\t(str):\t\t\t\tVersion to remove from the list of tags
+\t\theaders\t\t\t(dict[str, str]):\tHeaders for GitHub API requests
+\tReturns:
+\t\tstr|None: SHA of the latest tag commit, None if no tags exist
+\t\tstr|None: Version number of the latest tag, None if no tags exist
+\t"""
+def 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
+
+\tArgs:
+\t\towner\t\t\t(str):\t\t\t\tGitHub username
+\t\tproject_name\t(str):\t\t\t\tName of the GitHub repository
+\t\tlatest_tag_sha\t(str|None):\t\t\tSHA of the latest tag commit
+\t\theaders\t\t\t(dict[str, str]):\tHeaders for GitHub API requests
+\tReturns:
+\t\tlist[dict]: List of commits since the last tag
+\t"""
+def 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.
+
+\tConvention format: <type>: <description> or <type>(<sub-category>): <description>
+
+\tArgs:
+\t\tcommits\t\t\t\t(list[dict]):\tList of commits to generate changelog from
+\t\towner\t\t\t\t(str):\t\t\tGitHub username
+\t\tproject_name\t\t(str):\t\t\tName of the GitHub repository
+\t\tlatest_tag_version\t(str|None):\t\tVersion number of the latest tag
+\t\tversion\t\t\t\t(str):\t\t\tCurrent version being released
+\tReturns:
+\t\tstr: Generated changelog text
+\tSource:
+\t\thttps://www.conventionalcommits.org/en/v1.0.0/
+\t"""
+def create_tag(owner: str, project_name: str, version: str, headers: dict[str, str]) -> None:
+    """ Create a new tag
+
+\tArgs:
+\t\towner\t\t\t(str):\t\t\t\tGitHub username
+\t\tproject_name\t(str):\t\t\t\tName of the GitHub repository
+\t\tversion\t\t\t(str):\t\t\t\tVersion for the new tag
+\t\theaders\t\t\t(dict[str, str]):\tHeaders for GitHub API requests
+\t"""
+def create_release(owner: str, project_name: str, version: str, changelog: str, headers: dict[str, str]) -> int:
+    """ Create a new release
+
+\tArgs:
+\t\towner\t\t\t(str):\t\t\t\tGitHub username
+\t\tproject_name\t(str):\t\t\t\tName of the GitHub repository
+\t\tversion\t\t\t(str):\t\t\t\tVersion for the new release
+\t\tchangelog\t\t(str):\t\t\t\tChangelog text for the release
+\t\theaders\t\t\t(dict[str, str]):\tHeaders for GitHub API requests
+\tReturns:
+\t\tint: ID of the created release
+\t"""
+def upload_assets(owner: str, project_name: str, release_id: int, build_folder: str, headers: dict[str, str], endswith: list[str]) -> None:
+    """ Upload release assets
+
+\tArgs:
+\t\towner\t\t\t(str):\t\t\t\tGitHub username
+\t\tproject_name\t(str):\t\t\t\tName of the GitHub repository
+\t\trelease_id\t\t(int):\t\t\t\tID of the release to upload assets to
+\t\tbuild_folder\t(str):\t\t\t\tFolder containing assets to upload
+\t\theaders\t\t\t(dict[str, str]):\tHeaders for GitHub API requests
+\t\tendswith\t\t(list[str]):\t\tList of files to upload to the release
+\t\t\t(every file ending with one of these strings will be uploaded)
+\t"""
+def upload_to_github(credentials: dict[str, Any], github_config: dict[str, Any]) -> str:
+    ''' Upload the project to GitHub using the credentials and the configuration
+
+\tArgs:
+\t\tcredentials\t\t(dict[str, Any]):\tCredentials for the GitHub API
+\t\tgithub_config\t(dict[str, Any]):\tConfiguration for the GitHub project
+\tReturns:
+\t\tstr: Generated changelog text
+\tExamples:
+
+\t.. code-block:: python
+
+\t\t> upload_to_github(
+\t\t\tcredentials={
+\t\t\t\t"github": {
+\t\t\t\t\t"api_key": "ghp_...",
+\t\t\t\t\t"username": "Stoupy"
+\t\t\t\t}
+\t\t\t},
+\t\t\tgithub_config={
+\t\t\t\t"project_name": "stouputils",
+\t\t\t\t"version": "1.0.0",
+\t\t\t\t"build_folder": "build",
+\t\t\t\t"endswith": [".zip"]
+\t\t\t}
+\t\t)
+\t'''

stouputils/continuous_delivery/pypi.py

@@ -0,0 +1,91 @@
+""" This module contains utilities for PyPI.
+(Using build and twine packages)
+
+- pypi_full_routine: Upload the most recent file(s) to PyPI after updating pip and required packages and building the package
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/continuous_delivery/pypi_module.gif
+  :alt: stouputils pypi examples
+"""
+
+# Imports
+import os
+import sys
+from collections.abc import Callable
+
+from ..decorators import LogLevels, handle_error
+
+
+def update_pip_and_required_packages() -> int:
+	""" Update pip and required packages.
+
+	Returns:
+		int: Return code of the os.system call.
+	"""
+	return os.system(f"{sys.executable} -m pip install --upgrade pip setuptools build twine pkginfo packaging")
+
+def build_package() -> int:
+	""" Build the package.
+
+	Returns:
+		int: Return code of the os.system call.
+	"""
+	return os.system(f"{sys.executable} -m build")
+
+def upload_package(repository: str, filepath: str) -> int:
+	""" Upload the package to PyPI.
+
+	Args:
+		repository  (str): Repository to upload to.
+		filepath    (str): Path to the file to upload.
+
+	Returns:
+		int: Return code of the os.system call.
+	"""
+	return os.system(f"{sys.executable} -m twine upload --verbose -r {repository} {filepath}")
+
+@handle_error(message="Error while doing the pypi full routine", error_log=LogLevels.ERROR_TRACEBACK)
+def pypi_full_routine(
+	repository: str,
+	dist_directory: str,
+	last_files: int = 1,
+	endswith: str = ".tar.gz",
+
+	update_all_function: Callable[[], int] = update_pip_and_required_packages,
+	build_package_function: Callable[[], int] = build_package,
+	upload_package_function: Callable[[str, str], int] = upload_package,
+) -> None:
+	""" Upload the most recent file(s) to PyPI after updating pip and required packages and building the package.
+
+	Args:
+		repository               (str):                        Repository to upload to.
+		dist_directory           (str):                        Directory to upload from.
+		last_files               (int):                        Number of most recent files to upload. Defaults to 1.
+		endswith                 (str):                        End of the file name to upload. Defaults to ".tar.gz".
+		update_all_function      (Callable[[], int]):          Function to update pip and required packages.
+			Defaults to :func:`update_pip_and_required_packages`.
+		build_package_function   (Callable[[], int]):          Function to build the package.
+			Defaults to :func:`build_package`.
+		upload_package_function  (Callable[[str, str], int]):  Function to upload the package.
+			Defaults to :func:`upload_package`.
+
+	Returns:
+		int: Return code of the command.
+	"""
+	if update_all_function() != 0:
+		raise Exception("Error while updating pip and required packages")
+
+	if build_package_function() != 0:
+		raise Exception("Error while building the package")
+
+	# Get list of tar.gz files in dist directory sorted by modification time
+	files: list[str] = sorted(
+		[x for x in os.listdir(dist_directory) if x.endswith(endswith)],	# Get list of tar.gz files in dist directory
+		key=lambda x: os.path.getmtime(f"{dist_directory}/{x}"),			# Sort by modification time
+		reverse=True														# Sort in reverse order
+	)
+
+	# Upload the most recent file(s)
+	for file in files[:last_files]:
+		upload_package_function(repository, f"{dist_directory}/{file}")
+
+

stouputils/continuous_delivery/pypi.pyi

@@ -0,0 +1,43 @@
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from collections.abc import Callable as Callable
+
+def update_pip_and_required_packages() -> int:
+    """ Update pip and required packages.
+
+\tReturns:
+\t\tint: Return code of the os.system call.
+\t"""
+def build_package() -> int:
+    """ Build the package.
+
+\tReturns:
+\t\tint: Return code of the os.system call.
+\t"""
+def upload_package(repository: str, filepath: str) -> int:
+    """ Upload the package to PyPI.
+
+\tArgs:
+\t\trepository  (str): Repository to upload to.
+\t\tfilepath    (str): Path to the file to upload.
+
+\tReturns:
+\t\tint: Return code of the os.system call.
+\t"""
+def pypi_full_routine(repository: str, dist_directory: str, last_files: int = 1, endswith: str = '.tar.gz', update_all_function: Callable[[], int] = ..., build_package_function: Callable[[], int] = ..., upload_package_function: Callable[[str, str], int] = ...) -> None:
+    ''' Upload the most recent file(s) to PyPI after updating pip and required packages and building the package.
+
+\tArgs:
+\t\trepository               (str):                        Repository to upload to.
+\t\tdist_directory           (str):                        Directory to upload from.
+\t\tlast_files               (int):                        Number of most recent files to upload. Defaults to 1.
+\t\tendswith                 (str):                        End of the file name to upload. Defaults to ".tar.gz".
+\t\tupdate_all_function      (Callable[[], int]):          Function to update pip and required packages.
+\t\t\tDefaults to :func:`update_pip_and_required_packages`.
+\t\tbuild_package_function   (Callable[[], int]):          Function to build the package.
+\t\t\tDefaults to :func:`build_package`.
+\t\tupload_package_function  (Callable[[str, str], int]):  Function to upload the package.
+\t\t\tDefaults to :func:`upload_package`.
+
+\tReturns:
+\t\tint: Return code of the command.
+\t'''

stouputils/continuous_delivery/pyproject.py

@@ -0,0 +1,147 @@
+""" Utilities for reading, writing and managing pyproject.toml files.
+
+This module provides functions to handle pyproject.toml files, including reading,
+writing, version management and TOML formatting capabilities.
+
+- read_pyproject: Read the pyproject.toml file.
+- write_pyproject: Write to the pyproject.toml file.
+- format_toml_lists: Format TOML lists with proper indentation.
+- increment_version_from_input: Increment the patch version number.
+- increment_version_from_pyproject: Increment version in pyproject.toml.
+- get_version_from_pyproject: Get version from pyproject.toml.
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/continuous_delivery/pyproject_module.gif
+  :alt: stouputils pyproject examples
+"""
+
+# Imports
+from typing import Any
+
+from ..io import super_open
+
+
+def read_pyproject(pyproject_path: str) -> dict[str, Any]:
+	""" Read the pyproject.toml file.
+
+	Args:
+		pyproject_path: Path to the pyproject.toml file.
+	Returns:
+		dict[str, Any]: The content of the pyproject.toml file.
+	Example:
+		>>> content = read_pyproject("pyproject.toml")
+		>>> "." in content["project"]["version"]
+		True
+	"""
+	from msgspec import toml
+	with open(pyproject_path) as file:
+		content = file.read()
+	return toml.decode(content)
+
+
+def format_toml_lists(content: str) -> str:
+	""" Format TOML lists with indentation.
+
+	Args:
+		content (str): The content of the pyproject.toml file.
+	Returns:
+		str: The formatted content with properly indented lists.
+	Example:
+		>>> toml_content = '''[project]
+		... dependencies = [ "tqdm>=4.0.0", "requests>=2.20.0", "pyyaml>=6.0.0", ]'''
+		>>> format_toml_lists(toml_content).replace("\\t", "    ") == '''[project]
+		... dependencies = [
+		...     "tqdm>=4.0.0",
+		...     "requests>=2.20.0",
+		...     "pyyaml>=6.0.0",
+		... ]'''
+		True
+	"""
+	# Split the content into individual lines for processing
+	lines: list[str] = content.split("\n")
+	formatted_lines: list[str] = []
+
+	for line in lines:
+		# Check if line contains a list definition (has both [ ] and = characters)
+		if "[" in line and "]" in line and "=" in line:
+			# Only process simple lists that have one opening and closing bracket
+			if line.count("[") == 1 and line.count("]") == 1:
+				# Split into key and values parts
+				key, values = line.split("=", 1)
+				values = values.strip()
+
+				# Check if values portion is a list
+				if values.startswith("[") and values.endswith("]"):
+					# Parse list values, removing empty entries
+					values = [v.strip() for v in values[1:-1].split(",") if v.strip()]
+
+					# For lists with multiple items, format across multiple lines
+					if len(values) > 1:
+						formatted_lines.append(f"{key}= [")
+						for value in values:
+							formatted_lines.append(f"\t{value},")
+						formatted_lines.append("]")
+					# For single item lists, keep on one line
+					else:
+						formatted_lines.append(f"{key}= [{values[0]}]")
+					continue
+
+		# Keep non-list lines unchanged
+		formatted_lines.append(line)
+
+	# Rejoin all lines with newlines
+	return "\n".join(formatted_lines)
+
+
+def write_pyproject(path: str, content: dict[str, Any]) -> None:
+	""" Write to the pyproject.toml file with properly indented lists.
+
+	Args:
+		path: Path to the pyproject.toml file.
+		content: Content to write to the pyproject.toml file.
+	"""
+	from msgspec.toml import _import_tomli_w  # pyright: ignore[reportPrivateUsage]
+	toml = _import_tomli_w()
+	string: str = "\n" + toml.dumps(content) + "\n"
+	string = format_toml_lists(string)  # Apply formatting
+
+	with super_open(path, "w") as file:
+		file.write(string)
+
+
+def increment_version_from_input(version: str) -> str:
+	""" Increment the version.
+
+	Args:
+		version: The version to increment. (ex: "0.1.0")
+	Returns:
+		str: The incremented version. (ex: "0.1.1")
+	Example:
+		>>> increment_version_from_input("0.1.0")
+		'0.1.1'
+		>>> increment_version_from_input("1.2.9")
+		'1.2.10'
+	"""
+	version_parts: list[str] = version.split(".")
+	version_parts[-1] = str(int(version_parts[-1]) + 1)
+	return ".".join(version_parts)
+
+def increment_version_from_pyproject(path: str) -> None:
+	""" Increment the version in the pyproject.toml file.
+
+	Args:
+		path: Path to the pyproject.toml file.
+	"""
+	pyproject_content: dict[str, Any] = read_pyproject(path)
+	pyproject_content["project"]["version"] = increment_version_from_input(pyproject_content["project"]["version"])
+	write_pyproject(path, pyproject_content)
+
+def get_version_from_pyproject(path: str) -> str:
+	""" Get the version from the pyproject.toml file.
+
+	Args:
+		path: Path to the pyproject.toml file.
+	Returns:
+		str: The version. (ex: "0.1.0")
+	"""
+	return read_pyproject(path)["project"]["version"]
+

stouputils/continuous_delivery/pyproject.pyi

@@ -0,0 +1,67 @@
+from ..io import super_open as super_open
+from typing import Any
+
+def read_pyproject(pyproject_path: str) -> dict[str, Any]:
+    ''' Read the pyproject.toml file.
+
+\tArgs:
+\t\tpyproject_path: Path to the pyproject.toml file.
+\tReturns:
+\t\tdict[str, Any]: The content of the pyproject.toml file.
+\tExample:
+\t\t>>> content = read_pyproject("pyproject.toml")
+\t\t>>> "." in content["project"]["version"]
+\t\tTrue
+\t'''
+def format_toml_lists(content: str) -> str:
+    ''' Format TOML lists with indentation.
+
+\tArgs:
+\t\tcontent (str): The content of the pyproject.toml file.
+\tReturns:
+\t\tstr: The formatted content with properly indented lists.
+\tExample:
+\t\t>>> toml_content = \'\'\'[project]
+\t\t... dependencies = [ "tqdm>=4.0.0", "requests>=2.20.0", "pyyaml>=6.0.0", ]\'\'\'
+\t\t>>> format_toml_lists(toml_content).replace("\\t", "    ") == \'\'\'[project]
+\t\t... dependencies = [
+\t\t...     "tqdm>=4.0.0",
+\t\t...     "requests>=2.20.0",
+\t\t...     "pyyaml>=6.0.0",
+\t\t... ]\'\'\'
+\t\tTrue
+\t'''
+def write_pyproject(path: str, content: dict[str, Any]) -> None:
+    """ Write to the pyproject.toml file with properly indented lists.
+
+\tArgs:
+\t\tpath: Path to the pyproject.toml file.
+\t\tcontent: Content to write to the pyproject.toml file.
+\t"""
+def increment_version_from_input(version: str) -> str:
+    ''' Increment the version.
+
+\tArgs:
+\t\tversion: The version to increment. (ex: "0.1.0")
+\tReturns:
+\t\tstr: The incremented version. (ex: "0.1.1")
+\tExample:
+\t\t>>> increment_version_from_input("0.1.0")
+\t\t\'0.1.1\'
+\t\t>>> increment_version_from_input("1.2.9")
+\t\t\'1.2.10\'
+\t'''
+def increment_version_from_pyproject(path: str) -> None:
+    """ Increment the version in the pyproject.toml file.
+
+\tArgs:
+\t\tpath: Path to the pyproject.toml file.
+\t"""
+def get_version_from_pyproject(path: str) -> str:
+    ''' Get the version from the pyproject.toml file.
+
+\tArgs:
+\t\tpath: Path to the pyproject.toml file.
+\tReturns:
+\t\tstr: The version. (ex: "0.1.0")
+\t'''

stouputils/continuous_delivery/stubs.py

@@ -0,0 +1,86 @@
+""" This module contains utilities for generating stub files using stubgen.
+
+- generate_stubs: Generate stub files for a Python package using stubgen
+- stubs_full_routine: Generate stub files for a Python package
+
+"""
+
+# Imports
+import os
+from collections.abc import Callable
+
+from ..decorators import LogLevels, handle_error
+
+
+def generate_stubs(
+	package_name: str,
+	extra_args: str = "--include-docstrings --include-private",
+) -> int:
+	""" Generate stub files for a Python package using stubgen.
+
+	Note: stubgen generates stubs in the 'out' directory by default in the current working directory.
+
+	Args:
+		package_name  (str): Name of the package to generate stubs for.
+		extra_args    (str): Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
+	Returns:
+		int: Return code of the os.system call.
+	"""
+	try:
+		from mypy.stubgen import main as stubgen_main
+	except ImportError as e:
+		raise ImportError("mypy is required for array_to_disk function. Please install it via 'pip install mypy'.") from e
+	try:
+		stubgen_main(["-p", package_name, *extra_args.split()])
+		return 0
+	except Exception:
+		return 1
+
+def clean_stubs_directory(output_directory: str, package_name: str) -> None:
+	""" Clean the stubs directory by deleting all .pyi files.
+
+	Args:
+		output_directory  (str): Directory to clean.
+		package_name      (str): Package name subdirectory. Only cleans output_directory/package_name.
+	"""
+	target_dir: str = os.path.join(output_directory, package_name)
+	if os.path.exists(target_dir):
+		for root, _, files in os.walk(target_dir):
+			for file in files:
+				if file.endswith(".pyi"):
+					os.remove(os.path.join(root, file))
+
+@handle_error(message="Error while doing the stubs full routine", error_log=LogLevels.ERROR_TRACEBACK)
+def stubs_full_routine(
+	package_name: str,
+	output_directory: str = "typings",
+	extra_args: str = "--include-docstrings --include-private",
+	clean_before: bool = False,
+
+	generate_stubs_function: Callable[[str, str], int] = generate_stubs,
+	clean_stubs_function: Callable[[str, str], None] = clean_stubs_directory,
+) -> None:
+	""" Generate stub files for a Python package using stubgen.
+
+	Note: stubgen generates stubs in the 'out' directory by default in the current working directory.
+
+	Args:
+		package_name              (str):                       Name of the package to generate stubs for.
+		output_directory          (str):                       Directory to clean before generating stubs. Defaults to "typings".
+			This parameter is used for cleaning the directory before stub generation.
+		extra_args                (str):                       Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
+		clean_before              (bool):                      Whether to clean the output directory before generating stubs. Defaults to False.
+		generate_stubs_function   (Callable[[str, str], int]): Function to generate stubs.
+			Defaults to :func:`generate_stubs`.
+		clean_stubs_function      (Callable[[str], None]):     Function to clean the stubs directory.
+			Defaults to :func:`clean_stubs_directory`.
+	Raises:
+		Exception: If stub generation fails.
+	"""
+	if clean_before:
+		clean_stubs_function(output_directory, package_name)
+	extra_args += f" -o {output_directory}"
+
+	if generate_stubs_function(package_name, extra_args) != 0:
+		raise Exception(f"Error while generating stubs for {package_name}")
+

stouputils/continuous_delivery/stubs.pyi

@@ -0,0 +1,39 @@
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from collections.abc import Callable as Callable
+
+def generate_stubs(package_name: str, extra_args: str = '--include-docstrings --include-private') -> int:
+    ''' Generate stub files for a Python package using stubgen.
+
+\tNote: stubgen generates stubs in the \'out\' directory by default in the current working directory.
+
+\tArgs:
+\t\tpackage_name  (str): Name of the package to generate stubs for.
+\t\textra_args    (str): Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
+\tReturns:
+\t\tint: Return code of the os.system call.
+\t'''
+def clean_stubs_directory(output_directory: str, package_name: str) -> None:
+    """ Clean the stubs directory by deleting all .pyi files.
+
+\tArgs:
+\t\toutput_directory  (str): Directory to clean.
+\t\tpackage_name      (str): Package name subdirectory. Only cleans output_directory/package_name.
+\t"""
+def stubs_full_routine(package_name: str, output_directory: str = 'typings', extra_args: str = '--include-docstrings --include-private', clean_before: bool = False, generate_stubs_function: Callable[[str, str], int] = ..., clean_stubs_function: Callable[[str, str], None] = ...) -> None:
+    ''' Generate stub files for a Python package using stubgen.
+
+\tNote: stubgen generates stubs in the \'out\' directory by default in the current working directory.
+
+\tArgs:
+\t\tpackage_name              (str):                       Name of the package to generate stubs for.
+\t\toutput_directory          (str):                       Directory to clean before generating stubs. Defaults to "typings".
+\t\t\tThis parameter is used for cleaning the directory before stub generation.
+\t\textra_args                (str):                       Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
+\t\tclean_before              (bool):                      Whether to clean the output directory before generating stubs. Defaults to False.
+\t\tgenerate_stubs_function   (Callable[[str, str], int]): Function to generate stubs.
+\t\t\tDefaults to :func:`generate_stubs`.
+\t\tclean_stubs_function      (Callable[[str], None]):     Function to clean the stubs directory.
+\t\t\tDefaults to :func:`clean_stubs_directory`.
+\tRaises:
+\t\tException: If stub generation fails.
+\t'''