stouputils 1.0.20__tar.gz → 1.0.21__tar.gz

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

@@ -1,29 +1,41 @@
-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
+          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
+          force_orphan: false
+

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.0.20
+Version: 1.0.21
 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.21}/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.20 → stouputils-1.0.21}/pyproject.toml

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

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

@@ -7,6 +7,82 @@ import sys
 from stouputils import clean_path, handle_error
 clean_exec: str = clean_path(sys.executable)
 
+conf_content: str = """
+# Imports
+import os
+import sys
+from typing import Any
+sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../../src'))
+from upgrade import current_version		# Get version from pyproject.toml
+
+# Project information
+project: str = 'stouputils'
+copyright: str = '2024, Stoupy'
+author: str = 'Stoupy'
+release: str = current_version
+
+# General configuration
+extensions: list[str] = [
+	'sphinx.ext.autodoc',
+	'sphinx.ext.napoleon',
+	'sphinx.ext.viewcode',
+	'sphinx.ext.githubpages',
+	'sphinx.ext.intersphinx',
+]
+
+templates_path: list[str] = ['_templates']
+exclude_patterns: list[str] = []
+
+# HTML output options
+html_theme: str = 'sphinx_rtd_theme'
+html_static_path: list[str] = ['_static']
+
+# Theme options
+html_theme_options: dict[str, Any] = {
+	'style_external_links': True,
+}
+
+# Add any paths that contain custom static files
+html_static_path: list[str] = ['_static']
+
+# Autodoc settings
+autodoc_default_options: dict[str, bool | str] = {
+	'members': True,
+	'member-order': 'bysource',
+	'special-members': False,
+	'undoc-members': False,
+	'private-members': False,
+	'show-inheritance': True,
+	'ignore-module-all': True,
+	'exclude-members': '__weakref__'
+}
+
+# Tell autodoc to prefer source code over installed package
+autodoc_mock_imports = []
+always_document_param_types = True
+add_module_names = False
+
+# Tell Sphinx to look for source code in src directory
+html_context = {
+	'display_github': True,
+	'github_user': 'Stoupy51',
+	'github_repo': 'stouputils',
+	'github_version': 'main',
+	'conf_py_path': '/docs/source/',
+	'source_suffix': '.rst',
+}
+
+# Only document items with docstrings
+def skip_undocumented(app: Any, what: str, name: str, obj: Any, skip: bool, *args: Any, **kwargs: Any) -> bool:
+	if not obj.__doc__:
+		return True
+	return skip
+
+def setup(app: Any) -> None:
+	app.connect('autodoc-skip-member', skip_undocumented)
+"""
+
 def generate_index_rst(readme_path: str, index_path: str) -> None:
 	""" Generate index.rst from README.md content.
 	
@@ -26,6 +102,30 @@ def generate_index_rst(readme_path: str, index_path: str) -> None:
   :target: https://pypi.org/project/stouputils/
 """
 	
+	# Generate version selector
+	version_selector: str = """
+
+**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')
+	
+	# Create version links
+	version_links: list[str] = []
+	for version in version_list:
+		if version == 'latest':
+			version_links.append("`latest <../latest/index.html>`_")
+		else:
+			version_links.append(f"`v{version} <../v{version}/index.html>`_")
+	
+	version_selector += ", ".join(version_links)
+	
 	# Extract sections while preserving emojis
 	overview_section: str = readme_content.split('# 📚 Project Overview')[1].split('\n#')[0].strip()
 	file_tree_section: str = readme_content.split('# 🚀 Project File Tree')[1].split('\n#')[0].strip()
@@ -45,6 +145,8 @@ def generate_index_rst(readme_path: str, index_path: str) -> None:
 
 {badges_rst}
 
+{version_selector}
+
 📚 Overview
 -----------
 {overview_section.replace("<br>", " ")}
@@ -71,13 +173,25 @@ def generate_index_rst(readme_path: str, index_path: str) -> None:
 	with open(index_path, 'w', encoding="utf-8") as f:
 		f.write(rst_content)
 
+def generate_conf_py(conf_path: str) -> None:
+	""" Generate conf.py file.
+	
+	Args:
+		conf_path (str): Path where conf.py should be created
+	"""
+	with open(conf_path, 'w', encoding="utf-8") as f:
+		f.write(conf_content)
+
 @handle_error()
-def update_documentation() -> None:
+def update_documentation(version: str | None = None) -> None:
 	""" Update the Sphinx documentation.
 	This script will:
 	1. Create necessary directories if they don't exist
 	2. Generate module documentation using sphinx-apidoc
