stouputils 1.6.5__tar.gz → 1.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.6.5
+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.5 → stouputils-1.7.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.6.5"
+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.5 → 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.5 → 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.5 → 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.5 → 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.5 → 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'''

{stouputils-1.6.5 → stouputils-1.7.0}/stouputils/io.py

@@ -80,16 +80,22 @@ def relative_path(file_path: str, relative_to: str = "") -> str:
 		return file_path or "."
 
 # JSON dump with indentation for levels
-def super_json_dump(data: Any, file: IO[Any]|None = None, max_level: int = 2, indent: str | int = '\t', suffix: str = "\n") -> str:
+def super_json_dump(
+	data: Any,
+	file: IO[Any] | str | None = None,
+	max_level: int | None = 2,
+	indent: str | int = '\t',
+	suffix: str = "\n"
+) -> str:
 	r""" Writes the provided data to a JSON file with a specified indentation depth.
 	For instance, setting max_level to 2 will limit the indentation to 2 levels.
 
 	Args:
-		data (Any): 				The data to dump (usually a dict or a list)
-		file (IO[Any]): 			The file to dump the data to, if None, the data is returned as a string
-		max_level (int):			The depth of indentation to stop at (-1 for infinite)
-		indent (str | int):			The indentation character (default: '\t')
-		suffix (str):				The suffix to add at the end of the string (default: '\n')
+		data		(Any): 				The data to dump (usually a dict or a list)
+		file		(IO[Any] | str): 	The file object or path to dump the data to
+		max_level	(int | None):		The depth of indentation to stop at (-1 for infinite), None will default to 2
+		indent		(str | int):		The indentation character (default: '\t')
+		suffix		(str):				The suffix to add at the end of the string (default: '\n')
 	Returns:
 		str: The content of the file in every case
 
@@ -102,9 +108,11 @@ def super_json_dump(data: Any, file: IO[Any]|None = None, max_level: int = 2, in
 	>>> super_json_dump({"a": [[1,2,3]], "b": 2}, max_level = 3)
 	'{\n\t"a": [\n\t\t[\n\t\t\t1,\n\t\t\t2,\n\t\t\t3\n\t\t]\n\t],\n\t"b": 2\n}\n'
 	"""
-	# Normalize indentation to string
+	# Normalize indentation to string, and handle None values for max_level
 	if isinstance(indent, int):
 		indent = ' ' * indent
+	if max_level is None:
+		max_level = 2
 
 	# Dump content with 2-space indent and replace it with the desired indent
 	content: str = orjson.dumps(data, option=orjson.OPT_INDENT_2).decode("utf-8")
@@ -128,7 +136,11 @@ def super_json_dump(data: Any, file: IO[Any]|None = None, max_level: int = 2, in
 	# Final newline and write
 	content += suffix
 	if file:
-		file.write(content)
+		if isinstance(file, str):
+			with super_open(file, "w") as f:
+				f.write(content)
+		else:
+			file.write(content)
 	return content
 
 # JSON load from file path
@@ -144,17 +156,26 @@ def super_json_load(file_path: str) -> Any:
 		return orjson.loads(f.read())
 
 # CSV dump to file
-def super_csv_dump(data: Any, file: IO[Any] | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
-	""" Writes data to a CSV file with customizable options
+def super_csv_dump(
+	data: Any,
+	file: IO[Any] | str | None = None,
+	delimiter: str = ',',
+	has_header: bool = True,
+	index: bool = False,
+	*args: Any,
+	**kwargs: Any
+) -> str:
+	""" Writes data to a CSV file with customizable options and returns the CSV content as a string.
 
 	Args:
-		data (list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame): The data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
-		file (IO[Any]): The file to dump the data to, if None, the data is returned as a string
-		delimiter (str): The delimiter to use (default: ',')
-		has_header (bool): Whether to include headers (default: True, applies to dict and DataFrame data)
-		index (bool): Whether to include the index (default: False, only applies to pandas DataFrame)
-		*args: Additional positional arguments to pass to the underlying CSV writer or DataFrame method
-		**kwargs: Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
+		data		(list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame):
+						The data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
+		file		(IO[Any] | str): The file object or path to dump the data to
+		delimiter	(str): The delimiter to use (default: ',')
+		has_header	(bool): Whether to include headers (default: True, applies to dict and DataFrame data)
+		index		(bool): Whether to include the index (default: False, only applies to pandas DataFrame)
+		*args		(Any): Additional positional arguments to pass to the underlying CSV writer or DataFrame method
+		**kwargs	(Any): Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
 	Returns:
 		str: The CSV content as a string
 
@@ -213,7 +234,11 @@ def super_csv_dump(data: Any, file: IO[Any] | None = None, delimiter: str = ',',
 
 	content: str = output.getvalue()
 	if file:
-		file.write(content)
+		if isinstance(file, str):
+			with super_open(file, "w") as f:
+				f.write(content)
+		else:
+			file.write(content)
 	output.close()
 	return content
 
@@ -265,14 +290,14 @@ def super_csv_load(file_path: str, delimiter: str = ',', has_header: bool = True
 		if use_polars:
 			import polars as pl  # type: ignore
 			if not os.path.exists(file_path):
-				return pl.DataFrame()
+				return pl.DataFrame() # type: ignore
 			kwargs.setdefault("separator", delimiter)
 			kwargs.setdefault("has_header", has_header)
-			return pl.read_csv(file_path, *args, **kwargs)
+			return pl.read_csv(file_path, *args, **kwargs) # type: ignore
 		else:
 			import pandas as pd  # type: ignore
 			if not os.path.exists(file_path):
-				return pd.DataFrame()
+				return pd.DataFrame() # type: ignore
 			kwargs.setdefault("sep", delimiter)
 			kwargs.setdefault("header", 0 if has_header else None)
 			return pd.read_csv(file_path, *args, **kwargs) # type: ignore

{stouputils-1.6.5 → stouputils-1.7.0}/stouputils/io.pyi

@@ -35,16 +35,16 @@ def relative_path(file_path: str, relative_to: str = '') -> str:
 \t\t>>> relative_path("D:/some/random/path/stouputils/io.py", "D:\\\\some\\\\")
 \t\t\'random/path/stouputils/io.py\'
 \t'''
-def super_json_dump(data: Any, file: IO[Any] | None = None, max_level: int = 2, indent: str | int = '\t', suffix: str = '\n') -> str:
+def super_json_dump(data: Any, file: IO[Any] | str | None = None, max_level: int | None = 2, indent: str | int = '\t', suffix: str = '\n') -> str:
     ''' Writes the provided data to a JSON file with a specified indentation depth.
 \tFor instance, setting max_level to 2 will limit the indentation to 2 levels.
 
 \tArgs:
-\t\tdata (Any): \t\t\t\tThe data to dump (usually a dict or a list)
-\t\tfile (IO[Any]): \t\t\tThe file to dump the data to, if None, the data is returned as a string
-\t\tmax_level (int):\t\t\tThe depth of indentation to stop at (-1 for infinite)
-\t\tindent (str | int):\t\t\tThe indentation character (default: \'\\t\')
-\t\tsuffix (str):\t\t\t\tThe suffix to add at the end of the string (default: \'\\n\')
+\t\tdata\t\t(Any): \t\t\t\tThe data to dump (usually a dict or a list)
+\t\tfile\t\t(IO[Any] | str): \tThe file object or path to dump the data to
+\t\tmax_level\t(int | None):\t\tThe depth of indentation to stop at (-1 for infinite), None will default to 2
+\t\tindent\t\t(str | int):\t\tThe indentation character (default: \'\\t\')
+\t\tsuffix\t\t(str):\t\t\t\tThe suffix to add at the end of the string (default: \'\\n\')
 \tReturns:
 \t\tstr: The content of the file in every case
 
@@ -65,17 +65,18 @@ def super_json_load(file_path: str) -> Any:
 \tReturns:
 \t\tAny: The content of the JSON file
 \t"""
-def super_csv_dump(data: Any, file: IO[Any] | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
-    ''' Writes data to a CSV file with customizable options
+def super_csv_dump(data: Any, file: IO[Any] | str | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
+    ''' Writes data to a CSV file with customizable options and returns the CSV content as a string.
 
 \tArgs:
-\t\tdata (list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame): The data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
-\t\tfile (IO[Any]): The file to dump the data to, if None, the data is returned as a string
-\t\tdelimiter (str): The delimiter to use (default: \',\')
-\t\thas_header (bool): Whether to include headers (default: True, applies to dict and DataFrame data)
-\t\tindex (bool): Whether to include the index (default: False, only applies to pandas DataFrame)
-\t\t*args: Additional positional arguments to pass to the underlying CSV writer or DataFrame method
-\t\t**kwargs: Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
+\t\tdata\t\t(list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame):
+\t\t\t\t\t\tThe data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
+\t\tfile\t\t(IO[Any] | str): The file object or path to dump the data to
+\t\tdelimiter\t(str): The delimiter to use (default: \',\')
+\t\thas_header\t(bool): Whether to include headers (default: True, applies to dict and DataFrame data)
+\t\tindex\t\t(bool): Whether to include the index (default: False, only applies to pandas DataFrame)
+\t\t*args\t\t(Any): Additional positional arguments to pass to the underlying CSV writer or DataFrame method
+\t\t**kwargs\t(Any): Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
 \tReturns:
 \t\tstr: The CSV content as a string