mapFolding 0.12.1__py3-none-any.whl → 0.12.3__py3-none-any.whl

mapFolding/filesystemToolkit.py

@@ -1,26 +1,26 @@
 """
-Filesystem utilities for managing map folding computation results.
-
-This module provides functions for standardized handling of files related to the mapFolding package, with a focus on
-saving, retrieving, and naming computation results. It implements consistent naming conventions and path resolution
-strategies to ensure that:
-
-1. Computation results are stored in a predictable location.
-2. Filenames follow a consistent pattern based on map dimensions.
-3. Results can be reliably retrieved for future reference.
-4. The system handles file operations safely with appropriate error handling.
-
-The module serves as the standardized interface between the computational components of the package and the filesystem,
-abstracting away the details of file operations and path management. It provides robust fallback mechanisms to preserve
-computation results even in the face of filesystem errors, which is critical for long-running computations that may take
-days to complete.
-
-The functions here adhere to a consistent approach to path handling:
-- Cross-platform compatibility through the use of `pathlib`.
-- Default locations determined intelligently based on the runtime environment.
-- Progressive fallback strategies for saving critical computation results.
-- Preemptive filesystem validation to detect issues before computation begins.
+Persistent storage infrastructure for map folding computation results.
+
+(AI generated docstring)
+
+As computational state management orchestrates the complex recursive analysis,
+this module ensures that the valuable results of potentially multi-day computations
+are safely preserved and reliably retrievable. Map folding problems can require
+extensive computational time, making robust result persistence critical for
+practical research and application.
+
+The storage system provides standardized filename generation, platform-independent
+path resolution, and multiple fallback strategies to prevent data loss. Special
+attention is given to environments like Google Colab and cross-platform deployment
+scenarios. The storage patterns integrate with the configuration foundation to
+provide consistent behavior across different installation contexts.
+
+This persistence layer serves as the crucial bridge between the computational
+framework and the user interface, ensuring that computation results are available
+for the main interface to retrieve, validate, and present to users seeking
+solutions to their map folding challenges.
 """
+
 from mapFolding import packageSettings
 from os import PathLike
 from pathlib import Path, PurePath
@@ -29,48 +29,57 @@ import os
 import platformdirs
 
 def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
-	"""
-	Create a standardized filename for a computed `foldsTotal` value.
+	"""Create a standardized filename for a computed `foldsTotal` value.
+
+	(AI generated docstring)
 
 	This function generates a consistent, filesystem-safe filename based on map dimensions. Standardizing filenames
 	ensures that results can be reliably stored and retrieved, avoiding potential filesystem incompatibilities or Python
 	naming restrictions.
 
-	Parameters:
-		mapShape: A sequence of integers representing the dimensions of the map.
+	Parameters
+	----------
+	mapShape : tuple[int, ...]
+		A sequence of integers representing the dimensions of the map.
+
+	Returns
+	-------
+	filenameFoldsTotal : str
+		A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions.
 
-	Returns:
-		filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions.
+	Notes
+	-----
+	The filename format ensures no spaces in the filename, safe filesystem characters, unique extension (.foldsTotal),
+	Python-safe strings (no starting with numbers, no reserved words), and the 'p' prefix comes from Lunnon's original code.
 
-	Notes:
-		The filename format ensures:
-		- No spaces in the filename
-		- Safe filesystem characters
-		- Unique extension (.foldsTotal)
-		- Python-safe strings (no starting with numbers, no reserved words)
-		- The 'p' prefix comes from Lunnon's original code.
 	"""
 	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
 
 def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None) -> Path:
-	"""
-	Get a standardized path and filename for the computed `foldsTotal` value.
+	"""Get a standardized path and filename for the computed `foldsTotal` value.
+
+	(AI generated docstring)
 
 	This function resolves paths for storing computation results, handling different input types including directories,
 	absolute paths, or relative paths. It ensures that all parent directories exist in the resulting path.
 
-	Parameters:
-		mapShape: List of dimensions for the map folding problem.
-		pathLikeWriteFoldsTotal (getPathJobRootDEFAULT): Path, filename, or relative path and filename. If None, uses
-			default path. If a directory, appends standardized filename.
+	Parameters
+	----------
+	mapShape : tuple[int, ...]
+		A sequence of integers representing the map dimensions.
+	pathLikeWriteFoldsTotal : PathLike[str] | PurePath | None = getPathRootJobDEFAULT()
+		Path, filename, or relative path and filename. If None, uses default path. If a directory, appends standardized filename.
 
-	Returns:
-		pathFilenameFoldsTotal: Absolute path and filename for storing the `foldsTotal` value.
+	Returns
+	-------
+	pathFilenameFoldsTotal : Path
+		Absolute path and filename for storing the `foldsTotal` value.
 
-	Notes:
-		The function creates any necessary directories in the path if they don't exist.
-	"""
+	Notes
+	-----
+	The function creates any necessary directories in the path if they don't exist.
 
