mapFolding 0.3.7__py3-none-any.whl → 0.3.9__py3-none-any.whl

tests/conftest.py

@@ -0,0 +1,224 @@
+"""SSOT for Pytest"""
+
+# TODO learn how to run tests and coverage analysis without `env = ["NUMBA_DISABLE_JIT=1"]`
+
+from tests.conftest_tmpRegistry import (
+    pathCacheTesting,
+    pathDataSamples,
+    pathFilenameFoldsTotalTesting,
+    pathTempTesting,
+    setupTeardownTestData,
+)
+from tests.conftest_uniformTests import (
+    uniformTestMessage,
+    standardizedEqualTo,
+    standardizedSystemExit,
+)
+from mapFolding import *
+from mapFolding import basecamp
+from mapFolding import getAlgorithmCallable, getDispatcherCallable
+from mapFolding.beDRY import *
+from mapFolding.oeis import _getFilenameOEISbFile, _getOEISidValues
+from mapFolding.oeis import *
+from Z0Z_tools.pytestForYourUse import PytestFor_defineConcurrencyLimit, PytestFor_intInnit, PytestFor_oopsieKwargsie
+from typing import Any, Callable, ContextManager, Dict, Generator, List, Optional, Sequence, Set, Tuple, Type, Union
+import pathlib
+import pytest
+import random
+import unittest.mock
+
+def makeDictionaryFoldsTotalKnown() -> Dict[Tuple[int,...], int]:
+    """Returns a dictionary mapping dimension tuples to their known folding totals."""
+    dictionaryMapDimensionsToFoldsTotalKnown: Dict[Tuple[int, ...], int] = {}
+
+    for settings in settingsOEIS.values():
+        sequence = settings['valuesKnown']
+
+        for n, foldingsTotal in sequence.items():
+            dimensions = settings['getMapShape'](n)
+            dimensions.sort()
+            dictionaryMapDimensionsToFoldsTotalKnown[tuple(dimensions)] = foldingsTotal
+
+    # Are we in a place that has jobs?
+    pathJobDEFAULT = getPathJobDEFAULT()
+    if pathJobDEFAULT.exists():
+        # Are there foldsTotal files?
+        for pathFilenameFoldsTotal in pathJobDEFAULT.rglob('*.foldsTotal'):
+            if pathFilenameFoldsTotal.is_file():
+                try:
+                    listDimensions = eval(pathFilenameFoldsTotal.stem)
+                except Exception:
+                    continue
+                # Are the dimensions in the dictionary?
+                if isinstance(listDimensions, list) and all(isinstance(dimension, int) for dimension in listDimensions):
+                    listDimensions.sort()
+                    if tuple(listDimensions) in dictionaryMapDimensionsToFoldsTotalKnown:
+                        continue
+                    # Are the contents a reasonably large integer?
+                    try:
+                        foldsTotal = pathFilenameFoldsTotal.read_text()
+                    except Exception:
+                        continue
+                    # Why did I sincerely believe this would only be three lines of code?
+                    if foldsTotal.isdigit():
+                        foldsTotalInteger = int(foldsTotal)
+                        if foldsTotalInteger > 85109616 * 10**3:
+                            # You made it this far, so fuck it: put it in the dictionary
+                            dictionaryMapDimensionsToFoldsTotalKnown[tuple(listDimensions)] = foldsTotalInteger
+                        dictionaryMapDimensionsToFoldsTotalKnown[tuple(listDimensions)] = foldsTotalInteger
+                    # The sunk-costs fallacy claims another victim!
+
+    return dictionaryMapDimensionsToFoldsTotalKnown
+
+"""
+Section: Fixtures"""
+
+@pytest.fixture(autouse=True)
+def setupWarningsAsErrors() -> Generator[None, Any, None]:
+    """Convert all warnings to errors for all tests."""
+    import warnings
+    warnings.filterwarnings("error")
+    yield
+    warnings.resetwarnings()
+
+@pytest.fixture
+def foldsTotalKnown() -> Dict[Tuple[int,...], int]:
+    """Returns a dictionary mapping dimension tuples to their known folding totals.
+    NOTE I am not convinced this is the best way to do this.
+    Advantage: I call `makeDictionaryFoldsTotalKnown()` from modules other than test modules.
+    Preference: I _think_ I would prefer a SSOT function available to any module
+    similar to `foldsTotalKnown = getFoldsTotalKnown(listDimensions)`."""
+    return makeDictionaryFoldsTotalKnown()
+
+@pytest.fixture
+def listDimensionsTestCountFolds(oeisID: str) -> List[int]:
+    """For each `oeisID` from the `pytest.fixture`, returns `listDimensions` from `valuesTestValidation`
+    if `validateListDimensions` approves. Each `listDimensions` is suitable for testing counts."""
+    while True:
+        n = random.choice(settingsOEIS[oeisID]['valuesTestValidation'])
+        if n < 2:
+            continue
+        listDimensionsCandidate = settingsOEIS[oeisID]['getMapShape'](n)
+
+        try:
+            return validateListDimensions(listDimensionsCandidate)
+        except (ValueError, NotImplementedError):
+            pass
+
+@pytest.fixture
+def listDimensionsTestFunctionality(oeisID_1random: str) -> List[int]:
+    """To test functionality, get one `listDimensions` from `valuesTestValidation` if
+    `validateListDimensions` approves. The algorithm can count the folds of the returned
+    `listDimensions` in a short enough time suitable for testing."""
+    while True:
+        n = random.choice(settingsOEIS[oeisID_1random]['valuesTestValidation'])
+        if n < 2:
+            continue
+        listDimensionsCandidate = settingsOEIS[oeisID_1random]['getMapShape'](n)
+
+        try:
+            return validateListDimensions(listDimensionsCandidate)
+        except (ValueError, NotImplementedError):
+            pass
+
+@pytest.fixture
+def listDimensionsTestParallelization(oeisID: str) -> List[int]:
+    """For each `oeisID` from the `pytest.fixture`, returns `listDimensions` from `valuesTestParallelization`"""
+    n = random.choice(settingsOEIS[oeisID]['valuesTestParallelization'])
+    return settingsOEIS[oeisID]['getMapShape'](n)
+
+@pytest.fixture
+def mockBenchmarkTimer() -> Generator[unittest.mock.MagicMock | unittest.mock.AsyncMock, Any, None]:
+    """Mock time.perf_counter_ns for consistent benchmark timing."""
+    with unittest.mock.patch('time.perf_counter_ns') as mockTimer:
+        mockTimer.side_effect = [0, 1e9]  # Start and end times for 1 second
+        yield mockTimer
+
+@pytest.fixture
+def mockFoldingFunction() -> Callable[..., Callable[..., None]]:
+    """Creates a mock function that simulates _countFolds behavior."""
+    def make_mock(foldsValue: int, listDimensions: List[int]) -> Callable[..., None]:
+        mock_array = makeDataContainer(2)
+        mock_array[0] = foldsValue
+        mock_array[-1] = getLeavesTotal(listDimensions)
+
+        def mock_countFolds(**keywordArguments: Any) -> None:
+            keywordArguments['foldGroups'][:] = mock_array
+            return None
+
+        return mock_countFolds
+    return make_mock
+
+@pytest.fixture
+def mockDispatcher() -> Callable[[Any], ContextManager[Any]]:
+    """Context manager for mocking dispatcher callable."""
+    def wrapper(mockFunction: Any) -> ContextManager[Any]:
+        dispatcherCallable = getDispatcherCallable()
+        return unittest.mock.patch(
+            f"{dispatcherCallable.__module__}.{dispatcherCallable.__name__}",
+            side_effect=mockFunction
+        )
+    return wrapper
+
+@pytest.fixture(params=oeisIDsImplemented)
+def oeisID(request: pytest.FixtureRequest) -> Any:
+    return request.param
+
+@pytest.fixture
+def oeisID_1random() -> str:
+    """Return one random valid OEIS ID."""
+    return random.choice(oeisIDsImplemented)
+
+@pytest.fixture
+def useAlgorithmDirectly() -> Generator[None, Any, None]:
+    """Temporarily patches getDispatcherCallable to return the algorithm source directly."""
+    original_dispatcher = basecamp.getDispatcherCallable
+
+    # Patch the function at module level
+    basecamp.getDispatcherCallable = getAlgorithmCallable
+
+    yield
+
+    # Restore original function
+    basecamp.getDispatcherCallable = original_dispatcher
+
+"""
+Section: Prototype test structures before moving to uniformTests.py"""
+
+def prototypeCacheTest(
+    expected: Any,
+    setupCacheFile: Optional[Callable[[pathlib.Path, str], None]],
+    oeisID: str,
+    pathCache: pathlib.Path
+) -> None:
+    """Template for tests involving OEIS cache operations.
+
+    Parameters
+        expected: Expected value or exception from _getOEISidValues
+        setupCacheFile: Function to prepare the cache file before test
+        oeisID: OEIS ID to test
+        pathCache: Temporary cache directory path
+    """
+    pathFilenameCache = pathCache / _getFilenameOEISbFile(oeisID)
+
+    # Setup cache file if provided
+    if setupCacheFile:
+        setupCacheFile(pathFilenameCache, oeisID)
+
+    # Run test
+    try:
+        actual: Any = _getOEISidValues(oeisID)
+        messageActual = actual
+    except Exception as actualError:
+        actual = type(actualError)
+        messageActual = type(actualError).__name__
+
+    # Compare results
+    if isinstance(expected, type) and issubclass(expected, Exception):
+        messageExpected = expected.__name__
+        assert isinstance(actual, expected), uniformTestMessage(
+            messageExpected, messageActual, "_getOEISidValues", oeisID)
+    else:
+        messageExpected = expected
+        assert actual == expected, uniformTestMessage(
+            messageExpected, messageActual, "_getOEISidValues", oeisID)

