stouputils 1.0.20__tar.gz → 1.0.22__tar.gz

{stouputils-1.0.20 → stouputils-1.0.22}/.github/workflows/documentation.yml

@@ -1,29 +1,42 @@
-name: documentation
-
-on: [push, pull_request, workflow_dispatch]
-
-permissions:
-  contents: write
-
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-      - name: Install dependencies
-        run: |
-          pip install hatch stouputils sphinx sphinx_rtd_theme myst_parser
-          hatch build
-      - name: Sphinx build
-        run: |
-          python scripts/create_docs.py
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-        with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/html
-          force_orphan: true
-
+name: documentation
+
+on: 
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install dependencies
+        run: |
+          pip install hatch stouputils sphinx sphinx_rtd_theme myst_parser furo
+          hatch build
+      - name: Build latest docs
+        if: github.ref == 'refs/heads/main'
+        run: |
+          python scripts/create_docs.py
+      - name: Build version docs
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          python scripts/create_docs.py ${GITHUB_REF#refs/tags/v}
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') || startsWith(github.ref, 'refs/tags/v') }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html
+          keep_files: true
+          force_orphan: false
+

{stouputils-1.0.20 → stouputils-1.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.0.20
+Version: 1.0.22
 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
@@ -19,6 +19,7 @@ Description-Content-Type: text/markdown
 # 🛠️ Project Badges
 [![GitHub](https://img.shields.io/github/v/release/Stoupy51/stouputils?logo=github&label=GitHub)](https://github.com/Stoupy51/stouputils/releases/latest)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/stouputils?logo=python&label=PyPI%20downloads)](https://pypi.org/project/stouputils/)
+[![Documentation](https://img.shields.io/badge/documentation-purple?logo=sphinx)](https://stoupy51.github.io/stouputils/latest/)
 
 
 # 📚 Project Overview

{stouputils-1.0.20 → stouputils-1.0.22}/README.md

@@ -2,6 +2,7 @@
 # 🛠️ Project Badges
 [![GitHub](https://img.shields.io/github/v/release/Stoupy51/stouputils?logo=github&label=GitHub)](https://github.com/Stoupy51/stouputils/releases/latest)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/stouputils?logo=python&label=PyPI%20downloads)](https://pypi.org/project/stouputils/)
+[![Documentation](https://img.shields.io/badge/documentation-purple?logo=sphinx)](https://stoupy51.github.io/stouputils/latest/)
 
 
 # 📚 Project Overview

stouputils-1.0.22/examples/all_doctests.py

@@ -0,0 +1,17 @@
+
+# Imports
+import os
+import stouputils as stp
+
+# Constants
+ROOT: str = os.path.dirname(os.path.abspath(__file__))
+FOLDER_TO_TEST: str = f"{ROOT}/../src"
+
+# Main
+@stp.measure_time(stp.info, message="All doctests finished")
+def main() -> None:
+	stp.launch_tests(FOLDER_TO_TEST)
+
+if __name__ == "__main__":
+	main()
+

stouputils-1.0.22/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.22/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.22/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.22/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.22/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.22/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.22/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.22/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.22/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.20 → stouputils-1.0.22}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.0.20"
+version = "1.0.22"
 authors = [
 	{ name="Stoupy51", email="stoupy51@gmail.com" },
 ]