mapFolding 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

mapFolding/filesystemToolkit.py

@@ -1,6 +1,8 @@
 """
 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
@@ -27,47 +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: A sequence of integers representing the map dimensions.
-		pathLikeWriteFoldsTotal (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.
+	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.
 
-	Notes:
-		The function creates any necessary directories in the path if they don't exist.
-	"""
+	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.
+
+	"""
 	if pathLikeWriteFoldsTotal is None:
 		pathFilenameFoldsTotal = getPathRootJobDEFAULT() / getFilenameFoldsTotal(mapShape)
 	else:
@@ -83,133 +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:
-	"""
-	Internal 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: Path where the `foldsTotal` value should be saved.
-		foldsTotal: The integer value to save.
+	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.
 
-	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.
 	"""
 	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.
-	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.
-
-		The fallback filename includes a unique identifier based on the value itself to prevent conflicts.
+
+	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.
+
 	"""
 	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.
+	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.
 
-	Raises:
-		FileExistsError: If the target file already exists.
-		FileNotFoundError: If parent directories don't exist or if write tests fail.
-	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. The test value used is a large integer that exercises both the writing and
-		reading mechanisms thoroughly.
 	"""
 	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