tests/conftest_tmpRegistry.py

@@ -0,0 +1,62 @@
+from typing import Any, Generator, Set
+import pathlib
+import pytest
+import shutil
+import uuid
+
+# SSOT for test data paths
+pathDataSamples = pathlib.Path("tests/dataSamples")
+pathTempRoot = pathDataSamples / "tmp"
+
+# The registrar maintains the register of temp files
+registerOfTempFiles: Set[pathlib.Path] = set()
+
+def addTempFileToRegister(path: pathlib.Path) -> None:
+    """The registrar adds a temp file to the register."""
+    registerOfTempFiles.add(path)
+
+def cleanupTempFileRegister() -> None:
+    """The registrar cleans up temp files in the register."""
+    for pathTemp in sorted(registerOfTempFiles, reverse=True):
+        try:
+            if pathTemp.is_file():
+                pathTemp.unlink(missing_ok=True)
+            elif pathTemp.is_dir():
+                shutil.rmtree(pathTemp, ignore_errors=True)
+        except Exception as ERRORmessage:
+            print(f"Warning: Failed to clean up {pathTemp}: {ERRORmessage}")
+    registerOfTempFiles.clear()
+
+@pytest.fixture(scope="session", autouse=True)
+def setupTeardownTestData() -> Generator[None, None, None]:
+    """Auto-fixture to setup test data directories and cleanup after."""
+    pathDataSamples.mkdir(exist_ok=True)
+    pathTempRoot.mkdir(exist_ok=True)
+    yield
+    cleanupTempFileRegister()
+
+@pytest.fixture
+def pathTempTesting(request: pytest.FixtureRequest) -> pathlib.Path:
+    """Create a unique temp directory for each test function."""
+    # TODO I got rid of this shit. how the fuck is it back?
+    # Sanitize test name for filesystem compatibility
+    sanitizedName = request.node.name.replace('[', '_').replace(']', '_').replace('/', '_')
+    uniqueDirectory = f"{sanitizedName}_{uuid.uuid4()}"
+    pathTemp = pathTempRoot / uniqueDirectory
+    pathTemp.mkdir(parents=True, exist_ok=True)
+
+    addTempFileToRegister(pathTemp)
+    return pathTemp
+
+@pytest.fixture
+def pathCacheTesting(pathTempTesting: pathlib.Path) -> Generator[pathlib.Path, Any, None]:
+    """Temporarily replace the OEIS cache directory with a test directory."""
+    from mapFolding import oeis as there_must_be_a_better_way
+    pathCacheOriginal = there_must_be_a_better_way._pathCache
+    there_must_be_a_better_way._pathCache = pathTempTesting
+    yield pathTempTesting
+    there_must_be_a_better_way._pathCache = pathCacheOriginal
+
+@pytest.fixture
+def pathFilenameFoldsTotalTesting(pathTempTesting: pathlib.Path) -> pathlib.Path:
+    return pathTempTesting.joinpath("foldsTotalTest.txt")

