mapFolding 0.12.2__tar.gz → 0.12.3__tar.gz

{mapfolding-0.12.2 → mapfolding-0.12.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.12.2
-Summary: Map folding algorithm with code transformation framework for optimizing numerical computations
+Version: 0.12.3
+Summary: Map folding algorithm with code transformation framework for optimizing numerical computations.
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
 Project-URL: Donate, https://www.patreon.com/integrated
@@ -29,25 +29,21 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: Z0Z_tools
 Requires-Dist: astToolkit>=0.5.0
-Requires-Dist: autoflake
+Requires-Dist: hunterMakesPy
 Requires-Dist: numba
 Requires-Dist: numba_progress
 Requires-Dist: numpy
 Requires-Dist: platformdirs
-Requires-Dist: python_minifier
-Requires-Dist: sympy
-Requires-Dist: tomli
+Provides-Extra: development
+Requires-Dist: mypy; extra == "development"
+Requires-Dist: pyupgrade; extra == "development"
+Requires-Dist: setuptools-scm; extra == "development"
 Provides-Extra: testing
-Requires-Dist: mypy; extra == "testing"
 Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-env; extra == "testing"
 Requires-Dist: pytest-xdist; extra == "testing"
-Requires-Dist: pyupgrade; extra == "testing"
-Requires-Dist: ruff; extra == "testing"
-Requires-Dist: setuptools-scm; extra == "testing"
 Dynamic: license-file
 
 # mapFolding

{mapfolding-0.12.2 → mapfolding-0.12.3}/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-0.12.3/mapFolding/_theSSOT.py

@@ -0,0 +1,81 @@
+"""
+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
+flow management to solve the complex combinatorial problem of counting distinct
+folding patterns across multi-dimensional maps.
+
+The Single Source Of Truth (SSOT) principle governs this foundation, ensuring that
+package identity, filesystem locations, and concurrency configuration remain
+consistent across all computational phases. During packaging, static metadata is
+resolved from pyproject.toml. During installation, filesystem-dependent paths are
+dynamically discovered. During runtime, the `packageSettings` instance provides
+unified access to all configuration values, enabling the sophisticated computational
+framework that follows.
+
+This configuration foundation supports the type system definition, core utility
+functions, computational state management, result persistence, and ultimately the
+main computational interface that users interact with to solve map folding problems.
+"""
+
+from hunterMakesPy import PackageSettings
+import dataclasses
+
+packageNameHARDCODED = "mapFolding"
+"""Hardcoded package name used as fallback when dynamic resolution fails."""
+
+concurrencyPackageHARDCODED = 'multiprocessing'
+"""Default package identifier for concurrent execution operations."""
+
+@dataclasses.dataclass
+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
+	package lifecycle. The metadata on each field indicates when that value is
+	determined - either during packaging or at installation/runtime.
+
+	The design supports different evaluation phases to optimize performance and
+	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.
+
+	"""
+
+	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
+	'multiprocessing' for standard parallel processing and 'numba' for
+	specialized numerical computations.
+	"""
+
+concurrencyPackage = concurrencyPackageHARDCODED
+"""Active concurrency package configuration for the current session."""
+
+packageSettings = mapFoldingPackageSettings(
+	identifierPackageFALLBACK=packageNameHARDCODED
+	, concurrencyPackage=concurrencyPackage)
+"""Global package settings."""

mapfolding-0.12.2/mapFolding/datatypes.py → mapfolding-0.12.3/mapFolding/_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-0.12.2 → mapfolding-0.12.3}/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)