mapFolding 0.2.0__py3-none-any.whl

mapFolding/theSSOT.py

@@ -0,0 +1,62 @@
+from typing import Any, Tuple, TypedDict
+import enum
+import numpy
+import numpy.typing
+import pathlib
+import sys
+
+try:
+    _pathModule = pathlib.Path(__file__).parent
+except NameError:
+    _pathModule = pathlib.Path.cwd()
+
+pathJobDEFAULT = _pathModule / "jobs"
+"""filenameFoldsTotal = str(sorted(mapShape)).replace(' ', '') + '.foldsTotal'"""
+if 'google.colab' in sys.modules:
+    pathJobDEFAULT = pathlib.Path("/content/drive/MyDrive") / "jobs"
+
+@enum.verify(enum.CONTINUOUS, enum.UNIQUE) if sys.version_info >= (3, 11) else lambda x: x
+class EnumIndices(enum.IntEnum):
+    """Base class for index enums."""
+    @staticmethod
+    def _generate_next_value_(name, start, count, last_values):
+        """0-indexed."""
+        return count
+
+    def __index__(self) -> int:
+        """Make the enum work with array indexing."""
+        return self.value
+
+class indexMy(EnumIndices):
+    """Indices for dynamic values."""
+    dimension1ndex = enum.auto()
+    dimensionsUnconstrained = enum.auto()
+    gap1ndex = enum.auto()
+    gap1ndexCeiling = enum.auto()
+    indexLeaf = enum.auto()
+    indexMiniGap = enum.auto()
+    leaf1ndex = enum.auto()
+    leafConnectee = enum.auto()
+    taskIndex = enum.auto()
+
+class indexThe(EnumIndices):
+    """Indices for static values."""
+    dimensionsTotal = enum.auto()
+    leavesTotal = enum.auto()
+    taskDivisions = enum.auto()
+
+class indexTrack(EnumIndices):
+    """Indices for state tracking array."""
+    leafAbove = enum.auto()
+    leafBelow = enum.auto()
+    countDimensionsGapped = enum.auto()
+    gapRangeStart = enum.auto()
+
+class computationState(TypedDict):
+    connectionGraph: numpy.typing.NDArray[numpy.integer[Any]]
+    foldsTotal: numpy.ndarray[numpy.int64, numpy.dtype[numpy.int64]]
+    mapShape: Tuple[int, ...]
+    my: numpy.typing.NDArray[numpy.integer[Any]]
+    gapsWhere: numpy.typing.NDArray[numpy.integer[Any]]
+    the: numpy.typing.NDArray[numpy.integer[Any]]
+    track: numpy.typing.NDArray[numpy.integer[Any]]