tests/conftest_uniformTests.py

@@ -0,0 +1,53 @@
+from typing import Any, Callable, Sequence, Type, Union
+import pytest
+
+def uniformTestMessage(expected: Any, actual: Any, functionName: str, *arguments: Any) -> str:
+    """Format assertion message for any test comparison."""
+    return (f"\nTesting: `{functionName}({', '.join(str(parameter) for parameter in arguments)})`\n"
+            f"Expected: {expected}\n"
+            f"Got: {actual}")
+
+def standardizedEqualTo(expected: Any, functionTarget: Callable, *arguments: Any) -> None:
+    """Template for tests expecting an error."""
+    if type(expected) is Type[Exception]:
+        messageExpected = expected.__name__
+    else:
+        messageExpected = expected
+
+    try:
+        messageActual = actual = functionTarget(*arguments)
+    except Exception as actualError:
+        messageActual = type(actualError).__name__
+        actual = type(actualError)
+
+    assert actual == expected, uniformTestMessage(messageExpected, messageActual, functionTarget.__name__, *arguments)
+
+def standardizedSystemExit(expected: Union[str, int, Sequence[int]], functionTarget: Callable, *arguments: Any) -> None:
+    """Template for tests expecting SystemExit.
+
+    Parameters
+        expected: Exit code expectation:
+            - "error": any non-zero exit code
+            - "nonError": specifically zero exit code
+            - int: exact exit code match
+            - Sequence[int]: exit code must be one of these values
+        functionTarget: The function to test
+        arguments: Arguments to pass to the function
+    """
+    with pytest.raises(SystemExit) as exitInfo:
+        functionTarget(*arguments)
+
+    exitCode = exitInfo.value.code
+
+    if expected == "error":
+        assert exitCode != 0, \
+            f"Expected error exit (non-zero) but got code {exitCode}"
+    elif expected == "nonError":
+        assert exitCode == 0, \
+            f"Expected non-error exit (0) but got code {exitCode}"
+    elif isinstance(expected, (list, tuple)):
+        assert exitCode in expected, \
+            f"Expected exit code to be one of {expected} but got {exitCode}"
+    else:
+        assert exitCode == expected, \
+            f"Expected exit code {expected} but got {exitCode}"

