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

mapfolding-0.12.3.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: mapFolding
+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
+Project-URL: Homepage, https://github.com/hunterhogan/mapFolding
+Project-URL: Issues, https://github.com/hunterhogan/mapFolding/issues
+Project-URL: Repository, https://github.com/hunterhogan/mapFolding.git
+Keywords: A000136,A001415,A001416,A001417,A001418,A195646,AST manipulation,Numba optimization,OEIS,algorithmic optimization,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,performance optimization,source code analysis,stamp folding
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: astToolkit>=0.5.0
+Requires-Dist: hunterMakesPy
+Requires-Dist: numba
+Requires-Dist: numba_progress
+Requires-Dist: numpy
+Requires-Dist: platformdirs
+Provides-Extra: development
+Requires-Dist: mypy; extra == "development"
+Requires-Dist: pyupgrade; extra == "development"
+Requires-Dist: setuptools-scm; extra == "development"
+Provides-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"
+Dynamic: license-file
+
+# mapFolding
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+[![License: CC-BY-NC-4.0](https://img.shields.io/badge/License-CC_BY--NC_4.0-3b434b)](https://creativecommons.org/licenses/by-nc/4.0/)
+
+A computational framework that starts with Lunnon's 1971 algorithm for counting distinct ways to fold maps and improves it. Plus there is a comprehensive AST transformation system for transforming algorithms for optimization and research.
+
+(Yo, the rest is AI generated and I don't have the energy to proofread it. This package helped me compute two previously unknown values: I'm sure others can improve it.)
+
+## The Mathematical Problem
+
+Map folding is a combinatorial problem: given a rectangular grid of unit squares, how many distinct ways can you fold it? "Distinct" means that foldings producing identical final shapes are counted as one. This problem connects to combinatorial geometry, integer sequences, and computational complexity theory.
+
+The calculations extend the Online Encyclopedia of Integer Sequences (OEIS):
+
+- **A001415**: 2×n strips (computed through n=20 for the first time)
+- **A001418**: n×n squares
+- **A001416**: 3×n strips
+- **A001417**: n-dimensional hypercubes
+- **A195646**: 3×3×...×3 hypercubes
+
+```python
+from mapFolding import oeisIDfor_n
+
+# How many ways can you fold a 2×4 strip?
+foldsTotal = oeisIDfor_n('A001415', 4)
+```
+
+## The Computational Challenge
+
+For larger maps, these calculations require hours or days to complete. A 2×20 strip requires processing leaves through billions of recursive operations. The package addresses this through systematic algorithm transformation: converting readable Python implementations into specialized, Numba-optimized modules that achieve order-of-magnitude performance improvements.
+
+## What This Package Provides
+
+### Core Functionality
+
+- **Complete implementation** of Lunnon's recursive algorithm
+- **Mathematical validation** through OEIS integration and caching
+- **Type-safe computational state** management with automatic initialization
+- **Result persistence** for long-running calculations
+
+### Algorithm Transformation System
+
+- **AST manipulation framework** for converting dataclass-based algorithms to optimized implementations
+- **Automatic code generation** that produces standalone, highly optimized computation modules
+- **Dataclass decomposition** to enable Numba compatibility while preserving readable source code
+- **Comprehensive optimization** including dead code elimination, static value embedding, and aggressive compilation settings
+
+### Educational Resources
+
+- **Historical implementations** showing algorithm evolution from 1971 to present
+- **Performance comparison** studies demonstrating optimization techniques
+- **Complete test suite** with patterns for validating custom implementations
+- **Reference documentation** for extending the transformation framework
+
+## Use Cases
+
+**Mathematical Research**: Explore folding pattern properties, extend known sequences, or validate theoretical results against computed values.
+
+**Algorithm Optimization Learning**: Study a complete transformation pipeline that converts high-level algorithms into production-ready optimized code.
+
+**Performance Computing Education**: Examine techniques for achieving maximum Python performance through Numba integration, AST manipulation, and specialized code generation.
+
+**Combinatorial Problem Solving**: Use the framework as a template for optimizing other recursive combinatorial algorithms.
+
+## Example Usage
+
+```python
+from mapFolding import countFolds
+
+# Count folding patterns for a 3×3 square
+result = countFolds([3, 3])
+
+# Access OEIS sequences directly
+from mapFolding import oeisIDfor_n
+strip_foldings = oeisIDfor_n('A001415', 6)  # 2×6 strip
+
+# Generate optimized code for specific dimensions
+from mapFolding.someAssemblyRequired import makeJobTheorem2Numba
+# Creates specialized modules for maximum performance
+```
+
+## Repository Structure
+
+- `mapFolding/`: Core implementation with modular architecture
+- `reference/`: Historical algorithm implementations and performance studies
+- `someAssemblyRequired/`: AST transformation framework
+- `tests/`: Comprehensive validation suite
+- `jobs/`: Generated optimized modules for specific calculations
+
+## Performance Characteristics
+
+- **Pure Python baseline**: Educational implementations for understanding
+- **NumPy optimization**: ~10× improvement through vectorized operations
+- **Numba compilation**: ~100× improvement through native code generation
+- **Specialized modules**: ~1000× improvement through static optimization and embedded constants
+
+Actual performance varies by map dimensions and available hardware.
+
+## My recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+## How to code
+
+Coding One Step at a Time:
+
+0. WRITE CODE.
+1. Don't write stupid code that's hard to revise.
+2. Write good code.
+3. When revising, write better code.
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

mapfolding-0.12.3.dist-info/RECORD

@@ -0,0 +1,53 @@
+mapFolding/__init__.py,sha256=dl3HR2zoipFo0UstEJn3iWTkXlA_XeCQw_zfw2fk4qE,3643
+mapFolding/_theSSOT.py,sha256=dloMAsIOhUnIE7-SFJbQYyl6IYo7CdCAyBZPqMuckko,3380
+mapFolding/_theTypes.py,sha256=rT8UTm-I_haMQlUGaJ4yvqIMt6FUOvWH-VUYNud6UN4,5495
+mapFolding/basecamp.py,sha256=VuX0hLrXkY-XEcV9trd4aSdzxTfUNMR6kTnYo8-6tJw,9474
+mapFolding/beDRY.py,sha256=Iikg3U4zQjx6JOKL62R7Tb0CpOm3JkPSIewAByco9GA,14777
+mapFolding/daoOfMapFolding.py,sha256=ncTIiBfTsM8SNVx9qefZ0bBcBtviWLSk4iPv3Z9nGiE,5442
+mapFolding/dataBaskets.py,sha256=ch-8jVvZ57nJ52pB8N_u3Egz-56IfA2t8Ct0ba7SXOY,14252
+mapFolding/filesystemToolkit.py,sha256=Ex5tyugRQurXIgUNVtkQYfWMq8fM4e-izX01MBXU5_8,11006
+mapFolding/oeis.py,sha256=zw_Aua57-VAXbtS0soG_xfBR1PozmsYLQCoy_Vq5WAU,23026
+mapFolding/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mapFolding/reference/__init__.py,sha256=GKcSgYE49NcTISx-JZbELXyq-eRkMeTL5g4DXInWFw0,2206
+mapFolding/reference/flattened.py,sha256=0eHgLFIeIeVUsI5zF5oSy5iWYrjOMzxr7KjDxiTe01k,16078
+mapFolding/reference/hunterNumba.py,sha256=iLfyqwGdAh6c5GbapnKsWhAsNsR3O-fyGGHAdohluLw,7258
+mapFolding/reference/irvineJavaPort.py,sha256=UEfIX4QbPLl5jnyfYIyX5YRR3_rYvPUikK8jLehsFko,4076
+mapFolding/reference/jaxCount.py,sha256=TuDNKOnyhQfuixKmIxO9Algv7dvy7KMGhgsV3h96FGE,14853
+mapFolding/reference/lunnonNumpy.py,sha256=mMgrgbrBpe4nmo72ThEI-MGH0OwEHmfMPczSXHp2qKo,4357
+mapFolding/reference/lunnonWhile.py,sha256=ZL8GAQtPs5nJZSgoDl5USrLSS_zs03y98y1Z9E4jOmQ,3799
+mapFolding/reference/rotatedEntryPoint.py,sha256=5ughpKUT2JQhoAKgoDUdYNjgWQYPGV8v-7dWEAdDmfE,10274
+mapFolding/reference/total_countPlus1vsPlusN.py,sha256=yJZAVLVdoXqHag2_N6_6CT-Q6HXBgRro-eny93-Rlpw,9307
+mapFolding/reference/jobsCompleted/__init__.py,sha256=TU93ZGUW1xEkT6d9mQFn_rp5DvRy0ZslEB2Q6MF5ZDc,2596
+mapFolding/reference/jobsCompleted/[2x19]/p2x19.py,sha256=_tvYtfzMWVo2VtUbIAieoscb4N8FFflgTdW4-ljBUuA,19626
+mapFolding/reference/jobsCompleted/p2x19/p2x19.py,sha256=eZEw4Me4ocTt6VXoK2-Sbd5SowZtxRIbN9dZmc7OCVg,6395
+mapFolding/someAssemblyRequired/RecipeJob.py,sha256=Gi8H1z68rtl2PQShMb6D1JFug9S_edFxipWUuc0K1EQ,10949
+mapFolding/someAssemblyRequired/__init__.py,sha256=UNDh6O86jT5ywlw9LgeWsUHwOfNvoMJRDAzYXbwCbeM,5779
+mapFolding/someAssemblyRequired/_toolIfThis.py,sha256=VDZC10Xo3E1Y5n6FmaBBbOBR-rinV9DFkpgw8zrDyzg,6339
+mapFolding/someAssemblyRequired/_toolkitContainers.py,sha256=ymqEWH5oO_gNjvRjpRELCzahXfU74fhHZspnv6GGLiE,13680
+mapFolding/someAssemblyRequired/getLLVMforNoReason.py,sha256=tY0-2K0BFkwLAAjSrFJLPoG8CevDHOFc3OH3TxXANzg,2806
+mapFolding/someAssemblyRequired/infoBooth.py,sha256=GWiqnHbqk7te_pvVuk4G_gbFa_W2aeSx19w4pakvqfM,2300
+mapFolding/someAssemblyRequired/makeAllModules.py,sha256=E5d1YoP8wOGBCknyjR9uDx2xxHEp18UAjDPxIf6PeKg,44351
+mapFolding/someAssemblyRequired/makeJobTheorem2Numba.py,sha256=T3xopmCckvDJqdbEXL7IzQLYmfulp0EO5-kdpyjxWZs,19027
+mapFolding/someAssemblyRequired/toolkitNumba.py,sha256=UNLFadfRl6sHCHVEGbCu4sCPpnLKVqMd1U5ULWcEyis,14855
+mapFolding/someAssemblyRequired/transformationTools.py,sha256=nPGZsvb5GquaCCxdDh_XzNIZYSiVJpWKd7wfhfRvxnk,11512
+mapFolding/syntheticModules/__init__.py,sha256=evVFqhCGa-WZKDiLcnQWjs-Bj34eRnfSLqz_d7dFYZY,83
+mapFolding/syntheticModules/countParallel.py,sha256=OK_IB9w4yy9MMAiGvkei5ezPm_00v2nYjPrQZ_IlELg,7733
+mapFolding/syntheticModules/daoOfMapFolding.py,sha256=cfWPABtXyCxJ0BwPI7rhfLh_2UYV_XKAL8lJ4GLNXaQ,5896
+mapFolding/syntheticModules/dataPacking.py,sha256=m_eOZ7sMXIQ9jY5EvC3qgitQTY60n6rksy0ACMJOIC8,2292
+mapFolding/syntheticModules/initializeCount.py,sha256=nWSlJMMfIM3DvZxMn6ISQusUJqRYAjKQyLF5hwLEdBQ,3119
+mapFolding/syntheticModules/theorem2.py,sha256=9jrbZNNX4BWYZW1S0JjvRY2k7RU7I1RNUMV7JdCt1ZY,3017
+mapFolding/syntheticModules/theorem2Numba.py,sha256=-cKjNyxgUMFhEyFVs0VJ7hw4LfrV0WSNK5tPYbQ1oNU,3369
+mapFolding/syntheticModules/theorem2Trimmed.py,sha256=DHW3NxBdtABQYBKm2WRvfQ5kzc2_UwGI2h4ePuYEJoM,2685
+mapfolding-0.12.3.dist-info/licenses/LICENSE,sha256=NxH5Y8BdC-gNU-WSMwim3uMbID2iNDXJz7fHtuTdXhk,19346
+tests/__init__.py,sha256=5RdiZYAl8nPIM1sxB_D0CsN6J8173LOZ0hpR3geTHAU,1312
+tests/conftest.py,sha256=eBo0IIm98402hl_XW5nT06cUvW25ciItv1_zZdM152E,11126
+tests/test_computations.py,sha256=9We4l3JcyQy-LGHdCIL2fP_v6mXfdnPcD7YIp5C9Um8,5845
+tests/test_filesystem.py,sha256=IXTeyfifXe6vLizCo8BiSn5Yx9DEKYEc_hoJRKhQFNk,3899
+tests/test_oeis.py,sha256=CA0f8vHDwm_pLX4SMQN3_hTfy6elU2Hgm0d-jrxFoqE,6299
+tests/test_other.py,sha256=ELIMRO8NbuQzzleVRN4zhC1bWYK3KTzFQhS_GOKrnnk,4945
+tests/test_tasks.py,sha256=g80zHTjpv8zb5ptIIbJro9aY4McMn0gYMXj00MqY7vw,4042
+mapfolding-0.12.3.dist-info/METADATA,sha256=nZn2rzN0f5NDTIg_tS6Sb5cWS5wLfpuW5gjWIxLuANg,7884
+mapfolding-0.12.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mapfolding-0.12.3.dist-info/entry_points.txt,sha256=F3OUeZR1XDTpoH7k3wXuRb3KF_kXTTeYhu5AGK1SiOQ,146
+mapfolding-0.12.3.dist-info/top_level.txt,sha256=1gP2vFaqPwHujGwb3UjtMlLEGN-943VSYFR7V4gDqW8,17
+mapfolding-0.12.3.dist-info/RECORD,,

{mapfolding-0.12.1.dist-info → mapfolding-0.12.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.7.1)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

tests/__init__.py

@@ -1,44 +1,28 @@
-"""
-Map Folding Test Suite and Validation Framework
-
-This test suite provides comprehensive testing capabilities for the mapFolding package
-and its optimization framework. It is specifically designed to enable both package
-maintenance and custom extension testing, making it easy for users to validate their
-own recipe configurations and job implementations.
-
-## Key Testing Capabilities
-
-1. **Algorithm Validation**
-   - Tests core algorithm correctness against known OEIS sequence values
-   - Validates both sequential and parallel execution paths
-   - Ensures consistency across different implementation strategies
-
-2. **Code Generation Testing**
-   - Tests the AST transformation assembly line from source to optimized implementations
-   - Validates that generated Numba-accelerated modules produce correct results
-   - Ensures robust code generation across different parameter sets
-
-3. **Job-Specific Testing**
-   - Tests specialized job module generation for specific map shapes
-   - Validates execution of the generated modules
-   - Verifies correct output file creation and value storage
-
-## Testing Your Own Implementations
-
-This suite is designed to make it easy to test your custom recipes and jobs:
-
-### For Custom Recipes (RecipeSynthesizeFlow):
-Copy and adapt the `syntheticDispatcherFixture` and associated tests from
-`test_computations.py` to validate your customized code transformation assembly lines.
-
-### For Custom Jobs (RecipeJob):
-Copy and adapt the `test_writeJobNumba` function to test specialized job modules
-for specific map shapes with your custom configurations.
-
-The entire test infrastructure is built on fixtures and utilities that handle
-complex setup and validation, allowing you to focus on your implementation details
-while leveraging the existing validation framework.
-
-See the module docstrings in `test_computations.py` and `conftest.py` for detailed
-guidance on adapting these tests for your own purposes.
-"""
+"""Test suite for the mapFolding package.
+
+This test suite provides comprehensive validation of map folding computations,
+file system operations, OEIS integration, task division, and foundational
+utilities. The tests are designed to support multiple audiences and use cases.
+
+Test Module Organization:
+- conftest.py: Testing infrastructure and shared fixtures
+- test_computations.py: Core mathematical validation and algorithm testing
+- test_filesystem.py: File operations and path management
+- test_oeis.py: OEIS sequence integration and caching
+- test_other.py: Foundational utilities and data validation
+- test_tasks.py: Task division and work distribution
+
+For Contributors:
+The test suite follows Domain-Driven Design principles, organizing tests around
+mathematical concepts rather than implementation details. Use the existing
+patterns as templates when adding new functionality.
+
+For Users Adding Custom Modules:
+The test_computations.py module provides the most relevant examples for testing
+custom computational approaches. The standardized testing functions in conftest.py
+ensure consistent error reporting across all tests.
+
+For AI Assistants:
+The testing framework emphasizes readable, predictable patterns that maintain
+mathematical correctness while supporting code evolution and optimization.
+"""

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: