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

mapFolding/__init__.py

@@ -1,5 +1,7 @@
 """Computational toolkit for analyzing multi-dimensional map folding patterns.
 
+(AI generated docstring)
+
 The mapFolding package provides a complete implementation of Lunnon's 1971 algorithm
 for counting distinct folding patterns in multi-dimensional maps. This toolkit
 transforms the complex combinatorial mathematics of map folding into accessible
@@ -40,7 +42,7 @@ For practitioners: The robust result persistence and type safety ensure
 reliable completion of complex analytical tasks.
 """
 
-from mapFolding.datatypes import (
+from mapFolding._theTypes import (
 	Array1DElephino as Array1DElephino,
 	Array1DFoldsTotal as Array1DFoldsTotal,
 	Array1DLeavesTotal as Array1DLeavesTotal,
@@ -54,7 +56,7 @@ from mapFolding.datatypes import (
 	NumPyLeavesTotal as NumPyLeavesTotal,
 )
 
-from mapFolding._theSSOT import PackageSettings as PackageSettings, packageSettings as packageSettings
+from mapFolding._theSSOT import packageSettings as packageSettings
 
 from mapFolding.beDRY import (
 	getConnectionGraph as getConnectionGraph,

mapFolding/_theSSOT.py

@@ -1,6 +1,8 @@
 """
 Foundation layer for the map folding computational ecosystem.
 
+(AI generated docstring)
+
 This module establishes the fundamental configuration infrastructure that underpins
 all map folding operations. Map folding, as defined by Lunnon's 1971 algorithm,
 requires precise coordination of computational resources, type systems, and data
@@ -20,72 +22,20 @@ functions, computational state management, result persistence, and ultimately th
 main computational interface that users interact with to solve map folding problems.
 """
 
-from importlib import import_module as importlib_import_module
-from inspect import getfile as inspect_getfile
-from pathlib import Path
-from tomli import load as tomli_load
+from hunterMakesPy import PackageSettings
 import dataclasses
 
-packageNamePACKAGING_HARDCODED = "mapFolding"
-"""
-Hardcoded package name used as fallback when dynamic resolution fails.
-
-This constant serves as the ultimate fallback for package name resolution,
-ensuring the package can function even when pyproject.toml is not accessible
-during packaging or when module introspection fails during installation.
-"""
+packageNameHARDCODED = "mapFolding"
+"""Hardcoded package name used as fallback when dynamic resolution fails."""
 
 concurrencyPackageHARDCODED = 'multiprocessing'
-"""
-Default package identifier for concurrent execution operations.
-
-Specifies which Python concurrency package should be used as the default
-for parallel computations. This can be overridden through PackageSettings
-to use alternative packages like 'numba' for specialized performance scenarios.
-"""
-
-# Evaluate When Packaging
-# https://github.com/hunterhogan/mapFolding/issues/18
-try:
-	packageNamePACKAGING: str = tomli_load(Path("../pyproject.toml").open('rb'))["project"]["name"]
-	"""
-	Package name dynamically resolved from pyproject.toml during packaging.
-
-	This value is determined by reading the project configuration file during
-	the packaging process, ensuring consistency between the package metadata
-	and runtime identification. Falls back to hardcoded value if resolution fails.
-	"""
-except Exception:
-	packageNamePACKAGING = packageNamePACKAGING_HARDCODED
-
-# Evaluate When Installing
-# https://github.com/hunterhogan/mapFolding/issues/18
-def getPathPackageINSTALLING() -> Path:
-	"""
-	Resolve the absolute filesystem path to the installed package directory.
-
-	This function determines the package location at runtime by introspecting
-	the imported module's file location. It handles both regular Python files
-	and package directories, ensuring reliable path resolution across different
-	installation methods and environments.
-
-	Returns:
-		pathPackage: Absolute path to the package directory containing the module files.
-
-	Notes:
-		The function automatically handles the case where module introspection
-		returns a file path by extracting the parent directory, ensuring the
-		returned path always points to the package directory itself.
-	"""
-	pathPackage: Path = Path(inspect_getfile(importlib_import_module(packageNamePACKAGING)))
-	if pathPackage.is_file():
-		pathPackage = pathPackage.parent
-	return pathPackage
+"""Default package identifier for concurrent execution operations."""
 
 @dataclasses.dataclass
-class PackageSettings:
-	"""
-	Centralized configuration container for all package-wide settings.
+class mapFoldingPackageSettings(PackageSettings):
+	"""Centralized configuration container for all package-wide settings.
+
+	(AI generated docstring)
 
 	This dataclass serves as the single source of truth for package configuration,
 	providing both static and dynamically-resolved values needed throughout the
@@ -93,23 +43,28 @@ class PackageSettings:
 	determined - either during packaging or at installation/runtime.
 
 	The design supports different evaluation phases to optimize performance and
-	reliability:
-	- Packaging-time: Values that can be determined during package creation
-	- Installing-time: Values that require filesystem access or module introspection
-
-	Attributes:
-		fileExtension: Standard file extension for Python modules in this package.
-		packageName: Canonical name of the package as defined in project configuration.
-		pathPackage: Absolute filesystem path to the installed package directory.
-		concurrencyPackage: Package to use for concurrent execution operations.
+	reliability. Packaging-time values can be determined during package creation,
+	while installing-time values require filesystem access or module introspection.
+
+	Attributes
+	----------
+	fileExtension : str = '.py'
+		Standard file extension for Python modules in this package.
+	packageName : str
+		Canonical name of the package as defined in project configuration.
+	pathPackage : Path
+		Absolute filesystem path to the installed package directory.
+	concurrencyPackage : str | None = None
+		Package identifier for concurrent execution operations.
+
 	"""
-	fileExtension: str = dataclasses.field(default='.py', metadata={'evaluateWhen': 'installing'})
-	packageName: str = dataclasses.field(default = packageNamePACKAGING, metadata={'evaluateWhen': 'packaging'})
-	pathPackage: Path = dataclasses.field(default_factory=getPathPackageINSTALLING, metadata={'evaluateWhen': 'installing'})
+
 	concurrencyPackage: str | None = None
 	"""
 	Package identifier for concurrent execution operations.
 
+	(AI generated docstring)
+
 	Specifies which Python package should be used for parallel processing
 	in computationally intensive operations. When None, the default concurrency
 	package specified in the module constants is used. Accepted values include
@@ -118,20 +73,9 @@ class PackageSettings:
 	"""
 
 concurrencyPackage = concurrencyPackageHARDCODED
-"""
-Active concurrency package configuration for the current session.
-
-This module-level variable holds the currently selected concurrency package
-identifier, initialized from the hardcoded default but available for runtime
-modification through the package settings system.
-"""
+"""Active concurrency package configuration for the current session."""
 
-packageSettings = PackageSettings(concurrencyPackage=concurrencyPackage)
-"""
-Global package settings instance providing access to all configuration values.
-
-This singleton instance serves as the primary interface for accessing package
-configuration throughout the codebase. It combines statically-defined defaults
-with dynamically-resolved values to provide a complete configuration profile
-for the current package installation and runtime environment.
-"""
+packageSettings = mapFoldingPackageSettings(
+	identifierPackageFALLBACK=packageNameHARDCODED
+	, concurrencyPackage=concurrencyPackage)
+"""Global package settings."""

mapFolding/{datatypes.py → _theTypes.py}

@@ -1,6 +1,8 @@
 """
 Type system architecture for map folding computational domains.
 
+(AI generated docstring)
+
 Building upon the configuration foundation, this module defines the complete type
 hierarchy that ensures type safety and semantic clarity throughout the map folding
 computational framework. The type system recognizes three distinct computational
@@ -20,15 +22,15 @@ complex multi-dimensional folding patterns. The array types built from these
 base types provide the structured data containers that computational state
 management depends upon.
 """
-from numpy import (
-	dtype, integer, ndarray, uint8 as numpy_uint8, uint16 as numpy_uint16, uint64 as numpy_uint64,
-)
+from numpy import dtype, integer, ndarray, uint8 as numpy_uint8, uint16 as numpy_uint16, uint64 as numpy_uint64
 from typing import Any, TypeAlias, TypeVar
 
 NumPyIntegerType = TypeVar('NumPyIntegerType', bound=integer[Any], covariant=True)
 """
 Generic type variable for NumPy integer types used in computational operations.
 
+(AI generated docstring)
+
 This type variable enables generic programming with NumPy integer types while
 maintaining type safety. It supports covariant relationships between different
 NumPy integer types and their array containers.
@@ -38,6 +40,8 @@ DatatypeLeavesTotal: TypeAlias = int
 """
 Python type for leaf-related counts and indices in map folding computations.
 
+(AI generated docstring)
+
 Represents quantities related to individual map sections (leaves), including
 total leaf counts, leaf indices, and dimensional parameters. Uses standard
 Python integers for compatibility with general computations while enabling
@@ -48,6 +52,8 @@ NumPyLeavesTotal: TypeAlias = numpy_uint8
 """
 NumPy type for efficient leaf-related computations and array operations.
 
+(AI generated docstring)
+
 Corresponds to `DatatypeLeavesTotal` but optimized for NumPy operations.
 Uses 8-bit unsigned integers since leaf counts in practical map folding
 scenarios typically remain small (under 256).
@@ -57,6 +63,8 @@ DatatypeElephino: TypeAlias = int
 """
 Python type for internal computational indices and intermediate values.
 
+(AI generated docstring)
+
 Used for temporary variables, gap indices, and other internal computational
 state that doesn't directly correspond to leaves or final fold counts. The
 name follows the package convention for internal computational domains.
@@ -66,6 +74,8 @@ NumPyElephino: TypeAlias = numpy_uint16
 """
 NumPy type for internal computational operations requiring moderate value ranges.
 
+(AI generated docstring)
+
 Corresponds to `DatatypeElephino` with 16-bit unsigned integer storage,
 providing sufficient range for internal computations while maintaining
 memory efficiency in array operations.
@@ -75,6 +85,8 @@ DatatypeFoldsTotal: TypeAlias = int
 """
 Python type for final fold counts and pattern totals.
 
+(AI generated docstring)
+
 Represents the ultimate results of map folding computations - the total number
 of distinct folding patterns possible for a given map configuration. These
 values can grow exponentially with map size, requiring flexible integer types.
@@ -84,6 +96,8 @@ NumPyFoldsTotal: TypeAlias = numpy_uint64
 """
 NumPy type for large fold count computations and high-precision results.
 
+(AI generated docstring)
+
 Corresponds to `DatatypeFoldsTotal` using 64-bit unsigned integers to
 accommodate the exponentially large values that can result from map folding
 computations on even moderately-sized maps.
@@ -93,6 +107,8 @@ Array3D: TypeAlias = ndarray[tuple[int, int, int], dtype[NumPyLeavesTotal]]
 """
 Three-dimensional NumPy array type for connection graph representations.
 
+(AI generated docstring)
+
 Used to store the connectivity relationships between map leaves in a
 3D array structure. The array uses `NumPyLeavesTotal` element type since
 the stored values represent leaf indices and connection states.
@@ -102,6 +118,8 @@ Array1DLeavesTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyLeavesTotal]]
 """
 One-dimensional NumPy array type for leaf-related data sequences.
 
+(AI generated docstring)
+
 Stores sequences of leaf counts, indices, or related values in efficient
 array format. Common uses include leaf sequences, gap locations, and
 dimensional data where each element relates to the leaves domain.
@@ -111,6 +129,8 @@ Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[NumPyElephino]]
 """
 One-dimensional NumPy array type for internal computational sequences.
 
+(AI generated docstring)
+
 Used for storing sequences of internal computational values such as
 gap range starts, temporary indices, and other intermediate results
 that require the elephino computational domain's value range.
@@ -120,6 +140,8 @@ Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyFoldsTotal]]
 """
 One-dimensional NumPy array type for sequences of fold count results.
 
+(AI generated docstring)
+
 Stores sequences of fold totals and pattern counts, using the large
 integer type to accommodate the potentially enormous values that
 result from complex map folding computations.

mapFolding/basecamp.py

@@ -1,6 +1,8 @@
 """
 Unified interface for map folding computation orchestration.
 
+(AI generated docstring)
+
 This module represents the culmination of the computational ecosystem, providing
 the primary entry point where users interact with the complete map folding analysis
 system. It orchestrates all preceding layers: the configuration foundation,
@@ -23,13 +25,13 @@ consistent, reliable, and efficiently computed folding pattern counts.
 
 from collections.abc import Sequence
 from mapFolding import (
-	getPathFilenameFoldsTotal, packageSettings, saveFoldsTotal, saveFoldsTotalFAILearly,
-	setProcessorLimit, validateListDimensions,
-)
+	getPathFilenameFoldsTotal, packageSettings, saveFoldsTotal, saveFoldsTotalFAILearly, setProcessorLimit,
+	validateListDimensions)
 from os import PathLike
 from pathlib import PurePath
+import contextlib
 
-def countFolds(listDimensions: Sequence[int] | None = None
+def countFolds(listDimensions: Sequence[int] | None = None  # noqa: C901
 				, pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None
 				, computationDivisions: int | str | None = None
 				, CPUlimit: int | float | bool | None = None
@@ -42,6 +44,8 @@ def countFolds(listDimensions: Sequence[int] | None = None
 	"""
 	Count the total number of possible foldings for a given map dimensions.
 
+	(AI generated docstring)
+
 	This function serves as the main public interface to the map folding algorithm, handling all parameter validation,
 	computation state management, and result persistence in a user-friendly way.
 
@@ -86,32 +90,33 @@ def countFolds(listDimensions: Sequence[int] | None = None
 	computation time. If logicalCores >= `leavesTotal`, it will probably be faster. If logicalCores <= 2 * `leavesTotal`, it
 	will almost certainly be slower for all map dimensions.
 	"""
-	# mapShape =====================================================================
+	# mapShape ---------------------------------------------------------------------
 
 	if mapShape:
 		pass
 	else:
 		if oeisID and oeis_n:
-			from mapFolding.oeis import settingsOEIS
-			try:
+			from mapFolding.oeis import settingsOEIS  # noqa: PLC0415
+			with contextlib.suppress(KeyError):
 				mapShape = settingsOEIS[oeisID]['getMapShape'](oeis_n)
-			except KeyError:
-				pass
 		if not mapShape and listDimensions:
 			mapShape = validateListDimensions(listDimensions)
 
 	if mapShape is None:
-		raise ValueError(f"""I received these values:
+		message = (
+			f"""I received these values:
 	`{listDimensions = }`,
 	`{mapShape = }`,
 	`{oeisID = }` and `{oeis_n = }`,
-	but I was unable to select a map for which to count the folds.""")
+	but I was unable to select a map for which to count the folds."""
+		)
+		raise ValueError(message)
 
-	# task division instructions ===============================================
+	# task division instructions -----------------------------------------------------
 
 	if computationDivisions:
 		concurrencyLimit: int = setProcessorLimit(CPUlimit, packageSettings.concurrencyPackage)
-		from mapFolding.beDRY import getLeavesTotal, getTaskDivisions
+		from mapFolding.beDRY import getLeavesTotal, getTaskDivisions  # noqa: PLC0415
 		leavesTotal: int = getLeavesTotal(mapShape)
 		taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
 		del leavesTotal
@@ -119,7 +124,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 		concurrencyLimit = 1
 		taskDivisions = 0
 
-	# memorialization instructions ===========================================
+	# memorialization instructions ---------------------------------------------
 
 	if pathLikeWriteFoldsTotal is not None:
 		pathFilenameFoldsTotal = getPathFilenameFoldsTotal(mapShape, pathLikeWriteFoldsTotal)
@@ -127,70 +132,70 @@ def countFolds(listDimensions: Sequence[int] | None = None
 	else:
 		pathFilenameFoldsTotal = None
 
-	# Flow control until I can figure out a good way ===============================
+	# Flow control until I can figure out a good way ---------------------------------
 
 	if flow == 'daoOfMapFolding':
-		from mapFolding.dataBaskets import MapFoldingState
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.daoOfMapFolding import doTheNeedful
+		from mapFolding.daoOfMapFolding import doTheNeedful  # noqa: PLC0415
 		mapFoldingState = doTheNeedful(mapFoldingState)
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2' and any(dimension > 2 for dimension in mapShape):
-		from mapFolding.dataBaskets import MapFoldingState
+	elif flow == 'theorem2' and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
+		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds  # noqa: PLC0415
 		mapFoldingState = initializeGroupsOfFolds(mapFoldingState)
 
-		from mapFolding.syntheticModules.theorem2 import count
+		from mapFolding.syntheticModules.theorem2 import count  # noqa: PLC0415
 		mapFoldingState = count(mapFoldingState)
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2Trimmed' and any(dimension > 2 for dimension in mapShape):
-		from mapFolding.dataBaskets import MapFoldingState
+	elif flow == 'theorem2Trimmed' and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
+		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds  # noqa: PLC0415
 		mapFoldingState = initializeGroupsOfFolds(mapFoldingState)
 
-		from mapFolding.syntheticModules.theorem2Trimmed import count
+		from mapFolding.syntheticModules.theorem2Trimmed import count  # noqa: PLC0415
 		mapFoldingState = count(mapFoldingState)
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any(dimension > 2 for dimension in mapShape):
-		from mapFolding.dataBaskets import MapFoldingState
+	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
+		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds  # noqa: PLC0415
 		mapFoldingState = initializeGroupsOfFolds(mapFoldingState)
 
-		from mapFolding.syntheticModules.dataPacking import sequential
+		from mapFolding.syntheticModules.dataPacking import sequential  # noqa: PLC0415
 		mapFoldingState = sequential(mapFoldingState)
 
 		foldsTotal = mapFoldingState.foldsTotal
 
 	elif taskDivisions > 1:
-		from mapFolding.dataBaskets import ParallelMapFoldingState
+		from mapFolding.dataBaskets import ParallelMapFoldingState  # noqa: PLC0415
 		parallelMapFoldingState: ParallelMapFoldingState = ParallelMapFoldingState(mapShape, taskDivisions=taskDivisions)
 
-		from mapFolding.syntheticModules.countParallel import doTheNeedful
+		from mapFolding.syntheticModules.countParallel import doTheNeedful  # noqa: PLC0415
 
 		# `listStatesParallel` exists in case you want to research the parallel computation.
 		foldsTotal, listStatesParallel = doTheNeedful(parallelMapFoldingState, concurrencyLimit) # pyright: ignore[reportUnusedVariable]
 
 	else:
-		from mapFolding.dataBaskets import MapFoldingState
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.daoOfMapFolding import doTheNeedful
+		from mapFolding.syntheticModules.daoOfMapFolding import doTheNeedful  # noqa: PLC0415
 		mapFoldingState = doTheNeedful(mapFoldingState)
 		foldsTotal = mapFoldingState.foldsTotal
 
-	# Follow memorialization instructions ===========================================
+	# Follow memorialization instructions ---------------------------------------------
 
 	if pathFilenameFoldsTotal is not None:
 		saveFoldsTotal(pathFilenameFoldsTotal, foldsTotal)