+	"""
 	if pathLikeWriteFoldsTotal is None:
 		pathFilenameFoldsTotal = getPathRootJobDEFAULT() / getFilenameFoldsTotal(mapShape)
 	else:
@@ -86,125 +95,170 @@ def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal
 	return pathFilenameFoldsTotal
 
 def getPathRootJobDEFAULT() -> Path:
-	"""
-	Get the default root directory for map folding computation jobs.
+	"""Get the default root directory for map folding computation jobs.
+
+	(AI generated docstring)
 
 	This function determines the appropriate default directory for storing computation results based on the current
 	runtime environment. It uses platform-specific directories for normal environments and adapts to special
 	environments like Google Colab.
 
-	Returns:
-		pathJobDEFAULT: Path to the default directory for storing computation results
+	Returns
+	-------
+	pathJobDEFAULT : Path
+		Path to the default directory for storing computation results.
+
+	Notes
+	-----
+	For standard environments, uses `platformdirs` to find appropriate user data directory.
+	For Google Colab, uses a specific path in Google Drive.
+	Creates the directory if it doesn't exist.
 
-	Notes:
-		- For standard environments, uses `platformdirs` to find appropriate user data directory.
-		- For Google Colab, uses a specific path in Google Drive.
-		- Creates the directory if it doesn't exist.
 	"""
-	pathJobDEFAULT = Path(platformdirs.user_data_dir(appname=packageSettings.packageName, appauthor=False, ensure_exists=True))
+	pathJobDEFAULT = Path(platformdirs.user_data_dir(appname=packageSettings.identifierPackage, appauthor=False, ensure_exists=True))
 	if 'google.colab' in sysModules:
-		pathJobDEFAULT = Path("/content/drive/MyDrive") / packageSettings.packageName
+		pathJobDEFAULT = Path("/content/drive/MyDrive") / packageSettings.identifierPackage
 	pathJobDEFAULT.mkdir(parents=True, exist_ok=True)
 	return pathJobDEFAULT
 
 def _saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> None:
-	"""
-	Standardized function to save a `foldsTotal` value to a file.
+	"""Save a `foldsTotal` value to a file.
+
+	(AI generated docstring)
+
+	This function provides the core file writing functionality used by the public `saveFoldsTotal` function. It handles
+	the basic operations of creating parent directories and writing the integer value as text to the specified file
+	location.
+
+	Parameters
+	----------
+	pathFilename : PathLike[str] | PurePath
+		Path where the `foldsTotal` value should be saved.
+	foldsTotal : int
+		The integer value to save.
+
+	Notes
+	-----
+	This is an internal function that doesn't include error handling or fallback mechanisms. Use `saveFoldsTotal`
+	for production code that requires robust error handling.
 
-	Parameters:
-		pathFilename: Path where the `foldsTotal` value should be saved
-		foldsTotal: The integer value to save
 	"""
 	pathFilenameFoldsTotal = Path(pathFilename)
 	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
 	pathFilenameFoldsTotal.write_text(str(foldsTotal))
 
 def saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> None:
-	"""
-	Save `foldsTotal` value to disk with multiple fallback mechanisms.
+	"""Save `foldsTotal` value to disk with multiple fallback mechanisms.
+
+	(AI generated docstring)
 
 	This function attempts to save the computed `foldsTotal` value to the specified location, with backup strategies in
 	case the primary save attempt fails. The robustness is critical since these computations may take days to complete.
 
-	Parameters:
-		pathFilename: Target save location for the `foldsTotal` value
-		foldsTotal: The computed value to save
+	Parameters
+	----------
+	pathFilename : PathLike[str] | PurePath
+		Target save location for the `foldsTotal` value.
+	foldsTotal : int
+		The computed value to save.
+
+	Notes
+	-----
+	If the primary save fails, the function will attempt alternative save methods.
+	Print the value prominently to `stdout`.
+	Create a fallback file in the current working directory.
+	As a last resort, simply print the value.
+
+	The fallback filename includes a unique identifier based on the value itself to prevent conflicts.
 
-	Notes:
-		If the primary save fails, the function will attempt alternative save methods:
-		1. Print the value prominently to `stdout`.
-		2. Create a fallback file in the current working directory.
-		3. As a last resort, simply print the value.
 	"""
 	try:
 		_saveFoldsTotal(pathFilename, foldsTotal)
-	except Exception as ERRORmessage:
+	except Exception as ERRORmessage:  # noqa: BLE001
 		try:
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
-			print(ERRORmessage)
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")  # noqa: T201
+			print(ERRORmessage)  # noqa: T201
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")  # noqa: T201
 			randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
 			filenameInfixUnique = ''.join(randomnessPlanB)
-			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
-			writeStreamFallback = open(pathFilenamePlanB, 'w')
+			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')  # noqa: PTH109, PTH118
+			writeStreamFallback = open(pathFilenamePlanB, 'w')  # noqa: PTH123, SIM115
 			writeStreamFallback.write(str(foldsTotal))
 			writeStreamFallback.close()
