stouputils 1.0.21__tar.gz → 1.0.23__tar.gz

{stouputils-1.0.21 → stouputils-1.0.23}/.github/workflows/documentation.yml

@@ -20,7 +20,7 @@ jobs:
       - uses: actions/setup-python@v5
       - name: Install dependencies
         run: |
-          pip install hatch stouputils sphinx sphinx_rtd_theme myst_parser
+          pip install hatch stouputils sphinx sphinx_rtd_theme myst_parser furo
           hatch build
       - name: Build latest docs
         if: github.ref == 'refs/heads/main'
@@ -37,5 +37,6 @@ jobs:
           publish_branch: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: docs/build/html
+          keep_files: true
           force_orphan: false
 

{stouputils-1.0.21 → stouputils-1.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.0.21
+Version: 1.0.23
 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
@@ -10,8 +10,9 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
-Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: pyyaml
 Requires-Dist: requests>=2.31.0
+Requires-Dist: toml
 Requires-Dist: tqdm>=4.66.4
 Description-Content-Type: text/markdown
 

stouputils-1.0.23/build_all_in_one.py

@@ -0,0 +1,20 @@
+
+# Imports
+import stouputils as stp
+
+# Constants
+ROOT: str = stp.get_root_path(__file__)
+REPOSITORY: str = "stouputils"
+DIST_DIRECTORY: str = f"{ROOT}/dist"
+LAST_FILES: int = 1
+ENDWITH: str = ".tar.gz"
+
+if __name__ == "__main__":
+
+	stp.pypi_full_routine(
+		repository=REPOSITORY,
+		dist_directory=DIST_DIRECTORY,
+		last_files=LAST_FILES,
+		endswith=ENDWITH,
+	)
+

stouputils-1.0.23/examples/all_doctests.py

@@ -0,0 +1,13 @@
+
+# Imports
+import stouputils as stp
+
+# Main
+@stp.measure_time(stp.info, message="All doctests finished")
+def main() -> None:
+	FOLDER_TO_TEST: str = stp.get_root_path(__file__, 1) + "/src"
+	stp.launch_tests(FOLDER_TO_TEST)
+
+if __name__ == "__main__":
+	main()
+

stouputils-1.0.23/examples/archive.py

@@ -0,0 +1,24 @@
+
+# Imports
+import stouputils as stp
+from zipfile import ZipFile, BadZipFile
+
+# Main
+if __name__ == "__main__":
+	PREFIX: str = "examples/archive"
+
+	## Repair a corrupted zip file
+	# Try to read the first file
+	@stp.handle_error(BadZipFile)
+	def read_file() -> None:
+		with ZipFile(f"{PREFIX}/corrupted.zip", "r") as zip_file:
+			stp.info(zip_file.read("pack.mcmeta"))
+	read_file()
+
+	# Repair it
+	stp.repair_zip_file(f"{PREFIX}/corrupted.zip", f"{PREFIX}/repaired.zip")
+
+	# Read the first file
+	with ZipFile(f"{PREFIX}/repaired.zip", "r") as zip_file:
+		stp.info(zip_file.read("pack.mcmeta"))
+

stouputils-1.0.23/examples/collections.py

@@ -0,0 +1,28 @@
+
+# Imports
+import stouputils as stp
+
+# Main
+if __name__ == "__main__":
+	
+	# Example with numbers
+	numbers: list[int] = [1, 2, 3, 2, 1, 4, 3]
+	unique_numbers: list[int] = stp.unique_list(numbers)
+	stp.info(f"Original numbers: {numbers}")
+	stp.info(f"Unique numbers: {unique_numbers}")
+	
+	# Example with sets using different methods
+	s1: set[int] = {1, 2, 3}
+	s2: set[int] = {2, 3, 4}
+	s3: set[int] = {1, 2, 3}
+	sets: list[set[int]] = [s1, s2, s1, s1, s3, s2, s3]
+	
+	# Using id method (keeps s1 and s3 as separate objects)
+	unique_sets_id: list[set[int]] = stp.unique_list(sets, method="id")
+	stp.info(f"Unique sets (id method): {unique_sets_id}")
+	
+	# Using str method (combines s1 and s3 as they have same string representation)
+	unique_sets_str: list[set[int]] = stp.unique_list(sets, method="str")
+	stp.info(f"Unique sets (str method): {unique_sets_str}")
+
+

stouputils-1.0.23/examples/ctx.py

@@ -0,0 +1,25 @@
+
+# Imports
+import stouputils as stp
+import sys
+import os
+
+# Main
+if __name__ == "__main__":
+	
+	with stp.Muffle(mute_stderr=True):
+		print("Nothing")
+		print("here", file=sys.stderr)
+		stp.info("will be")
+		stp.info("printed", file=sys.stderr)
+
+	OUTPUT_PATH: str = "_super_idol_de_xiao_rong.log"
+	with stp.LogToFile(OUTPUT_PATH):
+		stp.info("""
+Why did the programmer always bring a ladder to work?
+Because they spent so much time debugging and climbing through their log files!
+""")
+		
+	stp.breakpoint("Press Enter to continue...")
+	os.remove(OUTPUT_PATH)
+

stouputils-1.0.23/examples/decorators_1.py

@@ -0,0 +1,29 @@
+
+# Imports
+import stouputils as stp
+import time
+
+# Main
+if __name__ == "__main__":
+	
+	# Cache the result of the function and measure the time it takes to execute
+	@stp.measure_time(stp.progress, "Time taken to execute long_function")
+	@stp.simple_cache()
+	def long_function() -> dict[str, int]:
+		stp.info("Starting long function...")
+		time.sleep(1)
+		stp.info("Long function finished!")
+		return {"a": 1, "b": 2}
+	
+	a = long_function()		# Takes 1 second
+	b = long_function()		# Takes 0 second
+	stp.info(f"a: {a}, b: {b}, a is b: {a is b}")
+	b["c"] = 3
+	stp.info(f"a has been modified because a is b: {a}")
+
+	# Silent decorator
+	@stp.silent
+	def silent_function():
+		print("ON THE CONSOLE")
+	silent_function()
+

stouputils-1.0.23/examples/decorators_2.py

@@ -0,0 +1,21 @@
+
+# Imports
+import stouputils as stp
+
+# Main
+if __name__ == "__main__":
+
+	# Handle exceptions
+	@stp.handle_error(ZeroDivisionError,
+		"Debugging: The process of removing software bugs, and putting in new ones",
+		error_log=stp.LogLevels.WARNING_TRACEBACK
+	)
+	def raise_value_error():
+		return 1 / 0
+
+	@stp.handle_error()
+	def raise_value_error_2():
+		return 1 / 0
+
+	raise_value_error()			# This will show the error using stp.warning
+	raise_value_error_2()		# This will show the error using stp.error

stouputils-1.0.23/examples/delta_backup.py

@@ -0,0 +1,7 @@
+
+# Example of use:
+# py examples/delta_backup.py delta "src" "backup" -x "*pycache*"
+
+import stouputils as stp
+stp.backup_cli()
+

stouputils-1.0.23/examples/io.py

@@ -0,0 +1,33 @@
+
+# Imports
+import stouputils as stp
+from typing import Any
+
+# Main
+if __name__ == "__main__":
+	
+	path: str = "C:\\\\Users\\\\Stoupy\\\\Documents\\\\test.txt"
+	path = stp.clean_path(path)
+	stp.info(path)
+
+	tilde_path: str = "~/Desktop/OnlyFansIncome.txt"
+	tilde_path = stp.replace_tilde(tilde_path)
+	stp.info(tilde_path)
+
+	this_folder_dont_exist: str = "./this_folder_dont_exist/a/c/feff/efefe/a"
+	with stp.super_open(this_folder_dont_exist, "w") as file:	# Automatically create the folder
+		file.write("Hello, world!")
+	
+	# Copy a file to a folder, or rename the copied file
+	stp.super_copy("LICENSE", "this_folder_dont_exist/a/")           # .../a/LICENSE
+	stp.super_copy("LICENSE", "this_folder_dont_exist/a/LICENSE_2")  # .../a/LICENSE_2
+	stp.breakpoint("Waiting for input to continue code execution...")
+
+	# Dump a JSON file with a specified indentation depth
+	data: dict[str, Any] = {"name": "John", "array": [[[1, 2, 3], [4, 5, 6]], [[7, 8, 9], [10, 11, 12]]]}
+	stp.info("\n", stp.super_json_dump(data, max_level=2))
+
+	# Remove the folder
+	import shutil
+	shutil.rmtree("this_folder_dont_exist")
+

stouputils-1.0.23/examples/parallel.py

@@ -0,0 +1,28 @@
+
+# Imports
+import stouputils as stp
+import time
+
+# Functions
+def is_even(n: int) -> bool:
+	return n % 2 == 0
+
+def multiple_args(a: int, b: int) -> int:
+	return a * b
+
+# Main
+if __name__ == "__main__":
+	
+	# Multi-threading (blazingly fast for IO-bound tasks)
+	args_1: list[int] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+	results_1: list[bool] = stp.multithreading(is_even, args_1)
+	stp.info(f"Results: {results_1}")
+
+	# Multi-processing (better for CPU-bound tasks)
+	time.sleep(1)
+	args_2: list[tuple[int, int]] = [(1, 2), (3, 4), (5, 6), (7, 8), (9, 10)]
+	results_2: list[int] = stp.multiprocessing(
+		multiple_args, args_2, use_starmap=True, desc="Multiple args", max_workers=2, verbose=1
+	)
+	stp.info(f"Results: {results_2}")
+

stouputils-1.0.23/examples/print.py

@@ -0,0 +1,27 @@
+
+# Imports
+import time
+import stouputils as stp
+
+# Main
+if __name__ == "__main__":
+	stp.info("Hello", "World")
+	time.sleep(0.5)
+	stp.info("Hello", "World")
+	time.sleep(0.5)
+	stp.info("Hello", "World")
+	time.sleep(0.5)
+	stp.info("Not Hello World !")
+	time.sleep(0.5)
+	stp.info("Hello", "World")
+	time.sleep(0.5)
+	stp.info("Hello", "World")
+
+	# All remaining print functions
+	stp.debug("Hello", "World")
+	stp.suggestion("Hello", "World")
+	stp.progress("Hello", "World")
+	stp.warning("Hello", "World")
+	stp.error("Hello", "World", exit=False)
+	stp.whatisit("Hello", "World")
+

{stouputils-1.0.21 → stouputils-1.0.23}/pyproject.toml

@@ -1,27 +1,18 @@
-
 [build-system]
-requires = ["hatchling"]
+requires = [ "hatchling",]
 build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.0.21"
-authors = [
-	{ name="Stoupy51", email="stoupy51@gmail.com" },
-]
+version = "1.0.23"
 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"
-classifiers = [
-	"Programming Language :: Python :: 3",
-	"License :: OSI Approved :: MIT License",
-	"Operating System :: OS Independent",
-]
-dependencies = [
-	"tqdm>=4.66.4",
-	"requests>=2.31.0",
-	"pyyaml>=6.0.2",
-]
+classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent",]
+dependencies = [ "tqdm>=4.66.4", "requests>=2.31.0", "pyyaml", "toml",]
+[[project.authors]]
+name = "Stoupy51"
+email = "stoupy51@gmail.com"
 
 [project.urls]
 Homepage = "https://github.com/Stoupy51/stouputils"
@@ -29,4 +20,3 @@ Issues = "https://github.com/Stoupy51/stouputils/issues"
 
 [tool.pyright]
 typeCheckingMode = "strict"
-

{stouputils-1.0.21 → stouputils-1.0.23}/scripts/create_docs.py

@@ -4,7 +4,8 @@ import os
 import shutil
 import subprocess
 import sys
-from stouputils import clean_path, handle_error
+from stouputils import clean_path, handle_error, warning, simple_cache
+from stouputils.continuous_delivery.github import version_to_float
 clean_exec: str = clean_path(sys.executable)
 
 conf_content: str = """
@@ -26,21 +27,45 @@ release: str = current_version
 extensions: list[str] = [
 	'sphinx.ext.autodoc',
 	'sphinx.ext.napoleon',
-	'sphinx.ext.viewcode',
+	'sphinx.ext.viewcode', 
 	'sphinx.ext.githubpages',
 	'sphinx.ext.intersphinx',
+	'furo.sphinxext',
 ]
 
 templates_path: list[str] = ['_templates']
 exclude_patterns: list[str] = []
 
 # HTML output options
-html_theme: str = 'sphinx_rtd_theme'
+html_theme: str = 'furo'
 html_static_path: list[str] = ['_static']
+html_logo: str = 'https://avatars.githubusercontent.com/u/35665974'
+html_title: str = 'stouputils'
+html_favicon: str = 'https://avatars.githubusercontent.com/u/35665974'
 
 # Theme options
 html_theme_options: dict[str, Any] = {
-	'style_external_links': True,
+	'light_css_variables': {
+		'color-brand-primary': '#2980B9',
+		'color-brand-content': '#2980B9',
+		'color-admonition-background': '#E8F0F8',
+	},
+	'dark_css_variables': {
+		'color-brand-primary': '#56B4E9',
+		'color-brand-content': '#56B4E9',
+		'color-admonition-background': '#1F262B',
+	},
+	'sidebar_hide_name': False,
+	'navigation_with_keys': True,
+	'announcement': 'This is the latest documentation of stouputils',
+	'footer_icons': [
+		{
+			'name': 'GitHub',
+			'url': 'https://github.com/Stoupy51/stouputils',
+			'html': '<i class="fab fa-github-square"></i>',
+			'class': '',
+		},
+	],
 }
 
 # Add any paths that contain custom static files
@@ -71,6 +96,7 @@ html_context = {
 	'github_version': 'main',
 	'conf_py_path': '/docs/source/',
 	'source_suffix': '.rst',
+	'default_mode': 'dark',
 }
 
 # Only document items with docstrings
@@ -83,6 +109,30 @@ def setup(app: Any) -> None:
 	app.connect('autodoc-skip-member', skip_undocumented)
 """
 
+@simple_cache()
+def get_versions_from_github() -> list[str]:
+	""" Get list of versions from GitHub gh-pages branch.
+
+	Returns:
+		list[str]: List of versions, with 'latest' as first element
+	"""
+	import requests
+	version_list: list[str] = []
+	try:
+		response = requests.get("https://api.github.com/repos/Stoupy51/stouputils/contents?ref=gh-pages")
+		if response.status_code == 200:
+			contents = response.json()
+			version_list = ["latest"] + sorted(
+				[d["name"].replace("v", "") for d in contents 
+				if d["type"] == "dir" and d["name"].startswith("v")],
+				key=version_to_float,
+				reverse=True
+			)
+	except Exception as e:
+		warning(f"Failed to get versions from GitHub: {e}")
+		version_list = ["latest"]
+	return version_list
+
 def generate_index_rst(readme_path: str, index_path: str) -> None:
 	""" Generate index.rst from README.md content.
 	
@@ -107,14 +157,8 @@ def generate_index_rst(readme_path: str, index_path: str) -> None:
 
 **Versions**: """
 	
-	# Add versions from html_context
-	version_list: list[str] = []
-	html_dir = "docs/build/html"
-	if os.path.exists(html_dir):
-		version_list = [d[1:] for d in os.listdir(html_dir) if d.startswith('v')]
-	from stouputils.continuous_delivery.github import version_to_float
-	version_list.sort(key=version_to_float, reverse=True)
-	version_list.insert(0, 'latest')
+	# Get versions from GitHub
+	version_list: list[str] = get_versions_from_github()
 	
 	# Create version links
 	version_links: list[str] = []
@@ -218,10 +262,7 @@ def update_documentation(version: str | None = None) -> None:
 		os.makedirs(modules_dir)
 
 	# Update conf.py to include version selector
-	version_list: list[str] = []
-	if os.path.exists(clean_path(f"{docs_dir}/build/html")):
-		version_list = [d.replace("v", "") for d in os.listdir(clean_path(f"{docs_dir}/build/html")) 
-					   if d.startswith("v")] + ["latest"]
+	version_list: list[str] = get_versions_from_github()
 	
 	# Update html_context in conf.py
 	global conf_content

{stouputils-1.0.21 → stouputils-1.0.23}/src/stouputils/all_doctests.py

@@ -1,12 +1,16 @@
 """
 This module is used to run all the doctests for all the modules in a given directory.
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/all_doctests_module.gif
+  :alt: stouputils all_doctests examples
 """
 
 # Imports
 import os
 import sys
-from .print import *
-from .decorators import measure_time, handle_error, LogLevels, force_raise_exception
+from .print import info, error, progress
+from .decorators import measure_time, handle_error, LogLevels
+from . import decorators
 from doctest import TestResults, testmod
 from types import ModuleType
 import importlib
@@ -46,10 +50,9 @@ def launch_tests(root_dir: str, importing_errors: LogLevels = LogLevels.WARNING_
 		[PROGRESS HH:MM:SS] Testing module 'module3'	took 0.007s
 		[PROGRESS HH:MM:SS] Testing module 'module4'	took 0.008s
 	"""
-	global force_raise_exception
 	if strict:
 		old_value: bool = strict
-		force_raise_exception = True
+		decorators.force_raise_exception = True
 		strict = old_value
 
 
@@ -91,5 +94,5 @@ def launch_tests(root_dir: str, importing_errors: LogLevels = LogLevels.WARNING_
 			error(f"Errors in module {module.__name__}", exit=False)
 
 	# Reset force_raise_exception back
-	force_raise_exception = strict
+	decorators.force_raise_exception = strict
 

{stouputils-1.0.21 → stouputils-1.0.23}/src/stouputils/archive.py

@@ -1,14 +1,19 @@
 """
 This module provides functions for creating and managing archives.
 
-- make_archive: Make an archive with consistency using FILES_TO_WRITE variable
-- repair_zip_file: Try to repair a corrupted zip file (NOT IMPLEMENTED)
+- make_archive: Create a zip archive from a source directory with consistent file timestamps.
+- repair_zip_file: Try to repair a corrupted zip file by ignoring some of the errors
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/archive_module.gif
+  :alt: stouputils archive examples
 """
 
 # Imports
-from .io import *
-from .print import *
+import os
 from zipfile import ZipFile, ZipInfo, ZIP_DEFLATED
+from .io import clean_path, super_copy
+from .decorators import handle_error, LogLevels
+from .dont_look.zip_file_override import ZipFileOverride
 
 # Function that makes an archive with consistency (same zip file each time)
 @handle_error()
@@ -18,7 +23,12 @@ def make_archive(
 	override_time: None | tuple[int, int, int, int, int, int] = None,
 	create_dir: bool = False
 ) -> bool:
-	""" Make an archive with consistency using FILES_TO_WRITE variable
+	""" Create a zip archive from a source directory with consistent file timestamps.
+	(Meaning deterministic zip file each time)
+
+	Creates a zip archive from the source directory and copies it to one or more destinations.
+	The archive will have consistent file timestamps across runs if override_time is specified.
+	Uses maximum compression level (9) with ZIP_DEFLATED algorithm.
 
 	Args:
 		source				(str):						The source folder to archive
@@ -33,6 +43,7 @@ def make_archive(
 
 		> make_archive("/path/to/source", "/path/to/destination.zip")
 		> make_archive("/path/to/source", ["/path/to/destination.zip", "/path/to/destination2.zip"])
+		> make_archive("src", "hello_from_year_2085.zip", override_time=(2085,1,1,0,0,0))
 	"""
 	# Fix copy_destinations type if needed
 	if destinations and isinstance(destinations, str):
@@ -66,7 +77,6 @@ def make_archive(
 
 
 # Function that repair a corrupted zip file (ignoring some of the errors)
-from .dont_look.zip_file_override import ZipFileOverride
 @handle_error()
 def repair_zip_file(file_path: str, destination: str) -> bool:
 	""" Try to repair a corrupted zip file by ignoring some of the errors

{stouputils-1.0.21 → stouputils-1.0.23}/src/stouputils/backup.py

@@ -5,6 +5,9 @@ This module provides utilities for backup management.
 - create_delta_backup: Creates a ZIP delta backup, saving only modified or new files while tracking deleted files
 - consolidate_backups: Consolidates the files from the given backup and all previous ones into a new ZIP file
 - backup_cli: Main entry point for command line usage
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/backup_module.gif
+  :alt: stouputils backup examples
 """
 
 # Standard library imports

{stouputils-1.0.21 → stouputils-1.0.23}/src/stouputils/collections.py

@@ -2,6 +2,9 @@
 This module provides utilities for collection manipulation:
 
 - unique_list: Remove duplicates from a list while preserving order using object id, hash or str
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/collections_module.gif
+  :alt: stouputils collections examples
 """
 
 # Imports

{stouputils-1.0.21 → stouputils-1.0.23}/src/stouputils/continuous_delivery/__init__.py

@@ -2,4 +2,6 @@
 # Imports
 from .cd_utils import *
 from .github import *
+from .pypi import *
+from .pyproject import *
 

{stouputils-1.0.21 → stouputils-1.0.23}/src/stouputils/continuous_delivery/cd_utils.py

@@ -3,7 +3,7 @@ It is mainly used by the `stouputils.continuous_delivery.github` module.
 """
 
 # Imports
-from ..print import *
+from ..print import warning
 from ..decorators import handle_error
 from ..io import clean_path, super_json_load
 import requests

{stouputils-1.0.21 → stouputils-1.0.23}/src/stouputils/continuous_delivery/github.py

@@ -1,12 +1,19 @@
 """ This module contains utilities for continuous delivery on GitHub.
 
 - upload_to_github: Upload the project to GitHub using the credentials and the configuration (make a release and upload the assets, handle existing tag, generate changelog, etc.)
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/continuous_delivery/github_module.gif
+  :alt: stouputils upload_to_github examples
 """
 
 # Imports
-from ..print import *
-from ..decorators import measure_time
-from .cd_utils import *
+from ..print import info, warning, progress
+from ..decorators import measure_time, handle_error
+from ..io import clean_path
+from .cd_utils import handle_response
+from typing import Any
+import requests
+import os
 
 # Constants
 GITHUB_API_URL: str = "https://api.github.com"
@@ -131,7 +138,7 @@ def delete_existing_tag(tag_url: str, headers: dict[str, str]) -> None:
 	"""
 	delete_response: requests.Response = requests.delete(tag_url, headers=headers)
 	handle_response(delete_response, "Failed to delete existing tag")
-	info(f"Deleted existing tag")
+	info("Deleted existing tag")
 
 def clean_version(version: str, keep: str = "") -> str:
 	""" Clean a version string