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

tests/conftest.py

@@ -1,62 +1,30 @@
-"""
-Test Configuration and Shared Fixtures
-
-This module provides the foundation for the mapFolding test suite, offering fixtures and
-utilities that enable consistent, reliable testing across the package. It's particularly
-valuable for users who want to test their own customizations.
-
-## Key Testing Facilities
-
-### File System Management
-
-The module implements a robust temporary file system management approach:
-- Creates a registry of temporary files and directories
-- Ensures proper cleanup after tests
-- Provides fixtures that automatically handle cleanup
-
-### Test-Specific Fixtures
-
-Several fixtures enable specialized testing scenarios:
-
-1. **Dispatcher Fixtures**:
-   - `useThisDispatcher`: Core fixture for patching the algorithm dispatcher
-   - `useAlgorithmSourceDispatcher`: Tests with the source algorithm implementation
-   - `syntheticDispatcherFixture`: Tests with generated Numba-optimized implementation
-
-2. **Test Data Fixtures**:
-   - `oeisID`, `oeisID_1random`: Provide OEIS sequence identifiers for testing
-   - `listDimensionsTestCountFolds`: Provides dimensions suitable for algorithm testing
-   - `listDimensionsTestParallelization`: Provides dimensions suitable for parallel testing
-   - `mapShapeTestFunctionality`: Provides map shapes suitable for functional testing
-
-3. **Path Fixtures**:
-   - `pathTmpTesting`: Creates a temporary directory for test-specific files
-   - `pathFilenameTmpTesting`: Creates a temporary file with appropriate extension
-   - `pathCacheTesting`: Creates a temporary OEIS cache directory
-
-### Standardized Test Utilities
-
-The module provides utilities that create consistent test outputs:
-
-- `standardizedEqualToCallableReturn`: Core utility that handles testing function return values
-  or exceptions with uniform error messages
-- `standardizedSystemExit`: Tests code that should exit the program with specific status codes
-- `uniformTestMessage`: Creates consistent error messages for test failures
-
-## Using These Fixtures for Custom Tests
-
-The most important fixtures for testing custom implementations are:
-
-1. `syntheticDispatcherFixture`: Creates and patches a Numba-optimized module from a recipe
-2. `pathTmpTesting`: Provides a clean temporary directory for test files
-3. `standardizedEqualToCallableReturn`: Simplifies test assertions with clear error messages
-
-These can be adapted by copying and modifying them to test custom recipes and jobs.
-See the examples in `test_computations.py` for guidance on adapting these fixtures.
+"""Test framework infrastructure and shared fixtures for mapFolding.
+
+This module serves as the foundation for the entire test suite, providing standardized
+fixtures, temporary file management, and testing utilities. It implements the Single
+Source of Truth principle for test configuration and establishes consistent patterns
+that make the codebase easier to extend and maintain.
+
+The testing framework is designed for multiple audiences:
+- Contributors who need to understand the test patterns
+- AI assistants that help maintain or extend the codebase
+- Users who want to test custom modules they create
+- Future maintainers who need to debug or modify tests
+
+Key Components:
+- Temporary file management with automatic cleanup
+- Standardized assertion functions with uniform error messages
+- Test data generation from OEIS sequences for reproducible results
+- Mock objects for external dependencies and timing-sensitive operations
+
+The module follows Domain-Driven Design principles, organizing test concerns around
+the mathematical concepts of map folding rather than technical implementation details.
+This makes tests more meaningful and easier to understand in the context of the
+research domain.
 """
 
 from collections.abc import Callable, Generator, Sequence
-from mapFolding import getLeavesTotal, validateListDimensions, makeDataContainer
+from mapFolding import getLeavesTotal, makeDataContainer, validateListDimensions
 from mapFolding.oeis import oeisIDsImplemented, settingsOEIS
 from pathlib import Path
 from typing import Any
@@ -68,7 +36,7 @@ import unittest.mock
 import uuid
 
 # SSOT for test data paths and filenames
-pathDataSamples = Path("tests/dataSamples").absolute()
+pathDataSamples: Path = Path("tests/dataSamples").absolute()
 pathTmpRoot: Path = pathDataSamples / "tmp"
 pathTmpRoot.mkdir(parents=True, exist_ok=True)
 
@@ -102,7 +70,7 @@ def setupTeardownTmpObjects() -> Generator[None, None, None]:
 @pytest.fixture
 def pathTmpTesting(request: pytest.FixtureRequest) -> Path:
 	# "Z0Z_" ensures the directory name does not start with a number, which would make it an invalid Python identifier
-	pathTmp = pathTmpRoot / ("Z0Z_" + str(uuid.uuid4().hex))
+	pathTmp: Path = pathTmpRoot / ("Z0Z_" + str(uuid.uuid4().hex))
 	pathTmp.mkdir(parents=True, exist_ok=False)
 
 	registrarRecordsTmpObject(pathTmp)
@@ -153,7 +121,15 @@ def setupWarningsAsErrors() -> Generator[None, Any, None]:
 @pytest.fixture
 def oneTestCuzTestsOverwritingTests(oeisID_1random: str) -> tuple[int, ...]:
 	"""For each `oeisID_1random` from the `pytest.fixture`, returns `listDimensions` from `valuesTestValidation`
