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

tests/test_computations.py

@@ -1,88 +1,26 @@
-"""
-Core Algorithm and Module Generation Testing
-
-This module provides tests for validating algorithm correctness and testing
-code generation functionality. It's designed not only to test the package's
-functionality but also to serve as a template for users testing their own
-custom implementations.
-
-## Key Testing Categories
-
-1. Algorithm Validation Tests
-   - `test_algorithmSourceParallel` - Tests the source algorithm in parallel mode
-   - `test_algorithmSourceSequential` - Tests the source algorithm in sequential mode
-   - `test_aOFn_calculate_value` - Tests OEIS sequence value calculations
-
-2. Synthetic Module Tests
-   - `test_syntheticParallel` - Tests generated Numba-optimized code in parallel mode
-   - `test_syntheticSequential` - Tests generated Numba-optimized code in sequential mode
-
-3. Job Testing
-   - `test_writeJobNumba` - Tests job-specific module generation and execution
-
-## How to Test Your Custom Implementations
-
-### Testing Custom Recipes (RecipeSynthesizeFlow):
-
-1. Copy the `syntheticDispatcherFixture` from conftest.py
-2. Modify it to use your custom recipe configuration
-3. Copy and adapt `test_syntheticParallel` and `test_syntheticSequential`
-
-Example:
-
-```python
-@pytest.fixture
-def myCustomRecipeFixture(useThisDispatcher, pathTmpTesting):
-    # Create your custom recipe configuration
-    myRecipe = RecipeSynthesizeFlow(
-        pathPackage=PurePosixPath(pathTmpTesting.absolute()),
-        # Add your custom configuration
-    )
-
-    # Generate the module
-    makeNumbaFlow(myRecipe)
-
-    # Import and patch the dispatcher
-    # ... (similar to syntheticDispatcherFixture)
+"""Core computational verification and algorithm validation tests.
 
-    return customDispatcher
+This module validates the mathematical correctness of map folding computations and
+serves as the primary testing ground for new computational approaches. It's the most
+important module for users who create custom folding algorithms or modify existing ones.
 
