stouputils 1.12.1__py3-none-any.whl

stouputils/applications/upscaler/video.py

@@ -0,0 +1,287 @@
+"""
+This module provides utility functions for upscaling videos using waifu2x-ncnn-vulkan.
+
+It extracts frames from videos, upscales them individually, and then recombines them
+into a high-quality output video. The process preserves audio from the original video
+and handles configuration of video encoding parameters like bitrate and framerate.
+
+Main functionalities:
+
+- Extracting frames from videos using FFmpeg
+- Upscaling frames using waifu2x-ncnn-vulkan
+- Recombining frames into videos with optimized bitrates
+- Handling partially processed videos to resume interrupted operations
+- Calculating recommended bitrates based on resolution and framerate
+
+The module includes YouTube's recommended bitrate settings for different resolutions,
+framerates, and HDR/SDR content types, ensuring optimal quality for various outputs.
+
+Example usage:
+
+.. code-block:: python
+
+	# Imports
+	import stouputils.applications.upscaler as app
+	from stouputils.io import get_root_path
+
+	# Constants
+	ROOT: str = get_root_path(__file__) + "/upscaler"
+	INPUT_FOLDER: str = f"{ROOT}/input"
+	PROGRESS_FOLDER: str = f"{ROOT}/progress"
+	OUTPUT_FOLDER: str = f"{ROOT}/output"
+
+	# Main
+	if __name__ == "__main__":
+		app.video_upscaler_cli(INPUT_FOLDER, PROGRESS_FOLDER, OUTPUT_FOLDER)
+"""
+
+# Imports
+import os
+import shutil
+import subprocess
+import sys
+from typing import Literal
+
+from PIL import Image
+
+from ...installer import check_executable
+from ...io import clean_path
+from ...parallel import multithreading
+from ...print import colored_for_loop, debug, error, info, warning
+from .config import FFMPEG_RELEASES, YOUTUBE_BITRATE_RECOMMENDATIONS, Config
+from .image import convert_frame, get_all_files, upscale_folder
+
+
+# Functions
+def get_recommended_bitrate(
+	resolution: tuple[int, int], frame_rate: int = 60, upload_type: Literal["SDR","HDR"] = "SDR"
+) -> int:
+	""" Get the recommended bitrate (in kbps) for the output video based on the video resolution.
+
+	Args:
+		resolution  (tuple[int, int]):       Video resolution (width, height).
+		frame_rate  (int):                   Frame rate of the video, default is 60.
+		upload_type (Literal["SDR","HDR"]):  Upload type from which the recommendation is made, default is "SDR".
+
+	Returns:
+		int:     The recommended bitrate for the output video (in kbps)
+
+	Source: https://support.google.com/youtube/answer/1722171?hl=en#zippy=%2Cbitrate
+
+	Examples:
+		>>> # Valid examples
+		>>> get_recommended_bitrate((3840, 2160), 60, "SDR")
+		68000
+		>>> get_recommended_bitrate((1920, 1080), 60, "HDR")
+		15000
+		>>> get_recommended_bitrate((1920, 1080), 60, "SDR")
+		12000
+		>>> get_recommended_bitrate((1920, 1080), 30, "SDR")
+		8000
+
+		>>> # Invalid examples
+		>>> get_recommended_bitrate((1920, 1080), 60, "Ratio")
+		Traceback (most recent call last):
+			...
+		AssertionError: Invalid upload type: 'Ratio'
+		>>> get_recommended_bitrate("1920x1080", 60, "SDR")
+		Traceback (most recent call last):
+			...
+		AssertionError: Invalid resolution: 1920x1080, must be a tuple of two integers
+		>>> get_recommended_bitrate((1920, 1080), -10, "SDR")
+		Traceback (most recent call last):
+			...
+		AssertionError: Invalid frame rate: -10, must be a positive integer
+	"""
+	# Assertions
+	assert isinstance(resolution, tuple) and len(resolution) == 2, \
+		f"Invalid resolution: {resolution}, must be a tuple of two integers"
+	assert isinstance(frame_rate, int) and frame_rate > 0, \
+		f"Invalid frame rate: {frame_rate}, must be a positive integer"
+	assert upload_type in YOUTUBE_BITRATE_RECOMMENDATIONS, \
+		f"Invalid upload type: '{upload_type}'"
+
+	# Determine frame rate category
+	frame_rate_category: str = "high" if frame_rate >= 48 else "standard"
+
+	# Get the appropriate bitrate dictionary
+	resolution_bitrates: dict[int, int] = YOUTUBE_BITRATE_RECOMMENDATIONS[upload_type][frame_rate_category]
+
+	# Find the appropriate bitrate based on resolution
+	max_dimension: int = min(*resolution)
+	for min_resolution, bitrate in sorted(resolution_bitrates.items(), reverse=True):
+		if max_dimension >= min_resolution:
+			return bitrate
+
+	# Fallback (should never reach here due to the '0' key in dictionaries)
+	return 1000
+
+
+def check_ffmpeg_executable() -> None:
+	if not Config.ffmpeg_executable_checked:
+		check_executable(Config.FFMPEG_EXECUTABLE, Config.FFMPEG_CHECK_HELP_TEXT, FFMPEG_RELEASES, append_to_path="bin")
+		Config.ffmpeg_executable_checked = True
+
+# Routine to handle a video file
+def upscale_video(video_file: str, input_folder: str, progress_folder: str, output_folder: str) -> None:
+	""" Handles a video file. """
+	# Prepare paths
+	input_path: str = f"{input_folder}/{video_file}"
+	progress_path: str = f"{progress_folder}/{video_file}"
+	p_extracted_path: str = f"{progress_path}/extracted"
+	p_upscaled_path: str = f"{progress_path}/upscaled"
+	output_path: str = f"{output_folder}/{video_file}"
+	os.makedirs(p_extracted_path, exist_ok = True)
+	os.makedirs(p_upscaled_path, exist_ok = True)
+
+	# Check if executable is installed
+	check_ffmpeg_executable()
+
+	## Step 1: Check if the video file is already upscaled or partially processed, if not, extract frames
+	# If the video file is already upscaled, skip it
+	if os.path.exists(output_path):
+		warning(f"'{video_file}' has already been processed, remove it from the output folder to reprocess it.")
+		return
+
+	# If the video is already in the list of videos that have been partially processed, ask to restart or skip
+	is_partially_processed: bool = len(os.listdir(p_extracted_path)) > 0 and len(os.listdir(p_upscaled_path)) > 0
+	if is_partially_processed:
+		info(f"'{video_file}' has already been partially processed, do you want to resume the process? (Y/n)")
+		if input().lower() == "n":
+			shutil.rmtree(p_upscaled_path, ignore_errors = True)
+			os.makedirs(p_upscaled_path, exist_ok = True)
+			is_partially_processed = False
+
+	# If the video is not partially processed, extract frames
+	if not is_partially_processed:
+		debug(f"Extracting frames from '{video_file}'...")
+
+		# Extract frames using ffmpeg
+		command: list[str] = [Config.FFMPEG_EXECUTABLE, "-i", input_path, f"{p_extracted_path}/%09d.png"]
+		subprocess.run(command, capture_output = True)
+
+	# Convert all frames to JPG format
+	frames_to_convert: list[str] = get_all_files(p_extracted_path, ".png")
+	if frames_to_convert:
+		multithreading(convert_frame, frames_to_convert, desc="Converting frames to JPG format")
+
+
+	## Step 2: Upscale the frames
+	# Get all the frames in the progress folder
+	all_frames: list[str] = get_all_files(p_extracted_path, ".jpg")
+	upscaled_frames: list[str] = get_all_files(p_upscaled_path, ".jpg")
+
+	# If there are frames to upscale,
+	if len(all_frames) > len(upscaled_frames):
+
+		# Try to get upscaling ratio if any
+		upscale_ratio: int = 2
+		if upscaled_frames:
+			with Image.open(upscaled_frames[0]) as img:
+				upscaled_size: tuple[int, int] = img.size
+			with Image.open(all_frames[0]) as img:
+				extracted_size: tuple[int, int] = img.size
+			upscale_ratio = upscaled_size[0] // extracted_size[0]
+			info(f"Detected upscaling ratio: {upscale_ratio}")
+		else:
+			if "--upscale" in sys.argv:
+				upscale_index: int = sys.argv.index("--upscale")
+				if upscale_index + 1 < len(sys.argv):
+					upscale_ratio = int(sys.argv[upscale_index + 1])
+				else:
+					error(
+						"No upscaling ratio provided with --upscale flag. "
+						"Please provide a ratio after the flag. (1/2/4/8/16/32)",
+						exit=True
+					)
+			else:
+				info("No upscaling ratio provided, please enter one (1/2/4/8/16/32, default=2):")
+				upscale_ratio = int(input() or "2")
+
+		# For each frame that hasn't been upscaled yet, upscale it
+		upscale_folder(p_extracted_path, p_upscaled_path, upscale_ratio, slightly_faster_mode=Config.SLIGHTLY_FASTER_MODE)
+
+	## Step 3: Convert the upscaled frames to a video
+	# Get the video bitrate
+	if Config.VIDEO_FINAL_BITRATE == -1:
+		upscaled_frame: str = get_all_files(p_upscaled_path, ".jpg")[0]
+		with Image.open(upscaled_frame) as img:
+			upscaled_size: tuple[int, int] = img.size
+		video_bitrate: int = get_recommended_bitrate(upscaled_size)
+	else:
+		video_bitrate: int = Config.VIDEO_FINAL_BITRATE
+
+	# Get the framerate of the original video
+	original_framerate: str = "60"
+	ffprobe_command: list[str] = [
+		Config.FFPROBE_EXECUTABLE,                    # Path to the ffprobe executable
+		"-v", "error",                                # Set verbosity level to error (only show errors)
+		"-select_streams", "v:0",                     # Select the first video stream
+		"-show_entries", "stream=r_frame_rate",       # Show only the frame rate information
+		"-of", "default=noprint_wrappers=1:nokey=1",  # Format output without wrappers and keys
+		input_path,                                   # Path to the input video file
+	]
+	try:
+		result = subprocess.run(ffprobe_command, capture_output=True, text=True, check=True)
+		framerate: str = result.stdout.strip()
+		if not framerate or '/' not in framerate: # Basic validation
+			warning(f"Could not reliably determine framerate for '{video_file}'. Falling back to 60.")
+			original_framerate = "60"
+		else:
+			debug(f"Detected original framerate: {framerate}")
+			original_framerate = framerate
+	except (subprocess.CalledProcessError, FileNotFoundError) as e:
+		warning(f"Failed to get framerate using ffprobe for '{video_file}': {e}. Falling back to 60.")
+
+
+	# Prepare the command to convert the upscaled frames to a video
+	subprocess.run([
+		Config.FFMPEG_EXECUTABLE,
+		"-framerate", original_framerate,    # Use the original video's framerate for input frames
+		"-i", f"{p_upscaled_path}/%09d.jpg", # Use p_upscaled_path, not upscaled_path
+		"-i", input_path,                    # Input video for sound and metadata
+		"-b:v", f"{video_bitrate}k",         # Set the video bitrate (in kbps)
+		*Config.FFMPEG_ARGS,			 	 # Additional arguments from the config
+		"-r", original_framerate,            # Set the *output* video framerate
+		output_path,                         # Output video
+	])
+
+
+def video_upscaler_cli(input_folder: str, progress_folder: str, output_folder: str) -> None:
+	""" Upscales videos from an input folder and saves them to an output folder.
+
+	Uses intermediate folders for extracted and upscaled frames within the progress folder.
+	**Handles resuming partially processed videos.**
+
+	Args:
+		input_folder    (str): Path to the folder containing input videos.
+		progress_folder (str): Path to the folder for storing intermediate files (frames).
+		output_folder   (str): Path to the folder where upscaled videos will be saved.
+	"""
+	# Clean paths
+	input_folder = clean_path(input_folder)
+	progress_folder = clean_path(progress_folder)
+	output_folder = clean_path(output_folder)
+	os.makedirs(input_folder, exist_ok = True)
+	os.makedirs(progress_folder, exist_ok = True)
+	os.makedirs(output_folder, exist_ok = True)
+
+	# Ask if we should shutdown the computer after the script is finished
+	info("Do you want to shutdown the computer after the script is finished? (y/N)")
+	shutdown_after_script: bool = input().lower() == "y"
+
+	# Collect all video files in the input folder
+	videos: list[str] = [file for file in os.listdir(input_folder) if not file.endswith(".md")]
+
+	# Handle each video file
+	for video in colored_for_loop(videos, desc="Upscaling videos"):
+		upscale_video(video, input_folder, progress_folder, output_folder)
+
+	# Shutdown the computer after the script is finished
+	if shutdown_after_script:
+		info("Shutting down the computer...")
+		if os.name == "nt":
+			subprocess.run(["shutdown", "/s", "/t", "0", "/f"], capture_output = False)
+		else:
+			subprocess.run(["shutdown", "now"], capture_output = False)
+