mapFolding-0.2.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.2
+Name: mapFolding
+Version: 0.2.0
+Summary: Algorithm(s) for counting distinct ways to fold a map (or a strip of stamps)
+Author-email: Hunter Hogan <HunterHogan@pm.me>
+Project-URL: homepage, https://github.com/hunterhogan/mapFolding
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numba
+Requires-Dist: numpy
+Requires-Dist: Z0Z-tools
+Provides-Extra: benchmark
+Requires-Dist: pandas; extra == "benchmark"
+Requires-Dist: jupyter; extra == "benchmark"
+Requires-Dist: ipywidgets; extra == "benchmark"
+Requires-Dist: tqdm; extra == "benchmark"
+Provides-Extra: jax
+Requires-Dist: jax; extra == "jax"
+Requires-Dist: jaxtyping; extra == "jax"
+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"
+
+# Algorithm(s) for counting distinct ways to fold a map (or a strip of stamps)
+
+`mapFolding.countFolds()` will accept arbitrary values for the map's dimensions.
+
+```python
+from mapFolding import countFolds
+foldsTotal = countFolds( [2,10] )
+```
+
+The directory `mapFolding/reference` has
+
+- a verbatim transcription of the "procedure" published in _The Computer Journal_,
+- multiple referential versions of the procedure with explanatory comments including
+- `hunterNumba.py` a one-size-fits-all, self-contained, reasonably fast, contemporary algorithm that is nevertheless infected by _noobaceae ignorancium_, and
+- miscellaneous notes.
+
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/unittests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/unittests.yml)
+
+## Simple, easy usage based on OEIS IDs
+
+`mapFolding` directly implements some IDs from _The On-Line Encyclopedia of Integer Sequences_.
+
+### Usage: command line
+
+After installing (see below), `OEIS_for_n` will run a computation from the command line.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> OEIS_for_n A001418 5
+186086600 distinct folding patterns.
+Time elapsed: 1.605 seconds
+```
+
+Use `getOEISids` to get the most up-to-date list of available OEIS IDs.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> getOEISids
+
+Available OEIS sequences:
+  A001415: Number of ways of folding a 2 X n strip of stamps.
+  A001416: Number of ways of folding a 3 X n strip of stamps.
+  A001417: Number of ways of folding a 2 X 2 X ... X 2 n-dimensional map.
+  A001418: Number of ways of folding an n X n sheet of stamps.
+  A195646: Number of ways of folding a 3 X 3 X ... X 3 n-dimensional map.
+
+Usage examples:
+  Command line:
+    OEIS_for_n A001415 8
+  Python:
+    from mapFolding import oeisIDfor_n
+    foldsTotal = oeisIDfor_n('A001415', 8)
+```
+
+### Usage: Python module or REPL
+
+Use `mapFolding.oeisIDfor_n()` to compute a(n) for an OEIS ID.
+
+```python
+from mapFolding import oeisIDfor_n
+foldsTotal = oeisIDfor_n( 'A001418', 4 )
+```
+
+### An "advanced" and likely unnecessary feature: clear `mapFolding`'s cache of OEIS data
+
+Clear _The On-Line Encyclopedia of Integer Sequences_ data from the `mapFolding` cache:
+
+```sh
+(mapFolding) C:\apps\mapFolding> clearOEIScache
+Cache cleared from C:\apps\mapFolding\mapFolding\.cache
+```
+
+## Connections to "Multi-dimensional map-folding" by W. F. Lunnon
+
+### The typo-laden algorithm published in 1971
+
+The full paper, W. F. Lunnon, Multi-dimensional map-folding, _The Computer Journal_, Volume 14, Issue 1, 1971, Pages 75–80, [https://doi.org/10.1093/comjnl/14.1.75](https://doi.org/10.1093/comjnl/14.1.75) ([BibTex](mapFolding/citations/Lunnon.bibtex) citation) is available at the DOI link. (As of 3 January 2025, the paper is a PDF of images, not text, and can be accessed without cost or login.)
+
+In [`foldings.txt`](mapFolding/reference/foldings.txt), you can find a text transcription of the algorithm as it was printed in 1971. In [`foldings.AA`](mapFolding/reference/foldings.AA), I have corrected obvious transcription errors, documented with comments, and I have reformatted line breaks and indentation. For contemporary readers, the result is likely easier to read than the text transcription or the original paper are easy to read. This is especially true if you view the document with semantic highlighting, such as with [Algol 60 syntax highlighter](https://github.com/PolariTOON/language-algol60).
+
+### Java implementation(s) and improvements
+
+[archmageirvine](https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java) ([BibTex](mapFolding/citations/jOEIS.bibtex) citation) says about the Java code:
+
+```java
+/**
+ * A001415 Number of ways of folding a 2 X n strip of stamps.
+ * @author Fred Lunnon (ALGOL68, C versions)
+ * @author Sean A. Irvine (Java port)
+ */
+...
+  // Implements algorithm as described in "Multi-dimensional map-folding",
+  // by W. F. Lunnon, The Computer J, 14, 1, pp. 75--80.  Note the original
+  // paper contains a few omissions, so this actual code is based on a C
+  // implementation by Fred Lunnon.
+```
+
+## Map-folding Video
+
+~~This caused my neurosis:~~ I enjoyed the following video, which is what introduced me to map folding.
+
+"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](mapFolding/citations/Physics_for_the_Birds.bibtex) citation)
+
+[![How Many Ways Can You Fold a Map?](https://i.ytimg.com/vi/sfH9uIY3ln4/hq720.jpg)](https://www.youtube.com/watch?v=sfH9uIY3ln4)
+
+## Install this package
+
+### From Github
+
+```sh
+pip install mapFolding@git+https://github.com/hunterhogan/mapFolding.git
+```
+
+### From a local directory
+
+#### Windows
+
+```powershell
+git clone https://github.com/hunterhogan/mapFolding.git \path\to\mapFolding
+pip install mapFolding@file:\path\to\mapFolding
+```
+
+#### POSIX
+
+```bash
+git clone https://github.com/hunterhogan/mapFolding.git /path/to/mapFolding
+pip install mapFolding@file:/path/to/mapFolding
+```
+
+## Install updates
+
+```sh
+pip install --upgrade mapFolding@git+https://github.com/hunterhogan/mapFolding.git
+```
+
+## Creating a virtual environment before installation
+
+You can isolate `mapFolding` in a virtual environment. For example, use the following commands to create a directory for the virtual environment, activate the virtual environment, and install the package. In the future, you will likely need to activate the virtual environment before using `mapFolding` again. From the command line, in a directory you want to install in.
+
+```sh
+py -m venv mapFolding
+cd mapFolding
+cd Scripts
+activate
+cd ..
+pip install mapFolding@git+https://github.com/hunterhogan/mapFolding.git
+```

mapFolding-0.2.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+mapFolding/__init__.py,sha256=fQGYxmjMofT1id_svln0L3htMBVUbMVj1UWIP74QhAQ,974
+mapFolding/babbage.py,sha256=tmz4ZEvMds1nPK7kb_oyl89AsGyuU0MB5udC8AAIL-I,633
+mapFolding/beDRY.py,sha256=JUGAuLpQYD-B_mSrgpw4E-JNM_N3gJ2VfY-FkrBP3yA,11135
+mapFolding/importPackages.py,sha256=Pno5VXaNiyJKG2Jtj4sB_h6EG50IJ7tQKyivVoKFMxo,303
+mapFolding/lovelace.py,sha256=NdQDPYpe7yU8GS9WIv_Rb4nOE9cPt0-XPKOiLfyE_Z4,9369
+mapFolding/oeis.py,sha256=pI08RrA39AVAU7U6h_1IowadxXC4K6n2OQd7vgTbTTI,11096
+mapFolding/startHere.py,sha256=37wU-VmM92bOZkFw4Wpiz3u0_1TiLsob94HZUPBwFQg,2433
+mapFolding/theSSOT.py,sha256=-t23-gPLPNWWBEeSi1mKkNCeeQA4y1AA_oPKC7tZwe4,1970
+mapFolding/JAX/lunnanJAX.py,sha256=xMZloN47q-MVfjdYOM1hi9qR4OnLq7qALmGLMraevQs,14819
+mapFolding/JAX/taskJAX.py,sha256=yJNeH0rL6EhJ6ppnATHF0Zf81CDMC10bnPnimVxE1hc,20037
+mapFolding/benchmarks/benchmarking.py,sha256=kv85F6V9pGhZvTOImArOuxyg5rywA_T6JLH_qFXM8BM,3018
+mapFolding/benchmarks/test_benchmarks.py,sha256=c4ANeR3jgqpKXFoxDeZkmAHxSuenMwsjmrhKJ1_XPqY,3659
+mapFolding/reference/hunterNumba.py,sha256=jV0dBjhLcnJjUHWRxLV_xvPIUP_GRLRKVeDhOtM9Wp4,7475
+mapFolding/reference/irvineJavaPort.py,sha256=Sj-63Z-OsGuDoEBXuxyjRrNmmyl0d7Yz_XuY7I47Oyg,4250
+mapFolding/reference/lunnan.py,sha256=SwjpOr1ROg-yZaZuiL7XjXhuvBxu_K4gQoPAWKUjJk4,5037
+mapFolding/reference/lunnanNumpy.py,sha256=bDQsBZUQcqJ9bTdnMF7HgtPcgpIodctujkm_lpq9NZ4,4653
+mapFolding/reference/lunnanWhile.py,sha256=p8_zLdMc6ujTYIu_yn-hbzOuLTQHvo0ENciIDmKayDU,4067
+mapFolding/reference/rotatedEntryPoint.py,sha256=6WVvEcGwDgRPa7dDs7ODAHUJjHDZDIDN6CXH8fFVFmA,12105
+tests/__init__.py,sha256=PGYVr7r23gATgcvZ3Sfph9D_g1MVvhgzMNWXBs_9tmY,52
+tests/conftest.py,sha256=ur6l5nDnWju7zOEMXqoNGYHY-Hf9GApOm4VT9pXtMtY,10594
+tests/test_oeis.py,sha256=h-NhWRoarl3v6qoB0RpnaUPuMGrQpWyfmsL0FXsGauU,7972
+tests/test_other.py,sha256=AZYRvZYL-wdDiKcbAFEBTV4a22CANmbl8mj8yVGBQ6g,4852
+tests/test_tasks.py,sha256=bBXsMfxb6WXz15eFjUxoS67wzRqusX_9XhetXaY-RnQ,944
+mapFolding-0.2.0.dist-info/METADATA,sha256=EC2InFN5XJ1LqKGptTerqGvuJQntDQdyMFG4WIvR6WU,6602
+mapFolding-0.2.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+mapFolding-0.2.0.dist-info/entry_points.txt,sha256=F3OUeZR1XDTpoH7k3wXuRb3KF_kXTTeYhu5AGK1SiOQ,146
+mapFolding-0.2.0.dist-info/top_level.txt,sha256=1gP2vFaqPwHujGwb3UjtMlLEGN-943VSYFR7V4gDqW8,17
+mapFolding-0.2.0.dist-info/RECORD,,

mapFolding-0.2.0.dist-info/WHEEL

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

mapFolding-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+OEIS_for_n = mapFolding.oeis:OEIS_for_n
+clearOEIScache = mapFolding.oeis:clearOEIScache
+getOEISids = mapFolding.oeis:getOEISids

mapFolding-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+mapFolding
+tests

tests/__init__.py

@@ -0,0 +1 @@
+from .conftest import makeDictionaryFoldsTotalKnown

tests/conftest.py

@@ -0,0 +1,262 @@
+"""SSOT for Pytest.
+Other test modules must not import directly from the package being tested."""
+
+# TODO learn how to run tests and coverage analysis without `env = ["NUMBA_DISABLE_JIT=1"]`
+
+from typing import Any, Callable, Dict, Generator, List, Optional, Sequence, Tuple, Type, Union
+import pathlib
+import pytest
+import random
+import unittest.mock
+
+from mapFolding import clearOEIScache
+from mapFolding import countFolds, pathJobDEFAULT
+from mapFolding import getLeavesTotal, parseDimensions, validateListDimensions
+from mapFolding.importPackages import makeTestSuiteConcurrencyLimit, defineConcurrencyLimit
+from mapFolding.importPackages import makeTestSuiteIntInnit, intInnit
+from mapFolding.importPackages import makeTestSuiteOopsieKwargsie, oopsieKwargsie
+from mapFolding.oeis import OEIS_for_n
+from mapFolding.oeis import _formatFilenameCache
+from mapFolding.oeis import _getOEISidValues
+from mapFolding.oeis import _parseBFileOEIS
+from mapFolding.oeis import _validateOEISid
+from mapFolding.oeis import getOEISids
+from mapFolding.oeis import oeisIDfor_n
+from mapFolding.oeis import oeisIDsImplemented
+from mapFolding.oeis import settingsOEIS
+
+__all__ = [
+    'OEIS_for_n',
+    '_formatFilenameCache',
+    '_getOEISidValues',
+    '_parseBFileOEIS',
+    '_validateOEISid',
+    'clearOEIScache',
+    'countFolds',
+    'defineConcurrencyLimit',
+    'expectSystemExit',
+    'getLeavesTotal',
+    'getOEISids',
+    'intInnit',
+    'makeTestSuiteConcurrencyLimit',
+    'makeTestSuiteIntInnit',
+    'makeTestSuiteOopsieKwargsie',
+    'oeisIDfor_n',
+    'oeisIDsImplemented',
+    'oopsieKwargsie',
+    'parseDimensions',
+    'settingsOEIS',
+    'standardCacheTest',
+    'standardComparison',
+    'validateListDimensions',
+    ]
+
+def makeDictionaryFoldsTotalKnown() -> Dict[Tuple[int,...], int]:
+    """Returns a dictionary mapping dimension tuples to their known folding totals."""
+    dictionaryMapDimensionsToFoldsTotalKnown = {}
+
+    for settings in settingsOEIS.values():
+        sequence = settings['valuesKnown']
+
+        for n, foldingsTotal in sequence.items():
+            dimensions = settings['getDimensions'](n)
+            dimensions.sort()
+            dictionaryMapDimensionsToFoldsTotalKnown[tuple(dimensions)] = foldingsTotal
+
+    # Are we in a place that has jobs?
+    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() and int(foldsTotal) > 85109616 * 10**3:
+                        foldsTotal = int(foldsTotal)
+                    # You made it this far, so fuck it: put it in the dictionary
+                    dictionaryMapDimensionsToFoldsTotalKnown[tuple(listDimensions)] = foldsTotal
+                    # The sunk-costs fallacy claims another victim!
+
+    return dictionaryMapDimensionsToFoldsTotalKnown
+
+"""
+Section: Fixtures"""
+
+@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 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]['getDimensions'](n)
+
+        try:
+            return validateListDimensions(listDimensionsCandidate)
+        except (ValueError, NotImplementedError):
+            pass
+
+@pytest.fixture
+def listDimensionsTest_countFolds(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]['getDimensions'](n)
+
+        try:
+            return validateListDimensions(listDimensionsCandidate)
+        except (ValueError, NotImplementedError):
+            pass
+
+@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(params=oeisIDsImplemented)
+def oeisID(request: pytest.FixtureRequest)-> str:
+    return request.param
+
+@pytest.fixture
+def oeisID_1random() -> str:
+    """Return one random valid OEIS ID."""
+    return random.choice(oeisIDsImplemented)
+
+@pytest.fixture
+def pathCacheTesting(tmp_path: 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 = tmp_path
+    yield tmp_path
+    there_must_be_a_better_way._pathCache = pathCacheOriginal
+
+@pytest.fixture
+def pathBenchmarksTesting(tmp_path: pathlib.Path) -> Generator[pathlib.Path, Any, None]:
+    """Temporarily replace the benchmarks directory with a test directory."""
+    from mapFolding.benchmarks import benchmarking
+    pathOriginal = benchmarking.pathFilenameRecordedBenchmarks
+    pathTest = tmp_path / "benchmarks.npy"
+    benchmarking.pathFilenameRecordedBenchmarks = pathTest
+    yield pathTest
+    benchmarking.pathFilenameRecordedBenchmarks = pathOriginal
+
+"""
+Section: Standardized test structures"""
+
+def standardComparison(expected: Any, functionTarget: Callable, *arguments: Any) -> None:
+    """Template for tests expecting an error."""
+    if type(expected) == 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, formatTestMessage(messageExpected, messageActual, functionTarget.__name__, *arguments)
+
+def expectSystemExit(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}"
+
+def formatTestMessage(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 standardCacheTest(
+    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 / _formatFilenameCache.format(oeisID=oeisID)
+
+    # Setup cache file if provided
+    if setupCacheFile:
+        setupCacheFile(pathFilenameCache, oeisID)
+
+    # Run test
+    try:
+        actual = _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), formatTestMessage(
+            messageExpected, messageActual, "_getOEISidValues", oeisID)
+    else:
+        messageExpected = expected
+        assert actual == expected, formatTestMessage(
+            messageExpected, messageActual, "_getOEISidValues", oeisID)