-			print(str(pathFilenamePlanB))
-		except Exception:
-			print(foldsTotal)
-	return None
+			print(str(pathFilenamePlanB))  # noqa: T201
+		except Exception:  # noqa: BLE001
+			print(foldsTotal)  # noqa: T201
 
 def saveFoldsTotalFAILearly(pathFilename: PathLike[str] | PurePath) -> None:
-	"""
-	Preemptively test file write capabilities before beginning computation.
+	"""Preemptively test file write capabilities before beginning computation.
 
-	This function performs validation checks on the target file location before a potentially long-running computation
-	begins. It tests several critical aspects of filesystem functionality to ensure results can be saved:
+	(AI generated docstring)
 
+	This function performs validation checks on the target file location before a potentially long-running computation
+	begins. It tests several critical aspects of filesystem functionality to ensure results can be saved.
+
+	Parameters
+	----------
+	pathFilename : PathLike[str] | PurePath
+		The path and filename where computation results will be saved.
+
+	Raises
+	------
+	FileExistsError
+		If the target file already exists.
+	FileNotFoundError
+		If parent directories don't exist or if write tests fail.
+
+	Notes
+	-----
+	Checks performed:
 	1. Checks if the file already exists to prevent accidental overwrites.
 	2. Verifies that parent directories exist.
 	3. Tests if the system can write a test value to the file.
 	4. Confirms that the written value can be read back correctly.
 
-	Parameters:
-		pathFilename: The path and filename where computation results will be saved.
-
-	Raises:
-		FileExistsError: If the target file already exists.
-		FileNotFoundError: If parent directories don't exist or if write tests fail.
+	This function helps prevent a situation where a computation runs for hours or days only to discover at the end
+	that results cannot be saved. The test value used is a large integer that exercises both the writing and
+	reading mechanisms thoroughly.
 
-	Notes:
-		This function helps prevent a situation where a computation runs for hours or days only to discover at the end
-		that results cannot be saved.
 	"""
 	if Path(pathFilename).exists():
-		raise FileExistsError(f"`{pathFilename = }` exists: a battle of overwriting might cause tears.")
+		message = f"`{pathFilename = }` exists: a battle of overwriting might cause tears."
+		raise FileExistsError(message)
 	if not Path(pathFilename).parent.exists():
-		raise FileNotFoundError(f"I received `{pathFilename = }` 0.000139 seconds ago from a function that promised it created the parent directory, but the parent directory does not exist. Fix that now, so your computation doesn't get deleted later. And be compassionate to others.")
+		message = f"I received `{pathFilename = }` 0.000139 seconds ago from a function that promised it created the parent directory, but the parent directory does not exist. Fix that now, so your computation doesn't get deleted later. And be compassionate to others."
+		raise FileNotFoundError(message)
 	foldsTotal = 149302889205120
 	_saveFoldsTotal(pathFilename, foldsTotal)
 	if not Path(pathFilename).exists():
-		raise FileNotFoundError(f"I just wrote a test file to `{pathFilename = }`, but it does not exist. Fix that now, so your computation doesn't get deleted later. And continually improve your empathy skills.")
-	foldsTotalRead = int(Path(pathFilename).read_text())
+		message = f"I just wrote a test file to `{pathFilename = }`, but it does not exist. Fix that now, so your computation doesn't get deleted later. And continually improve your empathy skills."
+		raise FileNotFoundError(message)
+	foldsTotalRead = int(Path(pathFilename).read_text(encoding="utf-8"))
 	if foldsTotalRead != foldsTotal:
-		raise FileNotFoundError(f"I wrote a test file to `{pathFilename = }` with contents of `{str(foldsTotal) = }`, but I read `{foldsTotalRead = }` from the file. Python says the values are not equal. Fix that now, so your computation doesn't get corrupted later. And be pro-social.")
+		message = f"I wrote a test file to `{pathFilename = }` with contents of `{str(foldsTotal) = }`, but I read `{foldsTotalRead = }` from the file. Python says the values are not equal. Fix that now, so your computation doesn't get corrupted later. And be pro-social."
+		raise FileNotFoundError(message)
 
 def writeStringToHere(this: str, pathFilename: PathLike[str] | PurePath) -> None:
-	"""
-	Write a string to a file, creating parent directories if needed.
+	"""Write a string to a file, creating parent directories if needed.
+
+	(AI generated docstring)
 
 	This utility function provides a consistent interface for writing string content to files across the package. It
 	handles path creation and ensures proper string conversion.
 
-	Parameters:
-		this: The string content to write to the file.
-		pathFilename: The target file path where the string should be written.
+	Parameters
+	----------
+	this : str
+		The string content to write to the file.
+	pathFilename : PathLike[str] | PurePath
+		The target file path where the string should be written.
+
+	Notes
+	-----
+	This function creates all parent directories in the path if they don't exist, making it safe to use with newly
+	created directory structures.
 
-	Notes:
-		This function creates all parent directories in the path if they don't exist, making it safe to use with newly
-		created directory structures.
 	"""
 	pathFilename = Path(pathFilename)
 	pathFilename.parent.mkdir(parents=True, exist_ok=True)
 	pathFilename.write_text(str(this))
-	return None