tests/test_oeis.py

@@ -0,0 +1,200 @@
+from contextlib import redirect_stdout
+from datetime import datetime, timedelta
+from mapFolding.oeis import _getFilenameOEISbFile, _getOEISidValues, _parseBFileOEIS, _validateOEISid
+from tests.conftest import *
+from typing import Optional, NoReturn, Tuple, Union
+import io
+import os
+import pathlib
+import pytest
+import random
+import re as regex
+import unittest
+import unittest.mock
+import urllib
+from urllib.error import URLError
+import urllib.request
+
+def test_algorithmSourceSequential(oeisID: str, useAlgorithmDirectly: None) -> None:
+    for n in settingsOEIS[oeisID]['valuesTestValidation']:
+        standardizedEqualTo(settingsOEIS[oeisID]['valuesKnown'][n], oeisIDfor_n, oeisID, n)
+
+def test_aOFn_calculate_value(oeisID: str) -> None:
+    for n in settingsOEIS[oeisID]['valuesTestValidation']:
+        standardizedEqualTo(settingsOEIS[oeisID]['valuesKnown'][n], oeisIDfor_n, oeisID, n)
+
+@pytest.mark.parametrize("badID", ["A999999", "  A999999  ", "A999999extra"])
+def test__validateOEISid_invalid_id(badID: str) -> None:
+    standardizedEqualTo(KeyError, _validateOEISid, badID)
+
+def test__validateOEISid_partially_valid(oeisID_1random: str) -> None:
+    standardizedEqualTo(KeyError, _validateOEISid, f"{oeisID_1random}extra")
+
+def test__validateOEISid_valid_id(oeisID: str) -> None:
+    standardizedEqualTo(oeisID, _validateOEISid, oeisID)
+
+def test__validateOEISid_valid_id_case_insensitive(oeisID: str) -> None:
+    standardizedEqualTo(oeisID.upper(), _validateOEISid, oeisID.lower())
+    standardizedEqualTo(oeisID.upper(), _validateOEISid, oeisID.upper())
+    standardizedEqualTo(oeisID.upper(), _validateOEISid, oeisID.swapcase())
+
+parameters_test_aOFn_invalid_n = [
+    # (2, "ok"), # test the test template
+    (-random.randint(1, 100), "randomNegative"),
+    ("foo", "string"),
+    (1.5, "float")
+]
+badValues, badValuesIDs = zip(*parameters_test_aOFn_invalid_n)
+@pytest.mark.parametrize("badN", badValues, ids=badValuesIDs)
+def test_aOFn_invalid_n(oeisID_1random: str, badN: Any) -> None:
+    """Check that negative or non-integer n raises ValueError."""
+    standardizedEqualTo(ValueError, oeisIDfor_n, oeisID_1random, badN)
+
+def test_aOFn_zeroDim_A001418() -> None:
+    standardizedEqualTo(ArithmeticError, oeisIDfor_n, 'A001418', 0)
+
+# ===== OEIS Cache Tests =====
+@pytest.mark.parametrize("cacheExists", [True, False])
+@unittest.mock.patch('pathlib.Path.exists')
+@unittest.mock.patch('pathlib.Path.unlink')
+def test_clearOEIScache(mock_unlink: unittest.mock.MagicMock, mock_exists: unittest.mock.MagicMock, cacheExists: bool) -> None:
+    """Test OEIS cache clearing with both existing and non-existing cache."""
+    mock_exists.return_value = cacheExists
+    clearOEIScache()
+
+    if cacheExists:
+        assert mock_unlink.call_count == len(settingsOEIS)
+        mock_unlink.assert_has_calls([unittest.mock.call(missing_ok=True)] * len(settingsOEIS))
+    else:
+        mock_exists.assert_called_once()
+        mock_unlink.assert_not_called()
+
+@pytest.mark.parametrize("scenarioCache", ["miss", "expired", "invalid"])
+def testCacheScenarios(pathCacheTesting: pathlib.Path, oeisID_1random: str, scenarioCache: str) -> None:
+    """Test cache scenarios: missing file, expired file, and invalid file."""
+
+    def setupCacheExpired(pathCache: pathlib.Path, oeisID: str) -> None:
+        pathCache.write_text("# Old cache content")
+        oldModificationTime = datetime.now() - timedelta(days=30)
+        os.utime(pathCache, times=(oldModificationTime.timestamp(), oldModificationTime.timestamp()))
+
+    def setupCacheInvalid(pathCache: pathlib.Path, oeisID: str) -> None:
+        pathCache.write_text("Invalid content")
+
+    if scenarioCache == "miss":
+        prototypeCacheTest(settingsOEIS[oeisID_1random]['valuesKnown'], None, oeisID_1random, pathCacheTesting)
+    elif scenarioCache == "expired":
+        prototypeCacheTest(settingsOEIS[oeisID_1random]['valuesKnown'], setupCacheExpired, oeisID_1random, pathCacheTesting)
+    else:
+        prototypeCacheTest(settingsOEIS[oeisID_1random]['valuesKnown'], setupCacheInvalid, oeisID_1random, pathCacheTesting)
+
+def testInvalidFileContent(pathCacheTesting: pathlib.Path, oeisID_1random: str) -> None:
+    pathFilenameCache = pathCacheTesting / _getFilenameOEISbFile(oeisID=oeisID_1random)
+
+    # Write invalid content to cache
+    pathFilenameCache.write_text("# A999999\n1 1\n2 2\n")
+    modificationTimeOriginal = pathFilenameCache.stat().st_mtime
+
+    # Function should detect invalid content, fetch fresh data, and update cache
+    OEISsequence = _getOEISidValues(oeisID_1random)
+
+    # Verify the function succeeded
+    assert OEISsequence is not None
+    # Verify cache was updated (modification time changed)
+    assert pathFilenameCache.stat().st_mtime > modificationTimeOriginal
+    # Verify cache now contains correct sequence ID
+    assert f"# {oeisID_1random}" in pathFilenameCache.read_text()
+
+def testParseContentErrors() -> None:
+    """Test invalid content parsing."""
+    standardizedEqualTo(ValueError, _parseBFileOEIS, "Invalid content\n1 2\n", 'A001415')
+
+def testExtraComments(pathCacheTesting: pathlib.Path, oeisID_1random: str) -> None:
+    pathFilenameCache = pathCacheTesting / _getFilenameOEISbFile(oeisID=oeisID_1random)
+
+    # Write content with extra comment lines
+    contentWithExtraComments = f"""# {oeisID_1random}
+# Normal place for comment line 1
+# Abnormal comment line
+1 2
+2 4
+3 6
+# Another comment in the middle
+4 8
+5 10"""
+    pathFilenameCache.write_text(contentWithExtraComments)
+
+    OEISsequence = _getOEISidValues(oeisID_1random)
+    # Verify sequence values are correct despite extra comments
+    standardizedEqualTo(2, lambda d: d[1], OEISsequence)  # First value
+    standardizedEqualTo(8, lambda d: d[4], OEISsequence)  # Value after mid-sequence comment
+    standardizedEqualTo(10, lambda d: d[5], OEISsequence)  # Last value
+
+def testNetworkError(monkeypatch: pytest.MonkeyPatch, pathCacheTesting: pathlib.Path) -> None:
+    """Test network error handling."""
+    def mockUrlopen(*args: Any, **kwargs: Any) -> NoReturn:
+        raise URLError("Network error")
+
+    monkeypatch.setattr(urllib.request, 'urlopen', mockUrlopen)
+    standardizedEqualTo(URLError, _getOEISidValues, next(iter(settingsOEIS)))
+
+# ===== Command Line Interface Tests =====
+def testHelpText() -> None:
+    """Test that help text is complete and examples are valid."""
+    outputStream = io.StringIO()
+    with redirect_stdout(outputStream):
+        getOEISids()
+
+    helpText = outputStream.getvalue()
+
+    # Verify content
+    for oeisID in oeisIDsImplemented:
+        assert oeisID in helpText
+        assert settingsOEIS[oeisID]['description'] in helpText
+
+    # Extract and verify examples
+
+    cliMatch = regex.search(r'OEIS_for_n (\w+) (\d+)', helpText)
+    pythonMatch = regex.search(r"oeisIDfor_n\('(\w+)', (\d+)\)", helpText)
+
+    assert cliMatch and pythonMatch, "Help text missing examples"
+    oeisID, n = pythonMatch.groups()
+    n = int(n)
+
+    # Verify CLI and Python examples use same values
+    assert cliMatch.groups() == (oeisID, str(n)), "CLI and Python examples inconsistent"
+
+    # Verify the example works
+    expectedValue = oeisIDfor_n(oeisID, n)
+
+    # Test CLI execution of the example
+    with unittest.mock.patch('sys.argv', ['OEIS_for_n', oeisID, str(n)]):
+        outputStream = io.StringIO()
+        with redirect_stdout(outputStream):
+            OEIS_for_n()
+        standardizedEqualTo(expectedValue, lambda: int(outputStream.getvalue().strip().split()[0]))
+
+def testCLI_InvalidInputs() -> None:
+    """Test CLI error handling."""
+    testCases = [
+        (['OEIS_for_n'], "missing arguments"),
+        (['OEIS_for_n', 'A999999', '1'], "invalid OEIS ID"),
+        (['OEIS_for_n', 'A001415', '-1'], "negative n"),
+        (['OEIS_for_n', 'A001415', 'abc'], "non-integer n"),
+    ]
+
+    for arguments, testID in testCases:
+        with unittest.mock.patch('sys.argv', arguments):
+            standardizedSystemExit("error", OEIS_for_n)
+
+def testCLI_HelpFlag() -> None:
+    """Verify --help output contains required information."""
+    with unittest.mock.patch('sys.argv', ['OEIS_for_n', '--help']):
+        outputStream = io.StringIO()
+        with redirect_stdout(outputStream):
+            standardizedSystemExit("nonError", OEIS_for_n)
+
+        helpOutput = outputStream.getvalue()
+        assert "Available OEIS sequences:" in helpOutput
+        assert "Usage examples:" in helpOutput
+        assert all(oeisID in helpOutput for oeisID in oeisIDsImplemented)