stouputils/applications/upscaler/video.pyi

@@ -0,0 +1,60 @@
+from ...installer import check_executable as check_executable
+from ...io import clean_path as clean_path
+from ...parallel import multithreading as multithreading
+from ...print import colored_for_loop as colored_for_loop, debug as debug, error as error, info as info, warning as warning
+from .config import Config as Config, FFMPEG_RELEASES as FFMPEG_RELEASES, YOUTUBE_BITRATE_RECOMMENDATIONS as YOUTUBE_BITRATE_RECOMMENDATIONS
+from .image import convert_frame as convert_frame, get_all_files as get_all_files, upscale_folder as upscale_folder
+from typing import Literal
+
+def get_recommended_bitrate(resolution: tuple[int, int], frame_rate: int = 60, upload_type: Literal['SDR', 'HDR'] = 'SDR') -> int:
+    ''' Get the recommended bitrate (in kbps) for the output video based on the video resolution.
+
+\tArgs:
+\t\tresolution  (tuple[int, int]):       Video resolution (width, height).
+\t\tframe_rate  (int):                   Frame rate of the video, default is 60.
+\t\tupload_type (Literal["SDR","HDR"]):  Upload type from which the recommendation is made, default is "SDR".
+
+\tReturns:
+\t\tint:     The recommended bitrate for the output video (in kbps)
+
+\tSource: https://support.google.com/youtube/answer/1722171?hl=en#zippy=%2Cbitrate
+
+\tExamples:
+\t\t>>> # Valid examples
+\t\t>>> get_recommended_bitrate((3840, 2160), 60, "SDR")
+\t\t68000
+\t\t>>> get_recommended_bitrate((1920, 1080), 60, "HDR")
+\t\t15000
+\t\t>>> get_recommended_bitrate((1920, 1080), 60, "SDR")
+\t\t12000
+\t\t>>> get_recommended_bitrate((1920, 1080), 30, "SDR")
+\t\t8000
+
+\t\t>>> # Invalid examples
+\t\t>>> get_recommended_bitrate((1920, 1080), 60, "Ratio")
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tAssertionError: Invalid upload type: \'Ratio\'
+\t\t>>> get_recommended_bitrate("1920x1080", 60, "SDR")
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tAssertionError: Invalid resolution: 1920x1080, must be a tuple of two integers
+\t\t>>> get_recommended_bitrate((1920, 1080), -10, "SDR")
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tAssertionError: Invalid frame rate: -10, must be a positive integer
+\t'''
+def check_ffmpeg_executable() -> None: ...
+def upscale_video(video_file: str, input_folder: str, progress_folder: str, output_folder: str) -> None:
+    """ Handles a video file. """
+def video_upscaler_cli(input_folder: str, progress_folder: str, output_folder: str) -> None:
+    """ Upscales videos from an input folder and saves them to an output folder.
+
+\tUses intermediate folders for extracted and upscaled frames within the progress folder.
+\t**Handles resuming partially processed videos.**
+
+\tArgs:
+\t\tinput_folder    (str): Path to the folder containing input videos.
+\t\tprogress_folder (str): Path to the folder for storing intermediate files (frames).
+\t\toutput_folder   (str): Path to the folder where upscaled videos will be saved.
+\t"""

