stouputils 1.14.0__py3-none-any.whl → 1.14.1__py3-none-any.whl

stouputils/continuous_delivery/__init__.pyi

@@ -0,0 +1,5 @@
+from .cd_utils import *
+from .github import *
+from .pypi import *
+from .pyproject import *
+from .stubs import *

stouputils/continuous_delivery/cd_utils.pyi

@@ -0,0 +1,129 @@
+import requests
+from ..decorators import handle_error as handle_error
+from ..io import clean_path as clean_path, json_load as json_load
+from ..print import warning as warning
+from typing import Any
+
+def load_credentials(credentials_path: str) -> dict[str, Any]:
+    ''' Load credentials from a JSON or YAML file into a dictionary.
+
+\tLoads credentials from either a JSON or YAML file and returns them as a dictionary.
+\tThe file must contain the required credentials in the appropriate format.
+
+\tArgs:
+\t\tcredentials_path (str): Path to the credentials file (.json or .yml)
+\tReturns:
+\t\tdict[str, Any]: Dictionary containing the credentials
+
+\tExample JSON format:
+
+\t.. code-block:: json
+
+\t\t{
+\t\t\t"github": {
+\t\t\t\t"username": "Stoupy51",
+\t\t\t\t"api_key": "ghp_XXXXXXXXXXXXXXXXXXXXXXXXXX"
+\t\t\t}
+\t\t}
+
+\tExample YAML format:
+
+\t.. code-block:: yaml
+
+\t\tgithub:
+\t\t\tusername: "Stoupy51"
+\t\t\tapi_key: "ghp_XXXXXXXXXXXXXXXXXXXXXXXXXX"
+\t'''
+def handle_response(response: requests.Response, error_message: str) -> None:
+    """ Handle a response from the API by raising an error if the response is not successful (status code not in 200-299).
+
+\tArgs:
+\t\tresponse\t\t(requests.Response): The response from the API
+\t\terror_message\t(str): The error message to raise if the response is not successful
+\t"""
+def clean_version(version: str, keep: str = '') -> str:
+    ''' Clean a version string
+
+\tArgs:
+\t\tversion\t(str): The version string to clean
+\t\tkeep\t(str): The characters to keep in the version string
+\tReturns:
+\t\tstr: The cleaned version string
+
+\t>>> clean_version("v1.e0.zfezf0.1.2.3zefz")
+\t\'1.0.0.1.2.3\'
+\t>>> clean_version("v1.e0.zfezf0.1.2.3zefz", keep="v")
+\t\'v1.0.0.1.2.3\'
+\t>>> clean_version("v1.2.3b", keep="ab")
+\t\'1.2.3b\'
+\t'''
+def version_to_float(version: str, error: bool = True) -> Any:
+    ''' Converts a version string into a float for comparison purposes.
+\tThe version string is expected to follow the format of major.minor.patch.something_else....,
+\twhere each part is separated by a dot and can be extended indefinitely.
+\tSupports pre-release suffixes with numbers: devN/dN (dev), aN (alpha), bN (beta), rcN/cN (release candidate).
+\tOrdering: 1.0.0 > 1.0.0rc2 > 1.0.0rc1 > 1.0.0b2 > 1.0.0b1 > 1.0.0a2 > 1.0.0a1 > 1.0.0dev1
+
+\tArgs:
+\t\tversion (str): The version string to convert. (e.g. "v1.0.0.1.2.3", "v2.0.0b2", "v1.0.0rc1")
+\t\terror (bool): Return None on error instead of raising an exception
+\tReturns:
+\t\tfloat: The float representation of the version. (e.g. 0)
+
+\t>>> version_to_float("v1.0.0")
+\t1.0
+\t>>> version_to_float("v1.0.0.1")
+\t1.000000001
+\t>>> version_to_float("v2.3.7")
+\t2.003007
+\t>>> version_to_float("v1.0.0.1.2.3")
+\t1.0000000010020031
+\t>>> version_to_float("v2.0") > version_to_float("v1.0.0.1")
+\tTrue
+\t>>> version_to_float("v2.0.0") > version_to_float("v2.0.0rc") > version_to_float("v2.0.0b") > version_to_float("v2.0.0a") > version_to_float("v2.0.0dev")
+\tTrue
+\t>>> version_to_float("v1.0.0b") > version_to_float("v1.0.0a")
+\tTrue
+\t>>> version_to_float("v1.0.0") > version_to_float("v1.0.0b")
+\tTrue
+\t>>> version_to_float("v3.0.0a") > version_to_float("v2.9.9")
+\tTrue
+\t>>> version_to_float("v1.2.3b") < version_to_float("v1.2.3")
+\tTrue
+\t>>> version_to_float("1.0.0") == version_to_float("v1.0.0")
+\tTrue
+\t>>> version_to_float("2.0.0.0.0.0.1b") > version_to_float("2.0.0.0.0.0.1a")
+\tTrue
+\t>>> version_to_float("2.0.0.0.0.0.1") > version_to_float("2.0.0.0.0.0.1b")
+\tTrue
+\t>>> version_to_float("v1.0.0rc") == version_to_float("v1.0.0c")
+\tTrue
+\t>>> version_to_float("v1.0.0c") > version_to_float("v1.0.0b")
+\tTrue
+\t>>> version_to_float("v1.0.0d") < version_to_float("v1.0.0a")
+\tTrue
+\t>>> version_to_float("v1.0.0dev") < version_to_float("v1.0.0a")
+\tTrue
+\t>>> version_to_float("v1.0.0dev") == version_to_float("v1.0.0d")
+\tTrue
+\t>>> version_to_float("v1.0.0rc2") > version_to_float("v1.0.0rc1")
+\tTrue
+\t>>> version_to_float("v1.0.0b2") > version_to_float("v1.0.0b1")
+\tTrue
+\t>>> version_to_float("v1.0.0a2") > version_to_float("v1.0.0a1")
+\tTrue
+\t>>> version_to_float("v1.0.0dev2") > version_to_float("v1.0.0dev1")
+\tTrue
+\t>>> version_to_float("v1.0.0") > version_to_float("v1.0.0rc2") > version_to_float("v1.0.0rc1")
+\tTrue
+\t>>> version_to_float("v1.0.0rc1") > version_to_float("v1.0.0b2")
+\tTrue
+\t>>> version_to_float("v1.0.0b1") > version_to_float("v1.0.0a2")
+\tTrue
+\t>>> version_to_float("v1.0.0a1") > version_to_float("v1.0.0dev2")
+\tTrue
+\t>>> versions = ["v1.0.0", "v1.0.0rc2", "v1.0.0rc1", "v1.0.0b2", "v1.0.0b1", "v1.0.0a2", "v1.0.0a1", "v1.0.0dev2", "v1.0.0dev1"]
+\t>>> sorted_versions = sorted(versions, key=version_to_float, reverse=True)
+\t>>> sorted_versions == versions
+\tTrue
+\t'''

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