-	3. Build HTML documentation
+	3. Build HTML documentation for specific version if provided
+
+	Args:
+		version (str | None): Version to build documentation for. If None, builds for latest
 	"""
 	# Get the project root directory (parent of scripts folder)
 	root_dir: str = clean_path(os.path.dirname(os.path.dirname(__file__)))
@@ -85,6 +199,9 @@ def update_documentation() -> None:
 	source_dir: str = clean_path(os.path.join(docs_dir, "source"))
 	modules_dir: str = clean_path(os.path.join(source_dir, "modules"))
 
+	# Modify build directory if version is specified
+	build_dir: str = "html/latest" if not version else f"html/v{version}"
+	
 	# Create directories if they don't exist
 	os.makedirs(modules_dir, exist_ok=True)
 	os.makedirs(clean_path(os.path.join(source_dir, "_static")), exist_ok=True)
@@ -100,6 +217,25 @@ def update_documentation() -> None:
 		shutil.rmtree(modules_dir)
 		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"]
+	
+	# Update html_context in conf.py
+	global conf_content
+	conf_content = conf_content.replace(
+		"html_context = {",
+		f"""html_context = {{
+	'versions': {version_list},
+	'current_version': 'latest' if not {repr(version)} else {repr(version)},"""
+	)
+
+	# Generate docs/source/conf.py
+	conf_path: str = clean_path(os.path.join(source_dir, "conf.py"))
+	generate_conf_py(conf_path)
+
 	# Generate module documentation using python -m
 	subprocess.run([
 		clean_exec,
@@ -122,12 +258,17 @@ def update_documentation() -> None:
 		"-b", "html",           # Build HTML
 		"-a",                   # Write all files
 		source_dir,             # Source directory
-		clean_path(os.path.join(docs_dir, "build", "html")),  # Output directory
+		clean_path(f"{docs_dir}/build/{build_dir}"),  # Output directory
 	], check=True)
 
 	print("Documentation updated successfully!")
-	print(f"You can view the documentation by opening {docs_dir}/build/html/index.html")
+	print(f"You can view the documentation by opening {docs_dir}/build/{build_dir}/index.html")
 
 if __name__ == "__main__":
-	update_documentation()
+	if len(sys.argv) == 2:
+		update_documentation(sys.argv[1].replace("v", ""))	# Remove "v" from version just in case
+	elif len(sys.argv) == 1:
+		update_documentation()
+	else:
+		raise ValueError("Usage: python create_docs.py [version]")
 

{stouputils-1.0.20 → stouputils-1.0.21}/src/stouputils/ctx.py

@@ -93,7 +93,8 @@ class LogToFile:
 		# Build log file path
 		file_basename: str = os.path.splitext(os.path.basename(filepath))[0]
 		date_time: str = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
-		log_filepath: str = f"{logs_folder}/{file_basename}/{date_time}.log"
+		date_str, time_str = date_time.split("_")
+		log_filepath: str = f"{logs_folder}/{file_basename}/{date_str}/{time_str}.log"
 
 		# Launch function with arguments if any
 		with LogToFile(log_filepath):

{stouputils-1.0.20 → stouputils-1.0.21}/src/stouputils/parallel.py

@@ -81,7 +81,7 @@ def __handle_parameters(
 	return desc, func, args
 
 @handle_error(error_log=LogLevels.ERROR_TRACEBACK)
-def multiprocessing(func: Callable[[T], R], args: list[T], use_starmap: bool = False, chunksize: int = 1, desc: str = "", max_workers: int = CPU_COUNT, delay_first_calls: float = 0, verbose_depth: int = 0) -> list[R]:
+def multiprocessing(func: Callable[[T], R], args: list[T], use_starmap: bool = False, chunksize: int = 1, desc: str = "", max_workers: int = CPU_COUNT, delay_first_calls: float = 0, verbose: int = 0) -> list[R]:
 	r""" Method to execute a function in parallel using multiprocessing, you should use it:
 
 	- For CPU-bound operations where the GIL (Global Interpreter Lock) is a bottleneck.
@@ -96,7 +96,7 @@ def multiprocessing(func: Callable[[T], R], args: list[T], use_starmap: bool = F
 		desc				(str):				Description of the function execution displayed in the progress bar
 		max_workers			(int):				Number of workers to use (Defaults to CPU_COUNT)
 		delay_first_calls	(float):			Apply i*delay_first_calls seconds delay to the first "max_workers" calls. For instance, the first process will be delayed by 0 seconds, the second by 1 second, etc. (Defaults to 0): This can be useful to avoid functions being called in the same second.
-		verbose_depth		(int):				Level of verbosity, decrease by 1 for each depth
+		verbose				(int):				Level of verbosity, decrease by 1 for each depth
 	Returns:
 		list[object]:	Results of the function execution
 	Examples:
@@ -107,11 +107,11 @@ def multiprocessing(func: Callable[[T], R], args: list[T], use_starmap: bool = F
 		[2, 12, 30]
 
 		>>> # Will process in parallel with progress bar
-		>>> multiprocessing(doctest_slow, list(range(10)), desc="Processing", verbose_depth=1)
+		>>> multiprocessing(doctest_slow, list(range(10)), desc="Processing", verbose=1)
 		[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
 		>>> # Will process in parallel with progress bar and delay the first threads
-		>>> multiprocessing(doctest_slow, list(range(10)), desc="Processing with delay", max_workers=2, delay_first_calls=1.2, verbose_depth=1)
+		>>> multiprocessing(doctest_slow, list(range(10)), desc="Processing with delay", max_workers=2, delay_first_calls=1.2, verbose=1)
 		[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 	"""
 	# Handle parameters
@@ -119,7 +119,7 @@ def multiprocessing(func: Callable[[T], R], args: list[T], use_starmap: bool = F
 
 	# Do multiprocessing only if there is more than 1 argument and more than 1 CPU
 	if max_workers > 1 and len(args) > 1:
-		if verbose_depth > 0:
+		if verbose > 0:
 			return list(process_map(func, args, max_workers=max_workers, chunksize=chunksize, desc=desc, bar_format=BAR_FORMAT)) # type: ignore
 		else:
 			with Pool(max_workers) as pool:
@@ -127,14 +127,14 @@ def multiprocessing(func: Callable[[T], R], args: list[T], use_starmap: bool = F
 
 	# Single process execution
 	else:
-		if verbose_depth > 0:
+		if verbose > 0:
 			return [func(arg) for arg in tqdm(args, total=len(args), desc=desc, bar_format=BAR_FORMAT)]
 		else:
 			return [func(arg) for arg in args]
 
 
 @handle_error(error_log=LogLevels.ERROR_TRACEBACK)
-def multithreading(func: Callable[[T], R], args: list[T], use_starmap: bool = False, desc: str = "", max_workers: int = CPU_COUNT, delay_first_calls: float = 0, verbose_depth: int = 0) -> list[R]:
+def multithreading(func: Callable[[T], R], args: list[T], use_starmap: bool = False, desc: str = "", max_workers: int = CPU_COUNT, delay_first_calls: float = 0, verbose: int = 0) -> list[R]:
 	r""" Method to execute a function in parallel using multithreading, you should use it:
 
 	- For I/O-bound operations where the GIL is not a bottleneck, such as network requests or disk operations.
@@ -148,7 +148,7 @@ def multithreading(func: Callable[[T], R], args: list[T], use_starmap: bool = Fa
 		desc				(str):				Description of the function execution displayed in the progress bar
 		max_workers			(int):				Number of workers to use (Defaults to CPU_COUNT)
 		delay_first_calls	(float):			Apply i*delay_first_calls seconds delay to the first "max_workers" calls. For instance with value to 1, the first thread will be delayed by 0 seconds, the second by 1 second, etc. (Defaults to 0): This can be useful to avoid functions being called in the same second.
-		verbose_depth		(int):				Level of verbosity, decrease by 1 for each depth
+		verbose				(int):				Level of verbosity, decrease by 1 for each depth
 	Returns:
 		list[object]:	Results of the function execution
 	Examples:
@@ -159,11 +159,11 @@ def multithreading(func: Callable[[T], R], args: list[T], use_starmap: bool = Fa
 		[2, 12, 30]
 
 		>>> # Will process in parallel with progress bar
-		>>> multithreading(doctest_slow, list(range(10)), desc="Threading", verbose_depth=1)
+		>>> multithreading(doctest_slow, list(range(10)), desc="Threading", verbose=1)
 		[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
 		>>> # Will process in parallel with progress bar and delay the first threads
-		>>> multithreading(doctest_slow, list(range(10)), desc="Threading with delay", max_workers=2, delay_first_calls=1.2, verbose_depth=1)
+		>>> multithreading(doctest_slow, list(range(10)), desc="Threading with delay", max_workers=2, delay_first_calls=1.2, verbose=1)
 		[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 	"""
 	# Handle parameters
@@ -171,7 +171,7 @@ def multithreading(func: Callable[[T], R], args: list[T], use_starmap: bool = Fa
 
 	# Do multithreading only if there is more than 1 argument and more than 1 CPU
 	if max_workers > 1 and len(args) > 1:
-		if verbose_depth > 0:
+		if verbose > 0:
 			with ThreadPoolExecutor(max_workers) as executor:
 				return list(tqdm(executor.map(func, args), total=len(args), desc=desc, bar_format=BAR_FORMAT))
 		else:
@@ -180,7 +180,7 @@ def multithreading(func: Callable[[T], R], args: list[T], use_starmap: bool = Fa
 
 	# Single process execution
 	else:
-		if verbose_depth > 0:
+		if verbose > 0:
 			return [func(arg) for arg in tqdm(args, total=len(args), desc=desc, bar_format=BAR_FORMAT)]
 		else:
 			return [func(arg) for arg in args]

{stouputils-1.0.20 → stouputils-1.0.21}/src/stouputils/print.py

@@ -1,5 +1,8 @@
 """
-This module provides utility functions for printing messages with different levels of importance, such as:
+This module provides utility functions for printing messages with different levels of importance,
+If a message is printed multiple times, it will be displayed as "(xN) message" where N is the number of times the message has been printed.
+
+The functions are such as:
 
 - info()
 - debug()
@@ -7,12 +10,14 @@ This module provides utility functions for printing messages with different leve
 - progress()
 - warning()
 - error()
-
-It also includes:
-
 - whatisit(): a function to print the type of each value and the value itself (and few other things)
 - breakpoint(): a breakpoint function to pause the program while calling whatisit()
 - logging_to: a set of file-like objects that will receive log messages without ANSI color codes, see stouputils.ctx.LogToFile for easy logging
+
+Here is a demonstration gif showing examples of uses:
+
+.. image:: https://i.imgur.com/EIeiLwa.gif
+  :alt: stouputils print examples
 """
 
 # Imports
@@ -54,8 +59,13 @@ def is_same_print(*args: Any, **kwargs: Any) -> bool:
 		nb_values = 1
 		return False
 
+import_time: float = time.time()
 def current_time() -> str:
-	return time.strftime("%H:%M:%S")
+	# If the import time is more than 24 hours, return the full datetime
+	if (time.time() - import_time) > (24 * 60 * 60):
+		return time.strftime("%Y-%m-%d %H:%M:%S")
+	else:
+		return time.strftime("%H:%M:%S")
 
 def info(*values: Any, color: str = GREEN, text: str = "INFO ", prefix: str = "", file: TextIO|list[TextIO] = sys.stdout, **print_kwargs: Any) -> None:
 	""" Print an information message looking like "[INFO HH:MM:SS] message" in green by default.
@@ -211,15 +221,15 @@ def breakpoint(*values: Any, print_function: Callable[..., None] = warning, **pr
 
 if __name__ == "__main__":
 	info("Hello", "World")
-	time.sleep(1)
-	info("Hello", "World")
-	time.sleep(1)
+	time.sleep(0.5)
 	info("Hello", "World")
-	time.sleep(1)
+	time.sleep(0.5)
 	info("Hello", "World")
-	time.sleep(1)
+	time.sleep(0.5)
+	info("Not Hello World !")
+	time.sleep(0.5)
 	info("Hello", "World")
-	time.sleep(1)
+	time.sleep(0.5)
 	info("Hello", "World")
 
 	# All remaining print functions