stouputils/archive.py

@@ -0,0 +1,344 @@
+"""
+This module provides functions for creating and managing archives.
+
+- repair_zip_file: Try to repair a corrupted zip file by ignoring some of the errors
+- make_archive: Create a zip archive from a source directory with consistent file timestamps.
+- archive_cli: Main entry point for command line usage
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/archive_module.gif
+  :alt: stouputils archive examples
+"""
+
+# pyright: reportUnusedVariable=false
+# Imports
+import fnmatch
+import os
+from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
+
+from .decorators import LogLevels, handle_error
+from .io import clean_path, super_copy
+from .print import CYAN, GREEN, RESET, debug, error, info
+
+
+# Function that repair a corrupted zip file (ignoring some of the errors)
+@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
+
+	This function manually parses the ZIP file structure to extract files
+	even when the ZIP file is corrupted. It reads the central directory
+	entries and attempts to decompress each file individually.
+
+	Args:
+		file_path		(str):	Path of the zip file to repair
+		destination		(str):	Destination of the new file
+	Returns:
+		bool: Always returns True unless any strong error
+
+	Examples:
+
+	.. code-block:: python
+
+		> repair_zip_file("/path/to/source.zip", "/path/to/destination.zip")
+	"""
+	# Check
+	if not os.path.exists(file_path):
+		raise FileNotFoundError(f"File '{file_path}' not found")
+	dirname: str = os.path.dirname(destination)
+	if dirname and not os.path.exists(dirname):
+		raise FileNotFoundError(f"Directory '{dirname}' not found")
+
+	import struct
+	import zlib
+
+	# Read the entire ZIP file into memory
+	with open(file_path, 'rb') as f:
+		data = f.read()
+
+	# Find central directory entries
+	CENTRAL_SIG = b'PK\x01\x02'
+	entries: list[dict[str, int | str]] = []
+	idx = 0
+
+	while True:
+		idx = data.find(CENTRAL_SIG, idx)
+		if idx == -1:
+			break
+		# Ensure enough length for central directory header
+		if idx + 46 > len(data):
+			break
+
+		header = data[idx:idx+46]
+		try:
+			(
+				sig,
+				ver_made, ver_needed, flags, comp_method, mtime, mdate,
+				crc, csize, usize,
+				name_len, extra_len, comm_len,
+				disk_start, int_attr,
+				ext_attr, local_off
+			) = struct.unpack('<4s6H3L3H2H2L', header)
+
+			name_start = idx + 46
+			if name_start + name_len > len(data):
+				idx += 4
+				continue
+
+			name = data[name_start:name_start+name_len].decode('utf-8', errors='replace')
+			entries.append({
+				'name': name,
+				'comp_method': comp_method,
+				'csize': csize,
+				'usize': usize,
+				'local_offset': local_off,
+				'crc': crc
+			})
+		except (struct.error, UnicodeDecodeError):
+			# Skip corrupted entries
+			pass
+
+		idx += 4
+
+	# Create a new ZIP file with recovered entries
+	with ZipFile(destination, "w", compression=ZIP_DEFLATED) as new_zip_file:
+		for entry in entries:
+			try:
+				# Get the local header to find data start
+				lo: int = int(entry['local_offset'])
+				if lo + 30 > len(data):
+					continue
+
+				lh = data[lo:lo+30]
+				try:
+					_, _, _, _, _, _, _, _, _, name_len, extra_len = struct.unpack('<4sHHHHHLLLHH', lh)
+				except struct.error:
+					continue
+
+				data_start: int = lo + 30 + name_len + extra_len
+				if data_start + int(entry['csize']) > len(data):
+					continue
+
+				comp_data = data[data_start:data_start+int(entry['csize'])]
+
+				# Decompress the data
+				try:
+					if int(entry['comp_method']) == 0:  # No compression
+						content = comp_data[:int(entry['usize'])]
+					elif int(entry['comp_method']) == 8:  # Deflate compression
+						content = zlib.decompress(comp_data, -zlib.MAX_WBITS)
+					else:
+						# Unsupported compression method, skip
+						continue
+
+					# Write to new ZIP file
+					new_zip_file.writestr(str(entry['name']), content)
+
+				except (zlib.error, Exception):
+					# If decompression fails, try to write raw data as a fallback
+					try:
+						new_zip_file.writestr(f"{entry['name']!s}.corrupted", comp_data)
+					except Exception:
+						# Skip completely corrupted entries
+						continue
+
+			except Exception:
+				# Skip any entries that cause errors
+				continue
+
+	return True
+
+# Function that makes an archive with consistency (same zip file each time)
+@handle_error()
+def make_archive(
+	source: str,
+	destinations: list[str] | str | None = None,
+	override_time: None | tuple[int, int, int, int, int, int] = None,
+	create_dir: bool = False,
+	ignore_patterns: str | None = None,
+) -> bool:
+	""" 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
+		destinations		(list[str]|str):			The destination folder(s) or file(s) to copy the archive to
+		override_time		(None | tuple[int, ...]):	The constant time to use for the archive
+			(e.g. (2024, 1, 1, 0, 0, 0) for 2024-01-01 00:00:00)
+		create_dir			(bool):						Whether to create the destination directory if it doesn't exist
+		ignore_patterns		(str | None):				Glob pattern(s) to ignore files. Can be a single pattern or comma-separated patterns (e.g. "*.pyc" or "*.pyc,__pycache__,*.log")
+	Returns:
+		bool: Always returns True unless any strong error
+	Examples:
+
+	.. code-block:: python
+
+		> 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))
+		> make_archive("src", "output.zip", ignore_patterns="*.pyc")
+		> make_archive("src", "output.zip", ignore_patterns="__pycache__")
+		> make_archive("src", "output.zip", ignore_patterns="*.pyc,__pycache__,*.log")
+	"""
+	# Fix copy_destinations type if needed
+	if destinations is None:
+		destinations = []
+	if destinations and isinstance(destinations, str):
+		destinations = [destinations]
+	if not destinations:
+		raise ValueError("destinations must be a list of at least one destination")
+
+	# Create directories if needed
+	if create_dir:
+		for dest_file in destinations:
+			dest_file = clean_path(dest_file)
+			parent_dir = os.path.dirname(dest_file)
+			if parent_dir and not os.path.exists(parent_dir):
+				os.makedirs(parent_dir, exist_ok=True)
+
+	# Create the archive
+	destination: str = clean_path(destinations[0])
+	destination = destination if ".zip" in destination else destination + ".zip"
+
+	# Parse ignore patterns (can be a single pattern or comma-separated patterns)
+	ignore_pattern_list: list[str] = []
+	if ignore_patterns:
+		ignore_pattern_list = [pattern.strip() for pattern in ignore_patterns.split(',')]
+
+	def should_ignore(path: str) -> bool:
+		"""Check if a file or directory path should be ignored based on patterns."""
+		if not ignore_pattern_list:
+			return False
+		for pattern in ignore_pattern_list:
+			if fnmatch.fnmatch(os.path.basename(path), pattern) or fnmatch.fnmatch(path, pattern):
+				return True
+		return False
+
+	with ZipFile(destination, "w", compression=ZIP_DEFLATED, compresslevel=9) as zip:
+		for root, dirs, files in os.walk(source):
+			# Filter out ignored directories in-place to prevent walking into them
+			dirs[:] = [d for d in dirs if not should_ignore(d)]
+
+			for file in files:
+				file_path: str = clean_path(os.path.join(root, file))
+				rel_path = os.path.relpath(file_path, source)
+
+				# Skip files that match any ignore pattern
+				if should_ignore(file) or should_ignore(rel_path):
+					continue
+
+				info: ZipInfo = ZipInfo(rel_path)
+				info.compress_type = ZIP_DEFLATED
+				if override_time:
+					info.date_time = override_time
+				with open(file_path, "rb") as f:
+					zip.writestr(info, f.read())
+
+	# Copy the archive to the destination(s)
+	for dest_file in destinations[1:]:
+		@handle_error(Exception, message=f"Unable to copy '{destination}' to '{dest_file}'", error_log=LogLevels.WARNING)
+		def internal(src: str, dest: str) -> None:
+			super_copy(src, dest, create_dir=create_dir)
+		internal(destination, clean_path(dest_file))
+
+	return True
+
+
+# Main entry point for command line usage
+def archive_cli() -> None:
+	""" Main entry point for command line usage.
+
+	Examples:
+
+	.. code-block:: bash
+
+		# Repair a corrupted zip file
+		python -m stouputils.archive repair /path/to/corrupted.zip /path/to/repaired.zip
+
+		# Create a zip archive
+		python -m stouputils.archive make /path/to/source /path/to/destination.zip
+
+		# Create a zip archive with ignore patterns
+		python -m stouputils.archive make /path/to/source /path/to/destination.zip --ignore "*.pyc,__pycache__"
+	"""
+	import argparse
+	import sys
+
+	# Check for help or no command
+	if len(sys.argv) == 1 or (len(sys.argv) == 2 and sys.argv[1] in ("--help", "-h", "help")):
+		separator: str = "─" * 60
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"{CYAN}stouputils {GREEN}archive {CYAN}utilities{RESET}")
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"\n{CYAN}Usage:{RESET} stouputils archive <command> [options]")
+		print(f"\n{CYAN}Available commands:{RESET}")
+		print(f"  {GREEN}make{RESET} <source> <destination> [--ignore PATTERNS] [--create-dir]")
+		print("      Create a zip archive from source directory")
+		print(f"      {CYAN}--ignore{RESET}      Glob patterns to ignore (comma-separated)")
+		print(f"      {CYAN}--create-dir{RESET}  Create destination directory if needed")
+		print(f"\n  {GREEN}repair{RESET} <input_file> [output_file]")
+		print("      Repair a corrupted zip file")
+		print("      If output_file is omitted, adds '_repaired' suffix")
+		print(f"{CYAN}{separator}{RESET}")
+		return
+
+	parser = argparse.ArgumentParser(description="Archive utilities")
+	subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+	# Repair command
+	repair_parser = subparsers.add_parser("repair", help="Repair a corrupted zip file")
+	repair_parser.add_argument("input_file", help="Path to the corrupted zip file")
+	repair_parser.add_argument("output_file", nargs="?", help="Path to the repaired zip file (optional, defaults to input_file with '_repaired' suffix)")
+
+	# Make archive command
+	archive_parser = subparsers.add_parser("make", help="Create a zip archive")
+	archive_parser.add_argument("source", help="Source directory to archive")
+	archive_parser.add_argument("destination", help="Destination zip file")
+	archive_parser.add_argument("--ignore", help="Glob patterns to ignore (comma-separated)")
+	archive_parser.add_argument("--create-dir", action="store_true", help="Create destination directory if it doesn't exist")
+
+	args = parser.parse_args()
+
+	if args.command == "repair":
+		input_file = args.input_file
+		if args.output_file:
+			output_file = args.output_file
+		else:
+			# Generate default output filename
+			base, ext = os.path.splitext(input_file)
+			output_file = f"{base}_repaired{ext}"
+
+		debug(f"Repairing '{input_file}' to '{output_file}'...")
+		try:
+			repair_zip_file(input_file, output_file)
+			info(f"Successfully repaired zip file: {output_file}")
+		except Exception as e:
+			error(f"Error repairing zip file: {e}", exit=False)
+			sys.exit(1)
+
+	elif args.command == "make":
+		debug(f"Creating archive from '{args.source}' to '{args.destination}'...")
+		try:
+			make_archive(
+				source=args.source,
+				destinations=args.destination,
+				create_dir=args.create_dir,
+				ignore_patterns=args.ignore
+			)
+			info(f"Successfully created archive: {args.destination}")
+		except Exception as e:
+			error(f"Error creating archive: {e}", exit=False)
+			sys.exit(1)
+
+	else:
+		parser.print_help()
+		sys.exit(1)
+
+
+if __name__ == "__main__":
+	archive_cli()
+
+