-	if `validateListDimensions` approves. Each `listDimensions` is suitable for testing counts."""
+	if `validateListDimensions` approves. Each `listDimensions` is suitable for testing counts.
+
+	This fixture provides a single test case to avoid issues with tests that write to the same
+	output files. It's particularly useful when testing code generation or file output functions
+	where multiple concurrent tests could interfere with each other.
+
+	The returned map shape is guaranteed to be computationally feasible for testing purposes,
+	avoiding cases that would take excessive time to complete during test runs.
+	"""
 	while True:
 		n = random.choice(settingsOEIS[oeisID_1random]['valuesTestValidation'])
 		if n < 2:
@@ -235,13 +211,42 @@ def oeisID_1random() -> str:
 	return random.choice(oeisIDsImplemented)
 
 def uniformTestMessage(expected: Any, actual: Any, functionName: str, *arguments: Any) -> str:
-	"""Format assertion message for any test comparison."""
+	"""Format assertion message for any test comparison.
+
+	Creates standardized, machine-parsable error messages that clearly display
+	what was expected versus what was received. This uniform formatting makes
+	test failures easier to debug and maintains consistency across the entire
+	test suite.
+
+	Parameters
+		expected: The value or exception type that was expected
+		actual: The value or exception type that was actually received
+		functionName: Name of the function being tested
+		arguments: Arguments that were passed to the function
+
+	Returns
+		formattedMessage: A formatted string showing the test context and comparison
+	"""
 	return (f"\nTesting: `{functionName}({', '.join(str(parameter) for parameter in arguments)})`\n"
 			f"Expected: {expected}\n"
 			f"Got: {actual}")
 
 def standardizedEqualToCallableReturn(expected: Any, functionTarget: Callable[..., Any], *arguments: Any) -> None:
-	"""Use with callables that produce a return or an error."""
+	"""Use with callables that produce a return or an error.
+
+	This is the primary testing function for validating both successful returns
+	and expected exceptions. It provides consistent error messaging and handles
+	the comparison logic that most tests in the suite rely on.
+
+	When testing a function that should raise an exception, pass the exception
+	type as the `expected` parameter. For successful returns, pass the expected
+	return value.
+
+	Parameters
+		expected: Expected return value or exception type
+		functionTarget: The function to test
+		arguments: Arguments to pass to the function
+	"""
 	if type(expected) is type[Exception]:
 		messageExpected = expected.__name__
 	else:

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)
+"""Core computational verification and algorithm validation tests.
 
-    # Import and patch the dispatcher
-    # ... (similar to syntheticDispatcherFixture)
+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.
 
-    return customDispatcher
+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.
 
-def test_myCustomRecipeParallel(myCustomRecipeFixture, listDimensionsTestParallelization):
-    # Test with the standardized validation utility
-    standardizedEqualToCallableReturn(
-        getFoldsTotalKnown(tuple(listDimensionsTestParallelization)),
-        countFolds,
-        listDimensionsTestParallelization,
-        None,
-        'maximum'
-    )
-```
+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
 
-### Testing Custom Jobs (RecipeJob):
+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.
 
-1. Copy and adapt `test_writeJobNumba`
-2. Modify it to use your custom job configuration
-
-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
@@ -104,6 +42,15 @@ if __name__ == '__main__':
 
 @pytest.mark.parametrize('flow', ['daoOfMapFolding', 'theorem2', 'theorem2Trimmed', 'theorem2numba'])
 def test_flowControl(mapShapeTestCountFolds: tuple[int, ...], flow: Literal['daoOfMapFolding'] | Literal['theorem2'] | Literal['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:
@@ -112,8 +59,18 @@ def test_aOFn_calculate_value(oeisID: str) -> None:
 
 @pytest.mark.parametrize('pathFilenameTmpTesting', ['.py'], indirect=True)
 def test_writeJobNumba(oneTestCuzTestsOverwritingTests: tuple[int, ...], pathFilenameTmpTesting: Path) -> None:
-	from mapFolding.someAssemblyRequired.toolkitNumba import SpicesJobNumba
+	"""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
+	from mapFolding.someAssemblyRequired.toolkitNumba import SpicesJobNumba
 	mapShape = oneTestCuzTestsOverwritingTests
 	state = MapFoldingState(mapShape)
 	state = initializeGroupsOfFolds(state)

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

tests/test_other.py

@@ -1,3 +1,30 @@
+"""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 (Z0Z_tools) shows how to test
+dependencies while maintaining clear separation of concerns.
+"""
+
 from collections.abc import Callable
 from mapFolding import getLeavesTotal, setProcessorLimit, validateListDimensions
 from tests.conftest import standardizedEqualToCallableReturn

tests/test_tasks.py

@@ -1,5 +1,35 @@
+"""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 mapFolding import (
+	countFolds, getFoldsTotalKnown, getLeavesTotal, getTaskDivisions, setProcessorLimit,
+	validateListDimensions,
+)
 from tests.conftest import standardizedEqualToCallableReturn
 from typing import Literal
 from Z0Z_tools.pytestForYourUse import PytestFor_defineConcurrencyLimit