-def test_myCustomRecipeParallel(myCustomRecipeFixture, listDimensionsTestParallelization):
-    # Test with the standardized validation utility
-    standardizedEqualToCallableReturn(
-        getFoldsTotalKnown(tuple(listDimensionsTestParallelization)),
-        countFolds,
-        listDimensionsTestParallelization,
-        None,
-        'maximum'
-    )
-```
+The tests here verify that different computational flows produce identical results,
+ensuring mathematical consistency across implementation strategies. This is critical
+for maintaining confidence in results as the codebase evolves and new optimization
+techniques are added.
 
-### Testing Custom Jobs (RecipeJob):
+Key Testing Areas:
+- Flow control validation across different algorithmic approaches
+- OEIS sequence value verification against known mathematical results
+- Code generation and execution for dynamically created computational modules
+- Numerical accuracy and consistency checks
 
-1. Copy and adapt `test_writeJobNumba`
-2. Modify it to use your custom job configuration
+For users implementing new computational methods: use the `test_flowControl` pattern
+as a template. It demonstrates how to validate that your algorithm produces results
+consistent with the established mathematical foundation.
 
-Example:
-
-```python
-def test_myCustomJob(oneTestCuzTestsOverwritingTests, pathFilenameTmpTesting):
-    # Create your custom job configuration
-    myJob = RecipeJob(
-        state=makeInitializedComputationState(validateListDimensions(oneTestCuzTestsOverwritingTests)),
-        # Add your custom configuration
-    )
-
-    spices = SpicesJobNumba()
-    # Customize spices if needed
-
-    # Generate and test the job
-    makeJobNumba(myJob, spices)
-    # Test execution similar to test_writeJobNumba
-```
-
-All tests leverage standardized utilities like `standardizedEqualToCallableReturn`
-that provide consistent, informative error messages and simplify test validation.
+The `test_writeJobNumba` function shows how to test dynamically generated code,
+which is useful if you're working with the code synthesis features of the package.
 """
 
 from mapFolding import countFolds, getFoldsTotalKnown, oeisIDfor_n
@@ -91,7 +29,7 @@ from mapFolding.oeis import settingsOEIS
 from mapFolding.someAssemblyRequired.RecipeJob import RecipeJobTheorem2Numba
 from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
 from pathlib import Path, PurePosixPath
-from tests.conftest import standardizedEqualToCallableReturn, registrarRecordsTmpObject
+from tests.conftest import registrarRecordsTmpObject, standardizedEqualToCallableReturn
 from typing import Literal
 import importlib.util
 import multiprocessing
@@ -100,20 +38,55 @@ import pytest
 if __name__ == '__main__':
 	multiprocessing.set_start_method('spawn')
 
-# TODO test synthesis
-
 @pytest.mark.parametrize('flow', ['daoOfMapFolding', 'theorem2', 'theorem2Trimmed', 'theorem2numba'])
-def test_flowControl(mapShapeTestCountFolds: tuple[int, ...], flow: Literal['daoOfMapFolding'] | Literal['theorem2'] | Literal['theorem2numba']) -> None:
+def test_flowControl(mapShapeTestCountFolds: tuple[int, ...], flow: Literal['daoOfMapFolding', 'theorem2', 'theorem2numba']) -> None:
+	"""Validate that different computational flows produce identical results.
+
+	This is the primary test for ensuring mathematical consistency across different
+	algorithmic implementations. When adding a new computational approach, include
+	it in the parametrized flow list to verify it produces correct results.
+
+	The test compares the output of each flow against known correct values from
+	OEIS sequences, ensuring that optimization techniques don't compromise accuracy.
+	"""
 	standardizedEqualToCallableReturn(getFoldsTotalKnown(mapShapeTestCountFolds), countFolds, None, None, None, None, mapShapeTestCountFolds, None, None, flow)
 
 def test_aOFn_calculate_value(oeisID: str) -> None:
+	"""Verify OEIS sequence value calculations against known reference values.
+
+	(AI generated docstring)
+
+	Tests the `oeisIDfor_n` function by comparing its calculated output against
+	known correct values from the OEIS database. This ensures that sequence
+	value computations remain mathematically accurate across code changes.
+
+	The test iterates through validation test cases defined in `settingsOEIS`
+	for the given OEIS sequence identifier, verifying that each computed value
+	matches its corresponding known reference value.
+
+	Parameters
+	----------
+	oeisID : str
+		The OEIS sequence identifier to test calculations for.
+
+	"""
 	for n in settingsOEIS[oeisID]['valuesTestValidation']:
 		standardizedEqualToCallableReturn(settingsOEIS[oeisID]['valuesKnown'][n], oeisIDfor_n, oeisID, n)
 
 @pytest.mark.parametrize('pathFilenameTmpTesting', ['.py'], indirect=True)
 def test_writeJobNumba(oneTestCuzTestsOverwritingTests: tuple[int, ...], pathFilenameTmpTesting: Path) -> None:
-	from mapFolding.someAssemblyRequired.toolkitNumba import SpicesJobNumba
-	from mapFolding.someAssemblyRequired.makeJobTheorem2Numba import makeJobNumba
+	"""Test dynamic code generation and execution for computational modules.
+
+	This test validates the package's ability to generate, compile, and execute
+	optimized computational code at runtime. It's essential for users working with
+	the code synthesis features or implementing custom optimization strategies.
+
+	The test creates a complete computational module, executes it, and verifies
+	that the generated code produces mathematically correct results. This pattern
+	can be adapted for testing other dynamically generated computational approaches.
+	"""
+	from mapFolding.someAssemblyRequired.makeJobTheorem2Numba import makeJobNumba  # noqa: PLC0415
+	from mapFolding.someAssemblyRequired.toolkitNumba import SpicesJobNumba  # noqa: PLC0415
 	mapShape = oneTestCuzTestsOverwritingTests
 	state = MapFoldingState(mapShape)
 	state = initializeGroupsOfFolds(state)
@@ -131,12 +104,14 @@ def test_writeJobNumba(oneTestCuzTestsOverwritingTests: tuple[int, ...], pathFil
 
 	Don_Lapre_Road_to_Self_Improvement = importlib.util.spec_from_file_location("__main__", pathFilenameModule)
 	if Don_Lapre_Road_to_Self_Improvement is None:
-		raise ImportError(f"Failed to create module specification from {pathFilenameModule}")
+		msg = f"Failed to create module specification from {pathFilenameModule}"
+		raise ImportError(msg)
 	if Don_Lapre_Road_to_Self_Improvement.loader is None:
-		raise ImportError(f"Failed to get loader for module {pathFilenameModule}")
+		msg = f"Failed to get loader for module {pathFilenameModule}"
+		raise ImportError(msg)
 	module = importlib.util.module_from_spec(Don_Lapre_Road_to_Self_Improvement)
 
 	module.__name__ = "__main__"
 	Don_Lapre_Road_to_Self_Improvement.loader.exec_module(module)
 
-	standardizedEqualToCallableReturn(str(getFoldsTotalKnown(oneTestCuzTestsOverwritingTests)), pathFilenameFoldsTotal.read_text().strip)
+	standardizedEqualToCallableReturn(str(getFoldsTotalKnown(oneTestCuzTestsOverwritingTests)), pathFilenameFoldsTotal.read_text(encoding="utf-8").strip)

tests/test_filesystem.py

@@ -1,5 +1,29 @@
+"""File system operations and path management validation.
+
+This module tests the package's interaction with the file system, ensuring that
+results are correctly saved, paths are properly constructed, and fallback mechanisms
+work when file operations fail. These tests are essential for maintaining data
+integrity during long-running computations.
+
+The file system abstraction allows the package to work consistently across different
+operating systems and storage configurations. These tests verify that abstraction
+works correctly and handles edge cases gracefully.
+
+Key Testing Areas:
+- Filename generation following consistent naming conventions
+- Path construction and directory creation
+- Fallback file creation when primary save operations fail
+- Cross-platform path handling
+
+Most users won't need to modify these tests unless they're changing how the package
+stores computational results or adding new file formats.
+"""
+
 from contextlib import redirect_stdout
-from mapFolding import validateListDimensions, getPathRootJobDEFAULT, getPathFilenameFoldsTotal, saveFoldsTotal, getFilenameFoldsTotal
+from mapFolding import (
+	getFilenameFoldsTotal, getPathFilenameFoldsTotal, getPathRootJobDEFAULT, saveFoldsTotal,
+	validateListDimensions,
+)
 from pathlib import Path
 import io
 import pytest

tests/test_oeis.py

@@ -1,5 +1,34 @@
+"""OEIS (Online Encyclopedia of Integer Sequences) integration testing.
+
+This module validates the package's integration with OEIS, ensuring that sequence
+identification, value retrieval, and caching mechanisms work correctly. The OEIS
+connection provides the mathematical foundation that validates computational results
+against established mathematical knowledge.
+
+These tests verify both the technical aspects of OEIS integration (network requests,
+caching, error handling) and the mathematical correctness of sequence identification
+and value mapping.
+
+Key Testing Areas:
+- OEIS sequence ID validation and normalization
+- Network request handling and error recovery
+- Local caching of sequence data for offline operation
+- Command-line interface for OEIS sequence queries
+- Mathematical consistency between local computations and OEIS values
+
+The caching tests are particularly important for users working in environments with
+limited network access, as they ensure the package can operate effectively offline
+once sequence data has been retrieved.
+
+Network error handling tests verify graceful degradation when OEIS is unavailable,
+which is crucial for maintaining package reliability in production environments.
+"""
+
 from contextlib import redirect_stdout
-from mapFolding.oeis import oeisIDfor_n, getOEISids, clearOEIScache, getOEISidValues, OEIS_for_n, oeisIDsImplemented, settingsOEIS, validateOEISid
+from mapFolding.oeis import (
+	clearOEIScache, getOEISids, getOEISidValues, OEIS_for_n, oeisIDfor_n, oeisIDsImplemented,
+	settingsOEIS, validateOEISid,
+)
 from pathlib import Path
 from tests.conftest import standardizedEqualToCallableReturn, standardizedSystemExit
 from typing import Any, NoReturn
@@ -58,13 +87,14 @@ def test_clearOEIScache(mock_unlink: unittest.mock.MagicMock, mock_exists: unitt
 		mock_exists.assert_called_once()
 		mock_unlink.assert_not_called()
 
-def testNetworkError(monkeypatch: pytest.MonkeyPatch, pathCacheTesting: Path) -> None:
-	"""Test network error handling."""
-	def mockUrlopen(*args: Any, **kwargs: Any) -> NoReturn:
-		raise URLError("Network error")
+# Monkey tests
+# def testNetworkError(monkeypatch: pytest.MonkeyPatch, pathCacheTesting: Path) -> None:
+# 	"""Test network error handling."""
+# 	def mockUrlopen(*args: Any, **kwargs: Any) -> NoReturn:
+# 		raise URLError("Network error")
 
-	monkeypatch.setattr(urllib.request, 'urlopen', mockUrlopen)
-	standardizedEqualToCallableReturn(URLError, getOEISidValues, next(iter(settingsOEIS)))
+# 	monkeypatch.setattr(urllib.request, 'urlopen', mockUrlopen)
+# 	standardizedEqualToCallableReturn(URLError, getOEISidValues, next(iter(settingsOEIS)))
 
 # ===== Command Line Interface Tests =====
 def testHelpText() -> None:

tests/test_other.py

@@ -1,9 +1,36 @@
+"""Foundational utilities and data validation testing.
+
+This module tests the core utility functions that support the mathematical
+computations but aren't specific to any particular algorithm. These are the
+building blocks that ensure data integrity and proper parameter handling
+throughout the package.
+
+The tests here validate fundamental operations like dimension validation,
+processor limit configuration, and basic mathematical utilities. These
+functions form the foundation that other modules build upon.
+
+Key Testing Areas:
+- Input validation and sanitization for map dimensions
+- Processor limit configuration for parallel computations
+- Mathematical utility functions from helper modules
+- Edge case handling for boundary conditions
+- Type system validation and error propagation
+
+For users extending the package: these tests demonstrate proper input validation
+patterns and show how to handle edge cases gracefully. The parametrized tests
+provide examples of comprehensive boundary testing that you can adapt for your
+own functions.
+
+The integration with external utility modules (hunterMakesPy) shows how to test
+dependencies while maintaining clear separation of concerns.
+"""
+
 from collections.abc import Callable
+from hunterMakesPy import intInnit
+from hunterMakesPy.pytestForYourUse import PytestFor_intInnit, PytestFor_oopsieKwargsie
 from mapFolding import getLeavesTotal, setProcessorLimit, validateListDimensions
 from tests.conftest import standardizedEqualToCallableReturn
 from typing import Any, Literal
-from Z0Z_tools import intInnit
-from Z0Z_tools.pytestForYourUse import PytestFor_intInnit, PytestFor_oopsieKwargsie
 import multiprocessing
 import numba
 import pytest

tests/test_tasks.py

@@ -1,8 +1,36 @@
+"""Parallel processing and task distribution validation.
+
+This module tests the package's parallel processing capabilities, ensuring that
+computations can be effectively distributed across multiple processors while
+maintaining mathematical accuracy. These tests are crucial for performance
+optimization and scalability.
+
+The task distribution system allows large computational problems to be broken
+down into smaller chunks that can be processed concurrently. These tests verify
+that the distribution logic works correctly and that results remain consistent
+regardless of how the work is divided.
+
+Key Testing Areas:
+- Task division strategies for different computational approaches
+- Processor limit configuration and enforcement
+- Parallel execution consistency and correctness
+- Resource management and concurrency control
+- Error handling in multi-process environments
+
+For users working with large-scale computations: these tests demonstrate how to
+configure and validate parallel processing setups. The concurrency limit tests
+show how to balance performance with system resource constraints.
+
+The multiprocessing configuration (spawn method) is essential for cross-platform
+compatibility and proper resource isolation between test processes.
+"""
+
 from collections.abc import Callable
-from mapFolding import countFolds, getTaskDivisions, setProcessorLimit, validateListDimensions, getLeavesTotal, getFoldsTotalKnown
+from hunterMakesPy.pytestForYourUse import PytestFor_defineConcurrencyLimit
+from mapFolding import (
+	countFolds, getFoldsTotalKnown, getLeavesTotal, getTaskDivisions, setProcessorLimit, validateListDimensions)
 from tests.conftest import standardizedEqualToCallableReturn
 from typing import Literal
-from Z0Z_tools.pytestForYourUse import PytestFor_defineConcurrencyLimit
 import multiprocessing
 import pytest
 

mapFolding/datatypes.py

@@ -1,18 +0,0 @@
-from numpy import dtype, uint8 as numpy_uint8, uint16 as numpy_uint16, uint64 as numpy_uint64, integer, ndarray
-from typing import Any, TypeAlias, TypeVar
-
-NumPyIntegerType = TypeVar('NumPyIntegerType', bound=integer[Any], covariant=True)
-
-DatatypeLeavesTotal: TypeAlias = int
-NumPyLeavesTotal: TypeAlias = numpy_uint8
-
-DatatypeElephino: TypeAlias = int
-NumPyElephino: TypeAlias = numpy_uint16
-
-DatatypeFoldsTotal: TypeAlias = int
-NumPyFoldsTotal: TypeAlias = numpy_uint64
-
-Array3D: TypeAlias = ndarray[tuple[int, int, int], dtype[NumPyLeavesTotal]]
-Array1DLeavesTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyLeavesTotal]]
-Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[NumPyElephino]]
-Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyFoldsTotal]]