stouputils 1.6.6__tar.gz → 1.7.0__tar.gz

{stouputils-1.6.6 → stouputils-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.6.6
+Version: 1.7.0
 Summary: Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more.
 Project-URL: Homepage, https://github.com/Stoupy51/stouputils
 Project-URL: Issues, https://github.com/Stoupy51/stouputils/issues

{stouputils-1.6.6 → stouputils-1.7.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.6.6"
+version = "1.7.0"
 description = "Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more."
 readme = "README.md"
 requires-python = ">=3.10"

{stouputils-1.6.6 → stouputils-1.7.0}/stouputils/all_doctests.py

@@ -119,17 +119,25 @@ def launch_tests(root_dir: str, strict: bool = True) -> int:
 	]
 
 	# Display any error lines for each module at the end of the script
-	nb_failed_tests: int = 0
+	total_failed: int = 0
 	for module, result in zip(modules, results, strict=False):
 		if result.failed > 0:
-			error(f"Errors in module {module.__name__}", exit=False)
-			nb_failed_tests += result.failed
+			successful_tests: int = result.attempted - result.failed
+			error(f"Errors in module {module.__name__} ({successful_tests}/{result.attempted} tests passed)", exit=False)
+			total_failed += result.failed
 
 	# Reset force_raise_exception back
 	decorators.force_raise_exception = strict
 
+	# Final info
+	total_tests: int = sum(result.attempted for result in results)
+	successful_tests: int = total_tests - total_failed
+	if total_failed == 0:
+		info(f"All tests passed for all {len(modules)} modules! ({total_tests}/{total_tests} tests passed)")
+	else:
+		error(f"Some tests failed: {successful_tests}/{total_tests} tests passed in total across {len(modules)} modules", exit=False)
 	# Return the number of failed tests
-	return nb_failed_tests
+	return total_failed
 
 
 def test_module_with_progress(module: ModuleType, separator: str) -> TestResults:

{stouputils-1.6.6 → stouputils-1.7.0}/stouputils/applications/automatic_docs.py

@@ -251,12 +251,15 @@ def setup(app: Any) -> None:
 	return conf_content
 
 @simple_cache()
-def get_versions_from_github(github_user: str, github_repo: str) -> list[str]:
+def get_versions_from_github(github_user: str, github_repo: str, recent_minor_versions: int = 2) -> list[str]:
 	""" Get list of versions from GitHub gh-pages branch.
+	Only shows detailed versions for the last N minor versions, and keeps only
+	the latest patch version for older minor versions.
 
 	Args:
-		github_user    (str): GitHub username
-		github_repo    (str): GitHub repository name
+		github_user             (str): GitHub username
+		github_repo             (str): GitHub repository name
+		recent_minor_versions   (int): Number of recent minor versions to show all patches for (-1 for all).
 
 	Returns:
 		list[str]: List of versions, with 'latest' as first element
@@ -266,13 +269,37 @@ def get_versions_from_github(github_user: str, github_repo: str) -> list[str]:
 	try:
 		response = requests.get(f"https://api.github.com/repos/{github_user}/{github_repo}/contents?ref=gh-pages")
 		if response.status_code == 200:
-			contents = response.json()
-			version_list = ["latest", *sorted([
+			contents: list[dict[str, str]] = response.json()
+			all_versions: list[str] = sorted([
 					d["name"].replace("v", "")
 					for d in contents
 					if d["type"] == "dir" and d["name"].startswith("v")
 				], key=version_to_float, reverse=True
-			)]
+			)
+
+			# Group versions by major.minor
+			from collections import defaultdict
+			minor_versions: dict[str, list[str]] = defaultdict(list)
+			for version in all_versions:
+				parts = version.split(".")
+				if len(parts) >= 2:
+					minor_key = f"{parts[0]}.{parts[1]}"
+					minor_versions[minor_key].append(version)
+
+			# Get the sorted minor version keys
+			sorted_minors = sorted(minor_versions.keys(), key=version_to_float, reverse=True)
+
+			# Build final version list
+			final_versions: list[str] = []
+			for i, minor_key in enumerate(sorted_minors):
+				if recent_minor_versions == -1 or i < recent_minor_versions:
+					# Keep all patch versions for the recent minor versions
+					final_versions.extend(minor_versions[minor_key])
+				else:
+					# Keep only the latest patch version for older minor versions
+					final_versions.append(minor_versions[minor_key][0])
+
+			version_list = ["latest", *final_versions]
 	except Exception as e:
 		info(f"Failed to get versions from GitHub: {e}")
 		version_list = ["latest"]
@@ -300,17 +327,19 @@ def generate_index_rst(
 	project: str,
 	github_user: str,
 	github_repo: str,
-	get_versions_function: Callable[[str, str], list[str]] = get_versions_from_github,
+	get_versions_function: Callable[[str, str, int], list[str]] = get_versions_from_github,
+	recent_minor_versions: int = 2,
 ) -> None:
 	""" Generate index.rst from README.md content.
 
 	Args:
-		readme_path             (str): Path to the README.md file
+		readme_path            (str): Path to the README.md file
 		index_path             (str): Path where index.rst should be created
 		project                (str): Name of the project
 		github_user            (str): GitHub username
 		github_repo            (str): GitHub repository name
-		get_versions_function  (Callable[[str, str], list[str]]): Function to get versions from GitHub
+		get_versions_function  (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
+		recent_minor_versions  (int): Number of recent minor versions to show all patches for. Defaults to 2
 	"""
 	# Read README content
 	with open(readme_path, encoding="utf-8") as f:
@@ -320,7 +349,7 @@ def generate_index_rst(
 	version_selector: str = "\n\n**Versions**: "
 
 	# Get versions from GitHub
-	version_list: list[str] = get_versions_function(github_user, github_repo)
+	version_list: list[str] = get_versions_function(github_user, github_repo, recent_minor_versions)
 
 	# Create version links
 	version_links: list[str] = []
@@ -429,8 +458,9 @@ def update_documentation(
 	github_repo: str = "",
 	version: str | None = None,
 	skip_undocumented: bool = True,
+	recent_minor_versions: int = 2,
 
-	get_versions_function: Callable[[str, str], list[str]] = get_versions_from_github,
+	get_versions_function: Callable[[str, str, int], list[str]] = get_versions_from_github,
 	generate_index_function: Callable[..., None] = generate_index_rst,
 	generate_docs_function: Callable[..., None] = generate_documentation,
 	generate_redirect_function: Callable[[str], None] = generate_redirect_html,
@@ -451,8 +481,9 @@ def update_documentation(
 		github_repo                (str): GitHub repository name
 		version                    (str | None): Version to build documentation for (e.g. "1.0.0", defaults to "latest")
 		skip_undocumented          (bool): Whether to skip undocumented members. Defaults to True
+		recent_minor_versions      (int): Number of recent minor versions to show all patches for. Defaults to 2
 
-		get_versions_function      (Callable[[str, str], list[str]]): Function to get versions from GitHub
+		get_versions_function      (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
 		generate_index_function    (Callable[..., None]): Function to generate index.rst
 		generate_docs_function     (Callable[..., None]): Function to generate documentation
 		generate_redirect_function (Callable[[str], None]): Function to create redirect file
@@ -490,15 +521,16 @@ def update_documentation(
 		github_user=github_user,
 		github_repo=github_repo,
 		get_versions_function=get_versions_function,
+		recent_minor_versions=recent_minor_versions,
 	)
 
 	# Clean up old module documentation
 	if os.path.exists(modules_dir):
 		shutil.rmtree(modules_dir)
-		os.makedirs(modules_dir)
+	os.makedirs(modules_dir, exist_ok=True)
 
 	# Get versions and current version for conf.py
-	version_list: list[str] = get_versions_function(github_user, github_repo)
+	version_list: list[str] = get_versions_function(github_user, github_repo, recent_minor_versions)
 	current_version: str = version if version else "latest"
 
 	# Generate conf.py

{stouputils-1.6.6 → stouputils-1.7.0}/stouputils/applications/automatic_docs.pyi

@@ -31,12 +31,15 @@ def get_sphinx_conf_content(project: str, project_dir: str, author: str, current
 \tReturns:
 \t\tstr: Content of the Sphinx configuration file
 \t"""
-def get_versions_from_github(github_user: str, github_repo: str) -> list[str]:
+def get_versions_from_github(github_user: str, github_repo: str, recent_minor_versions: int = 2) -> list[str]:
     """ Get list of versions from GitHub gh-pages branch.
+\tOnly shows detailed versions for the last N minor versions, and keeps only
+\tthe latest patch version for older minor versions.
 
 \tArgs:
-\t\tgithub_user    (str): GitHub username
-\t\tgithub_repo    (str): GitHub repository name
+\t\tgithub_user             (str): GitHub username
+\t\tgithub_repo             (str): GitHub repository name
+\t\trecent_minor_versions   (int): Number of recent minor versions to show all patches for (-1 for all).
 
 \tReturns:
 \t\tlist[str]: List of versions, with 'latest' as first element
@@ -50,16 +53,17 @@ def markdown_to_rst(markdown_content: str) -> str:
 \tReturns:
 \t\tstr: RST content
 \t"""
-def generate_index_rst(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: Callable[[str, str], list[str]] = ...) -> None:
+def generate_index_rst(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: Callable[[str, str, int], list[str]] = ..., recent_minor_versions: int = 2) -> None:
     """ Generate index.rst from README.md content.
 
 \tArgs:
-\t\treadme_path             (str): Path to the README.md file
+\t\treadme_path            (str): Path to the README.md file
 \t\tindex_path             (str): Path where index.rst should be created
 \t\tproject                (str): Name of the project
 \t\tgithub_user            (str): GitHub username
 \t\tgithub_repo            (str): GitHub repository name
-\t\tget_versions_function  (Callable[[str, str], list[str]]): Function to get versions from GitHub
+\t\tget_versions_function  (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
+\t\trecent_minor_versions  (int): Number of recent minor versions to show all patches for. Defaults to 2
 \t"""
 def generate_documentation(source_dir: str, modules_dir: str, project_dir: str, build_dir: str) -> None:
     """ Generate documentation using Sphinx.
@@ -76,7 +80,7 @@ def generate_redirect_html(filepath: str) -> None:
 \tArgs:
 \t\tfilepath (str): Path to the file where the HTML content should be written
 \t"""
-def update_documentation(root_path: str, project: str, project_dir: str = '', author: str = 'Author', copyright: str = '2025, Author', html_logo: str = '', html_favicon: str = '', html_theme: str = 'breeze', github_user: str = '', github_repo: str = '', version: str | None = None, skip_undocumented: bool = True, get_versions_function: Callable[[str, str], list[str]] = ..., generate_index_function: Callable[..., None] = ..., generate_docs_function: Callable[..., None] = ..., generate_redirect_function: Callable[[str], None] = ..., get_conf_content_function: Callable[..., str] = ...) -> None:
+def update_documentation(root_path: str, project: str, project_dir: str = '', author: str = 'Author', copyright: str = '2025, Author', html_logo: str = '', html_favicon: str = '', html_theme: str = 'breeze', github_user: str = '', github_repo: str = '', version: str | None = None, skip_undocumented: bool = True, recent_minor_versions: int = 2, get_versions_function: Callable[[str, str, int], list[str]] = ..., generate_index_function: Callable[..., None] = ..., generate_docs_function: Callable[..., None] = ..., generate_redirect_function: Callable[[str], None] = ..., get_conf_content_function: Callable[..., str] = ...) -> None:
     ''' Update the Sphinx documentation.
 
 \tArgs:
@@ -92,8 +96,9 @@ def update_documentation(root_path: str, project: str, project_dir: str = '', au
 \t\tgithub_repo                (str): GitHub repository name
 \t\tversion                    (str | None): Version to build documentation for (e.g. "1.0.0", defaults to "latest")
 \t\tskip_undocumented          (bool): Whether to skip undocumented members. Defaults to True
+\t\trecent_minor_versions      (int): Number of recent minor versions to show all patches for. Defaults to 2
 
-\t\tget_versions_function      (Callable[[str, str], list[str]]): Function to get versions from GitHub
+\t\tget_versions_function      (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
 \t\tgenerate_index_function    (Callable[..., None]): Function to generate index.rst
 \t\tgenerate_docs_function     (Callable[..., None]): Function to generate documentation
 \t\tgenerate_redirect_function (Callable[[str], None]): Function to create redirect file

{stouputils-1.6.6 → stouputils-1.7.0}/stouputils/continuous_delivery/cd_utils.py

@@ -108,9 +108,11 @@ def 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.
+	Supports pre-release suffixes with numbers: devN/dN (dev), aN (alpha), bN (beta), rcN/cN (release candidate).
+	Ordering: 1.0.0 > 1.0.0rc2 > 1.0.0rc1 > 1.0.0b2 > 1.0.0b1 > 1.0.0a2 > 1.0.0a1 > 1.0.0dev1
 
 	Args:
-		version (str): The version string to convert. (e.g. "v1.0.0.1.2.3")
+		version (str): The version string to convert. (e.g. "v1.0.0.1.2.3", "v2.0.0b2", "v1.0.0rc1")
 	Returns:
 		float: The float representation of the version. (e.g. 0)
 
@@ -124,7 +126,88 @@ def version_to_float(version: str) -> float:
 	1.0000000010020031
 	>>> version_to_float("v2.0") > version_to_float("v1.0.0.1")
 	True
+	>>> 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")
+	True
+	>>> version_to_float("v1.0.0b") > version_to_float("v1.0.0a")
+	True
+	>>> version_to_float("v1.0.0") > version_to_float("v1.0.0b")
+	True
+	>>> version_to_float("v3.0.0a") > version_to_float("v2.9.9")
+	True
+	>>> version_to_float("v1.2.3b") < version_to_float("v1.2.3")
+	True
+	>>> version_to_float("1.0.0") == version_to_float("v1.0.0")
+	True
+	>>> version_to_float("2.0.0.0.0.0.1b") > version_to_float("2.0.0.0.0.0.1a")
+	True
+	>>> version_to_float("2.0.0.0.0.0.1") > version_to_float("2.0.0.0.0.0.1b")
+	True
+	>>> version_to_float("v1.0.0rc") == version_to_float("v1.0.0c")
+	True
+	>>> version_to_float("v1.0.0c") > version_to_float("v1.0.0b")
+	True
+	>>> version_to_float("v1.0.0d") < version_to_float("v1.0.0a")
+	True
+	>>> version_to_float("v1.0.0dev") < version_to_float("v1.0.0a")
+	True
+	>>> version_to_float("v1.0.0dev") == version_to_float("v1.0.0d")
+	True
+	>>> version_to_float("v1.0.0rc2") > version_to_float("v1.0.0rc1")
+	True
+	>>> version_to_float("v1.0.0b2") > version_to_float("v1.0.0b1")
+	True
+	>>> version_to_float("v1.0.0a2") > version_to_float("v1.0.0a1")
+	True
+	>>> version_to_float("v1.0.0dev2") > version_to_float("v1.0.0dev1")
+	True
+	>>> version_to_float("v1.0.0") > version_to_float("v1.0.0rc2") > version_to_float("v1.0.0rc1")
+	True
+	>>> version_to_float("v1.0.0rc1") > version_to_float("v1.0.0b2")
+	True
+	>>> version_to_float("v1.0.0b1") > version_to_float("v1.0.0a2")
+	True
+	>>> version_to_float("v1.0.0a1") > version_to_float("v1.0.0dev2")
+	True
+	>>> 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"]
+	>>> sorted_versions = sorted(versions, key=version_to_float, reverse=True)
+	>>> sorted_versions == versions
+	True
 	"""
+	# Check for pre-release suffixes and calculate suffix modifier
+	# Suffixes are ordered from longest to shortest to avoid partial matches
+	suffix_modifiers: dict[str, int] = {
+		"dev": 4,  # dev is lowest
+		"d": 4,    # d (dev) is lowest
+		"a": 3,    # alpha
+		"b": 2,    # beta
+		"rc": 1,   # rc is highest pre-release
+		"c": 1,    # c (release candidate)
+	}
+	suffix_type: int = 0  # 0 = no suffix, 1-4 = rc/c, b, a, dev/d
+	suffix_number: int = 0
+
+	# Check for suffixes with optional numbers
+	for suffix, modifier in suffix_modifiers.items():
+		if suffix in version:
+			# Find the suffix position
+			suffix_pos: int = version.rfind(suffix)
+			after_suffix: str = version[suffix_pos + len(suffix):]
+
+			# Check if there's a number after the suffix
+			if after_suffix.isdigit():
+				suffix_number = int(after_suffix)
+				version = version[:suffix_pos]
+			elif after_suffix == "":
+				# Suffix at the end without number
+				version = version[:suffix_pos]
+			else:
+				# Not a valid suffix match, continue searching
+				continue
+
+			# Found a valid suffix, set the type and break
+			suffix_type = modifier
+			break
+
 	# Clean the version string by keeping only the numbers and dots
 	version = clean_version(version)
 
@@ -137,5 +220,15 @@ def version_to_float(version: str) -> float:
 	for part in version_parts:
 		total += int(part) * multiplier
 		multiplier /= 1_000
+
+	# Apply pre-release modifier
+	# Pre-releases are represented as negative offsets from the base version
+	# Lower suffix_type = closer to release (rc=1 is closest, dev=4 is furthest)
+	# Higher suffix_number = closer to release within the same suffix type
+	# Formula: base_version - (suffix_type * 1000 - suffix_number) * 1e-9
+	# This ensures: 1.0.0 > 1.0.0rc2 > 1.0.0rc1 > 1.0.0b2 > 1.0.0a2 > 1.0.0dev2
+	if suffix_type > 0:
+		total -= (suffix_type * 1000 - suffix_number) * 1e-9
+
 	return total
 

{stouputils-1.6.6 → stouputils-1.7.0}/stouputils/continuous_delivery/cd_utils.pyi

@@ -61,9 +61,11 @@ def version_to_float(version: str) -> float:
     ''' 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")
+\t\tversion (str): The version string to convert. (e.g. "v1.0.0.1.2.3", "v2.0.0b2", "v1.0.0rc1")
 \tReturns:
 \t\tfloat: The float representation of the version. (e.g. 0)
 
@@ -77,4 +79,50 @@ def version_to_float(version: str) -> float:
 \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'''