@@ -0,0 +1,52 @@
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from .pyproject import read_pyproject as read_pyproject
+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'''
+def pypi_full_routine_using_uv() -> None:
+    """ Full build and publish routine using 'uv' command line tool.
+
+\tSteps:
+\t\t1. Generate stubs unless '--no-stubs' is passed
+\t\t2. Build the package using 'uv build'
+\t\t3. Upload the most recent file to PyPI using 'uv publish'
+\t"""

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

stouputils/ctx.pyi

@@ -0,0 +1,211 @@
+import abc
+from .io import super_open as super_open
+from .print import TeeMultiOutput as TeeMultiOutput, debug as debug
+from collections.abc import Callable as Callable
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import Any, IO, TextIO, TypeVar
+
+T = TypeVar('T')
+
+class AbstractBothContextManager[T](AbstractContextManager[T], AbstractAsyncContextManager[T], metaclass=abc.ABCMeta):
+    """ Abstract base class for context managers that support both synchronous and asynchronous usage. """
+
+class LogToFile(AbstractBothContextManager['LogToFile']):
+    ''' Context manager to log to a file.
+
+\tThis context manager allows you to temporarily log output to a file while still printing normally.
+\tThe file will receive log messages without ANSI color codes.
+
+\tArgs:
+\t\tpath (str): Path to the log file
+\t\tmode (str): Mode to open the file in (default: "w")
+\t\tencoding (str): Encoding to use for the file (default: "utf-8")
+\t\ttee_stdout (bool): Whether to redirect stdout to the file (default: True)
+\t\ttee_stderr (bool): Whether to redirect stderr to the file (default: True)
+\t\tignore_lineup (bool): Whether to ignore lines containing LINE_UP escape sequence in files (default: False)
+\t\trestore_on_exit (bool): Whether to restore original stdout/stderr on exit (default: False)
+\t\t\tThis ctx uses TeeMultiOutput which handles closed files gracefully, so restoring is not mandatory.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> import stouputils as stp
+\t\t\t> with stp.LogToFile("output.log"):
+\t\t\t>     stp.info("This will be logged to output.log and printed normally")
+\t\t\t>     print("This will also be logged")
+
+\t\t\t> with stp.LogToFile("output.log") as log_ctx:
+\t\t\t>     stp.warning("This will be logged to output.log and printed normally")
+\t\t\t>     log_ctx.change_file("new_file.log")
+\t\t\t>     print("This will be logged to new_file.log")
+\t'''
+    path: str
+    mode: str
+    encoding: str
+    tee_stdout: bool
+    tee_stderr: bool
+    ignore_lineup: bool
+    restore_on_exit: bool
+    file: IO[Any]
+    original_stdout: TextIO
+    original_stderr: TextIO
+    def __init__(self, path: str, mode: str = 'w', encoding: str = 'utf-8', tee_stdout: bool = True, tee_stderr: bool = True, ignore_lineup: bool = True, restore_on_exit: bool = False) -> None: ...
+    def __enter__(self) -> LogToFile:
+        """ Enter context manager which opens the log file and redirects stdout/stderr """
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit context manager which closes the log file and restores stdout/stderr """
+    async def __aenter__(self) -> LogToFile:
+        """ Enter async context manager which opens the log file and redirects stdout/stderr """
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit async context manager which closes the log file and restores stdout/stderr """
+    def change_file(self, new_path: str) -> None:
+        """ Change the log file to a new path.
+
+\t\tArgs:
+\t\t\tnew_path (str): New path to the log file
+\t\t"""
+    @staticmethod
+    def common(logs_folder: str, filepath: str, func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        ''' Common code used at the beginning of a program to launch main function
+
+\t\tArgs:
+\t\t\tlogs_folder (str): Folder to store logs in
+\t\t\tfilepath    (str): Path to the main function
+\t\t\tfunc        (Callable[..., Any]): Main function to launch
+\t\t\t*args       (tuple[Any, ...]): Arguments to pass to the main function
+\t\t\t**kwargs    (dict[str, Any]): Keyword arguments to pass to the main function
+\t\tReturns:
+\t\t\tAny: Return value of the main function
+
+\t\tExamples:
+\t\t\t>>> if __name__ == "__main__":
+\t\t\t...     LogToFile.common(f"{ROOT}/logs", __file__, main)
+\t\t'''
+
+class MeasureTime(AbstractBothContextManager['MeasureTime']):
+    ''' Context manager to measure execution time.
+
+\tThis context manager measures the execution time of the code block it wraps
+\tand prints the result using a specified print function.
+
+\tArgs:
+\t\tprint_func      (Callable): Function to use to print the execution time (e.g. debug, info, warning, error, etc.).
+\t\tmessage         (str):      Message to display with the execution time. Defaults to "Execution time".
+\t\tperf_counter    (bool):     Whether to use time.perf_counter_ns or time.time_ns. Defaults to True.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> import time
+\t\t\t> import stouputils as stp
+\t\t\t> with stp.MeasureTime(stp.info, message="My operation"):
+\t\t\t...     time.sleep(0.5)
+\t\t\t> # [INFO HH:MM:SS] My operation: 500.123ms (500123456ns)
+
+\t\t\t> with stp.MeasureTime(): # Uses debug by default
+\t\t\t...     time.sleep(0.1)
+\t\t\t> # [DEBUG HH:MM:SS] Execution time: 100.456ms (100456789ns)
+\t'''
+    print_func: Callable[..., None]
+    message: str
+    perf_counter: bool
+    ns: Callable[[], int]
+    start_ns: int
+    def __init__(self, print_func: Callable[..., None] = ..., message: str = 'Execution time', perf_counter: bool = True) -> None: ...
+    def __enter__(self) -> MeasureTime:
+        """ Enter context manager, record start time """
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit context manager, calculate duration and print """
+    async def __aenter__(self) -> MeasureTime:
+        """ Enter async context manager, record start time """
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit async context manager, calculate duration and print """
+
+class Muffle(AbstractBothContextManager['Muffle']):
+    ''' Context manager that temporarily silences output.
+\t(No thread-safety guaranteed)
+
+\tAlternative to stouputils.decorators.silent()
+
+\tExamples:
+\t\t>>> with Muffle():
+\t\t...     print("This will not be printed")
+\t'''
+    mute_stderr: bool
+    original_stdout: IO[Any]
+    original_stderr: IO[Any]
+    def __init__(self, mute_stderr: bool = False) -> None: ...
+    def __enter__(self) -> Muffle:
+        """ Enter context manager which redirects stdout and stderr to devnull """
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit context manager which restores original stdout and stderr """
+    async def __aenter__(self) -> Muffle:
+        """ Enter async context manager which redirects stdout and stderr to devnull """
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit async context manager which restores original stdout and stderr """
+
+class DoNothing(AbstractBothContextManager['DoNothing']):
+    ''' Context manager that does nothing.
+
+\tThis is a no-op context manager that can be used as a placeholder
+\tor for conditional context management.
+
+\tDifferent from contextlib.nullcontext because it handles args and kwargs,
+\talong with **async** context management.
+
+\tExamples:
+\t\t>>> with DoNothing():
+\t\t...     print("This will be printed normally")
+\t\tThis will be printed normally
+
+\t\t>>> # Conditional context management
+\t\t>>> some_condition = True
+\t\t>>> ctx = DoNothing() if some_condition else Muffle()
+\t\t>>> with ctx:
+\t\t...     print("May or may not be printed depending on condition")
+\t\tMay or may not be printed depending on condition
+\t'''
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """ No initialization needed, this is a no-op context manager """
+    def __enter__(self) -> DoNothing:
+        """ Enter context manager (does nothing) """
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """ Exit context manager (does nothing) """
+    async def __aenter__(self) -> DoNothing:
+        """ Enter async context manager (does nothing) """
+    async def __aexit__(self, *excinfo: Any) -> None:
+        """ Exit async context manager (does nothing) """
+NullContextManager = DoNothing
+
+class SetMPStartMethod(AbstractBothContextManager['SetMPStartMethod']):
+    ''' Context manager to temporarily set multiprocessing start method.
+
+\tThis context manager allows you to temporarily change the multiprocessing start method
+\tand automatically restores the original method when exiting the context.
+
+\tArgs:
+\t\tstart_method (str): The start method to use: "spawn", "fork", or "forkserver"
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> import multiprocessing as mp
+\t\t\t> import stouputils as stp
+\t\t\t> # Temporarily use spawn method
+\t\t\t> with stp.SetMPStartMethod("spawn"):
+\t\t\t> ...     # Your multiprocessing code here
+\t\t\t> ...     pass
+
+\t\t\t> # Original method is automatically restored
+\t'''
+    start_method: str | None
+    old_method: str | None
+    def __init__(self, start_method: str | None) -> None: ...
+    def __enter__(self) -> SetMPStartMethod:
+        """ Enter context manager which sets the start method """
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """ Exit context manager which restores the original start method """
+    async def __aenter__(self) -> SetMPStartMethod:
+        """ Enter async context manager which sets the start method """
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """ Exit async context manager which restores the original start method """