mapFolding 0.8.0__tar.gz → 0.8.1__tar.gz

{mapfolding-0.8.0 → mapfolding-0.8.1}/PKG-INFO

@@ -1,18 +1,17 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.8.0
-Summary: Count distinct ways to fold a map (or a strip of stamps)
+Version: 0.8.1
+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: Repository, https://github.com/hunterhogan/mapFolding.git
-Keywords: A001415,A001416,A001417,A001418,A195646,combinatorics,folding,map folding,OEIS,optimization,stamp folding
+Keywords: A001415,A001416,A001417,A001418,A195646,algorithmic optimization,AST manipulation,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,Numba optimization,OEIS,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 :: End Users/Desktop
-Classifier: Intended Audience :: Other Audience
 Classifier: Intended Audience :: Science/Research
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
@@ -23,7 +22,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Compilers
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -43,6 +45,7 @@ Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-env; extra == "testing"
 Requires-Dist: pytest-xdist; extra == "testing"
 Requires-Dist: pyupgrade; extra == "testing"
+Dynamic: license-file
 
 # mapFolding: Algorithms for enumerating distinct map/stamp folding patterns 🗺️
 
@@ -51,8 +54,6 @@ Requires-Dist: pyupgrade; extra == "testing"
 [![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
 ![Static Badge](https://img.shields.io/badge/issues-I%20have%20them-brightgreen)
 [![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/)
-![PyPI - Downloads](https://img.shields.io/pypi/dd/mapFolding)
-![GitHub repo size](https://img.shields.io/github/repo-size/hunterhogan/mapFolding)
 
 ---
 
@@ -100,44 +101,49 @@ Available OEIS sequences:
 
 ### 2. **Algorithm Zoo** 🦒
 
-- **Lunnon’s 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
+- **Lunnon's 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
 - The /reference directory.
 - **Numba-JIT Accelerated**: Up to 1000× faster than pure Python ([benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
 
-### 3. **For Researchers** 🔬
-
-- Change multiple minute settings, such as the bit width of the data types.
-- Transform the algorithm using AST
-- Create hyper-optimized modules to compute a specific map.
-
-### 4. **Customizing your algorithm**
-
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaJob.py (and/or synthesizeNumba____.py, as applicable)~~
-  - Synthesize a Numba-optimized module for a specific mapShape
-  - Synthesize _from_ a module in mapFolding\syntheticModules or from any source you select
-  - Use the existing transformation options
-  - Or create new ways of transforming the algorithm from its source to a specific job
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\makeJob.py~~
-  - Initialize data for a specific mapShape
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaModules.py (and/or synthesizeNumba____.py, as applicable)~~
-  - Synthesize one or more Numba-optimized modules for parallel or sequential computation
-  - Overwrite the modules in mapFolding\syntheticModules or save the module(s) to a custom path
-  - Synthesize _from_ the algorithm(s) in mapFolding\theDao.py or from any source you select
-  - Use the existing transformation options
-  - Or create new ways of transforming the algorithm from its source to a new module
-  - Use your new module in synthesizeNumbaJob.py, above, as the source to create a mapShape-specific job module
-- mapFolding\theDao.py
-  - Modify the algorithms for initializing values, parallel computation, and/or sequential computation
-  - Use the modified algorithm(s) in synthesizeNumbaModules.py, above, to create Numba-optimized version(s)
-  - Then use a Numba-optimized version in synthesizeNumbaJob.py, above, to create a hyper-optimized version for a specific mapShape
-- mapFolding\theSSOT.py
-  - Modify broad settings or find functions to modify broad settings, such as data structures and their data types
-  - Create new settings or groups of settings
-- mapFolding\beDRY.py
-  - Functions to handle common tasks, such as parsing parameters or creating the `connectionGraph` for a mapShape (a Cartesian product decomposition)
-- mapFolding\someAssemblyRequired
-  - Create new transformations to optimize the algorithm, such as for JAX, CuPy, or CUDA
-  - (mapFolding\reference\jax.py has a once-functional JAX implementation, and synthesizeModuleJAX.py might be a useful starting point)
+### 3. **For Researchers and Power Users** 🔬
+
+This package provides a sophisticated code transformation framework that can turn readable algorithm implementations into highly-optimized computational engines:
+
+- **Algorithmic Exploration**: Study the core algorithm in `theDao.py`, which uses a functional state-transformation approach with clear, isolated functions
+- **Performance Optimization**: Generate specialized implementations with the `someAssemblyRequired` transformation pipeline:
+  - AST-based code analysis and manipulation
+  - Dataclass "shattering" to decompose complex state objects into primitive components
+  - Just-in-time compilation with Numba and various optimization profiles
+  - LLVM IR extraction for low-level algorithmic analysis
+
+- **Extensible Design**: The transformation framework is abstract and generic, enabling:
+  - Creation of new optimization targets beyond the included Numba implementation
+  - Customization of compilation parameters and optimization levels
+  - Development of specialized algorithms for specific map dimensions
+
+### 4. **Customization and Extension Guide**
+
+The package architecture supports multiple levels of customization:
+
+- **Basic Usage**: Work with the high-level API in `basecamp.py` for standard computations
+- **Algorithm Modification**:
+  - Modify the core algorithm in `theDao.py` while preserving its functional approach
+  - Configure system-wide settings in `theSSOT.py` to adjust data types and performance characteristics
+  - Use utility functions in `beDRY.py` for common operations
+
+- **Advanced Transformation**:
+  - The `someAssemblyRequired` package provides tools to transform code at the AST level:
+    - `transformationTools.py` contains utilities for AST manipulation and code generation
+    - `transformDataStructures.py` handles complex data structure transformations
+    - `ingredientsNumba.py` provides Numba-specific configuration profiles
+    - `synthesizeNumbaFlow.py` orchestrates the transformation process
+
+- **Custom Deployment**:
+  - Generate specialized implementations for specific dimensions
+  - Create optimized modules that can be executed as standalone scripts
+  - Extract LLVM IR for further analysis or optimization
+
+The package's multi-level design allows you to start with simple API calls and progressively delve deeper into optimization as your computational needs grow.
 
 ## Map-folding Video
 
@@ -154,4 +160,4 @@ Available OEIS sequences:
 [![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)
 
-[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.png)](https://creativecommons.org/licenses/by-nc/4.0/)
+[![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.8.0 → mapfolding-0.8.1}/README.md

@@ -5,8 +5,6 @@
 [![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
 ![Static Badge](https://img.shields.io/badge/issues-I%20have%20them-brightgreen)
 [![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/)
-![PyPI - Downloads](https://img.shields.io/pypi/dd/mapFolding)
-![GitHub repo size](https://img.shields.io/github/repo-size/hunterhogan/mapFolding)
 
 ---
 
@@ -54,44 +52,49 @@ Available OEIS sequences:
 
 ### 2. **Algorithm Zoo** 🦒
 
-- **Lunnon’s 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
+- **Lunnon's 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
 - The /reference directory.
 - **Numba-JIT Accelerated**: Up to 1000× faster than pure Python ([benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
 
-### 3. **For Researchers** 🔬
-
-- Change multiple minute settings, such as the bit width of the data types.
-- Transform the algorithm using AST
-- Create hyper-optimized modules to compute a specific map.
-
-### 4. **Customizing your algorithm**
-
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaJob.py (and/or synthesizeNumba____.py, as applicable)~~
-  - Synthesize a Numba-optimized module for a specific mapShape
-  - Synthesize _from_ a module in mapFolding\syntheticModules or from any source you select
-  - Use the existing transformation options
-  - Or create new ways of transforming the algorithm from its source to a specific job
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\makeJob.py~~
-  - Initialize data for a specific mapShape
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaModules.py (and/or synthesizeNumba____.py, as applicable)~~
-  - Synthesize one or more Numba-optimized modules for parallel or sequential computation
-  - Overwrite the modules in mapFolding\syntheticModules or save the module(s) to a custom path
-  - Synthesize _from_ the algorithm(s) in mapFolding\theDao.py or from any source you select
-  - Use the existing transformation options
-  - Or create new ways of transforming the algorithm from its source to a new module
-  - Use your new module in synthesizeNumbaJob.py, above, as the source to create a mapShape-specific job module
-- mapFolding\theDao.py
-  - Modify the algorithms for initializing values, parallel computation, and/or sequential computation
-  - Use the modified algorithm(s) in synthesizeNumbaModules.py, above, to create Numba-optimized version(s)
-  - Then use a Numba-optimized version in synthesizeNumbaJob.py, above, to create a hyper-optimized version for a specific mapShape
-- mapFolding\theSSOT.py
-  - Modify broad settings or find functions to modify broad settings, such as data structures and their data types
-  - Create new settings or groups of settings
-- mapFolding\beDRY.py
-  - Functions to handle common tasks, such as parsing parameters or creating the `connectionGraph` for a mapShape (a Cartesian product decomposition)
-- mapFolding\someAssemblyRequired
-  - Create new transformations to optimize the algorithm, such as for JAX, CuPy, or CUDA
-  - (mapFolding\reference\jax.py has a once-functional JAX implementation, and synthesizeModuleJAX.py might be a useful starting point)
+### 3. **For Researchers and Power Users** 🔬
+
+This package provides a sophisticated code transformation framework that can turn readable algorithm implementations into highly-optimized computational engines:
+
+- **Algorithmic Exploration**: Study the core algorithm in `theDao.py`, which uses a functional state-transformation approach with clear, isolated functions
+- **Performance Optimization**: Generate specialized implementations with the `someAssemblyRequired` transformation pipeline:
+  - AST-based code analysis and manipulation
+  - Dataclass "shattering" to decompose complex state objects into primitive components
+  - Just-in-time compilation with Numba and various optimization profiles
+  - LLVM IR extraction for low-level algorithmic analysis
+
+- **Extensible Design**: The transformation framework is abstract and generic, enabling:
+  - Creation of new optimization targets beyond the included Numba implementation
+  - Customization of compilation parameters and optimization levels
+  - Development of specialized algorithms for specific map dimensions
+
+### 4. **Customization and Extension Guide**
+
+The package architecture supports multiple levels of customization:
+
+- **Basic Usage**: Work with the high-level API in `basecamp.py` for standard computations
+- **Algorithm Modification**:
+  - Modify the core algorithm in `theDao.py` while preserving its functional approach
+  - Configure system-wide settings in `theSSOT.py` to adjust data types and performance characteristics
+  - Use utility functions in `beDRY.py` for common operations
+
+- **Advanced Transformation**:
+  - The `someAssemblyRequired` package provides tools to transform code at the AST level:
+    - `transformationTools.py` contains utilities for AST manipulation and code generation
+    - `transformDataStructures.py` handles complex data structure transformations
+    - `ingredientsNumba.py` provides Numba-specific configuration profiles
+    - `synthesizeNumbaFlow.py` orchestrates the transformation process
+
+- **Custom Deployment**:
+  - Generate specialized implementations for specific dimensions
+  - Create optimized modules that can be executed as standalone scripts
+  - Extract LLVM IR for further analysis or optimization
+
+The package's multi-level design allows you to start with simple API calls and progressively delve deeper into optimization as your computational needs grow.
 
 ## Map-folding Video
 
@@ -108,4 +111,4 @@ Available OEIS sequences:
 [![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)
 
-[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.png)](https://creativecommons.org/licenses/by-nc/4.0/)
+[![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.8.1/mapFolding/__init__.py

@@ -0,0 +1,38 @@
+"""
+Map folding enumeration and counting algorithms with optimization capabilities.
+
+This package implements algorithms to count and enumerate the various ways
+a rectangular map can be folded, based on the mathematical problem described
+in Lunnon's 1971 paper. It provides multiple layers of functionality, from
+high-level user interfaces to low-level algorithmic optimizations and code
+transformation tools.
+
+Core modules:
+- basecamp: Public API with simplified interfaces for end users
+- theDao: Core computational algorithm using a functional state-transformation approach
+- beDRY: Utility functions for common operations and parameter management
+- theSSOT: Single Source of Truth for configuration, types, and state management
+- oeis: Interface to the Online Encyclopedia of Integer Sequences for known results
+
+Extended functionality:
+- someAssemblyRequired: Code transformation framework that optimizes the core algorithm
+  through AST manipulation, dataclass transformation, and compilation techniques
+
+Special directories:
+- .cache/: Stores cached data from external sources like OEIS to improve performance
+- syntheticModules/: Contains dynamically generated, optimized implementations of the
+  core algorithm created by the code transformation framework
+
+This package strives to balance algorithm readability and understandability with
+high-performance computation capabilities, allowing users to compute map folding
+totals for larger dimensions than previously feasible.
+"""
+from mapFolding.basecamp import countFolds as countFolds
+from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n
+
+__all__ = [
+    'clearOEIScache',
+    'countFolds',
+    'getOEISids',
+    'OEIS_for_n',
+]

{mapfolding-0.8.0 → mapfolding-0.8.1}/mapFolding/basecamp.py

@@ -1,3 +1,17 @@
+"""
+Public API for the map folding algorithm with simplified interface.
+
+This module provides the main entry point for users of the mapFolding package,
+abstracting away the complexities of the computational algorithm. It offers
+a high-level interface to count the total number of possible ways to fold
+a rectangular map of specified dimensions, with options for customizing the
+computation process and saving results.
+
+The primary function is countFolds, which handles parameter validation,
+computation state management, dispatching to the appropriate algorithm
+implementation, and optional persistence of results.
+"""
+
 from collections.abc import Sequence
 from mapFolding.beDRY import outfitCountFolds, setCPUlimit, validateListDimensions
 from mapFolding.filesystem import getPathFilenameFoldsTotal, saveFoldsTotal

{mapfolding-0.8.0 → mapfolding-0.8.1}/mapFolding/beDRY.py

@@ -1,4 +1,19 @@
-"""A relatively stable API for oft-needed functionality."""
+"""
+Utility functions for maintaining DRY (Don't Repeat Yourself) principles in the mapFolding package.
+
+This module provides a collection of helper functions that abstract common operations needed
+throughout the package, preventing code duplication and ensuring consistency. The functions
+manage core aspects of the computation process, including:
+
+1. Resource allocation and system limits management
+2. Data structure initialization and manipulation
+3. Parameter validation and interpretation
+4. Construction of specialized arrays and matrices for the folding algorithm
+
+The functions in this module serve as a relatively stable API for other modules to use,
+particularly for initializing computation state, validating inputs, and creating data
+structures needed by the folding algorithms.
+"""
 from collections.abc import Sequence
 from mapFolding.theSSOT import Array3D, ComputationState, getDatatypePackage, getNumpyDtypeDefault
 from sys import maxsize as sysMaxsize

mapfolding-0.8.1/mapFolding/filesystem.py

@@ -0,0 +1,129 @@
+"""
+Filesystem utilities for managing map folding computation results.
+
+This module provides functions for standardized handling of files related to the mapFolding
+package, with a focus on saving, retrieving, and naming computation results. It implements
+consistent naming conventions and path resolution strategies to ensure that:
+
+1. Computation results are stored in a predictable location
+2. Filenames follow a consistent pattern based on map dimensions
+3. Results can be reliably retrieved for future reference
+4. The system handles file operations safely with appropriate error handling
+
+The module serves as the interface between the computational components of the package
+and the filesystem, abstracting away the details of file operations and path management.
+"""
+from pathlib import Path, PurePath
+from typing import Any
+from os import PathLike
+import os
+
+def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
+    """
+    Create a standardized filename for a computed `foldsTotal` value.
+
+    This function generates a consistent, filesystem-safe filename based on map dimensions.
+    Standardizing filenames ensures that results can be reliably stored and retrieved,
+    avoiding potential filesystem incompatibilities or Python naming restrictions.
+
+    Parameters:
+        mapShape: A sequence of integers representing the dimensions of the map.
+
+    Returns:
+        filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions.
+
+    Notes:
+        The filename format ensures:
+        - No spaces in the filename
+        - Safe filesystem characters
+        - Unique extension (.foldsTotal)
+        - Python-safe strings (no starting with numbers, no reserved words)
+        - The 'p' prefix preserves compatibility with Lunnan's original code.
+    """
+    return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
+
+def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: str | PathLike[str] | None = None) -> Path:
+    """
+    Get a standardized path and filename for the computed foldsTotal value.
+
+    This function resolves paths for storing computation results, handling different
+    input types including directories, absolute paths, or relative paths. It ensures
+    that all parent directories exist in the resulting path.
+
+    Parameters:
+        mapShape: List of dimensions for the map folding problem.
+        pathLikeWriteFoldsTotal (getPathJobRootDEFAULT): Path, filename, or relative path and filename.
+            If None, uses default path. If a directory, appends standardized filename.
+
+    Returns:
+        pathFilenameFoldsTotal: Absolute path and filename for storing the foldsTotal value.
+
+    Notes:
+        The function creates any necessary directories in the path if they don't exist.
+    """
+    from mapFolding.theSSOT import getPathJobRootDEFAULT
+
+    if pathLikeWriteFoldsTotal is None:
+        pathFilenameFoldsTotal = getPathJobRootDEFAULT() / getFilenameFoldsTotal(mapShape)
+    else:
+        pathLikeSherpa = Path(pathLikeWriteFoldsTotal)
+        if pathLikeSherpa.is_dir():
+            pathFilenameFoldsTotal = pathLikeSherpa / getFilenameFoldsTotal(mapShape)
+        elif pathLikeSherpa.is_file() and pathLikeSherpa.is_absolute():
+            pathFilenameFoldsTotal = pathLikeSherpa
+        else:
+            pathFilenameFoldsTotal = getPathJobRootDEFAULT() / pathLikeSherpa
+
+    pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+    return pathFilenameFoldsTotal
+
+def saveFoldsTotal(pathFilename: str | PathLike[str], foldsTotal: int) -> None:
+    """
+    Save `foldsTotal` value to disk with multiple fallback mechanisms.
+
+    This function attempts to save the computed `foldsTotal` value to the specified
+    location, with backup strategies in case the primary save attempt fails.
+    The robustness is critical since these computations may take days to complete.
+
+    Parameters:
+        pathFilename: Target save location for the `foldsTotal` value
+        foldsTotal: The computed value to save
+
+    Notes:
+        If the primary save fails, the function will attempt alternative save methods:
+        1. Print the value prominently to stdout
+        2. Create a fallback file in the current working directory
+        3. As a last resort, simply print the value
+    """
+    try:
+        pathFilenameFoldsTotal = Path(pathFilename)
+        pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+        pathFilenameFoldsTotal.write_text(str(foldsTotal))
+    except Exception as ERRORmessage:
+        try:
+            print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+            print(ERRORmessage)
+            print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+            randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
+            filenameInfixUnique = ''.join(randomnessPlanB)
+            pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
+            writeStreamFallback = open(pathFilenamePlanB, 'w')
+            writeStreamFallback.write(str(foldsTotal))
+            writeStreamFallback.close()
+            print(str(pathFilenamePlanB))
+        except Exception:
+            print(foldsTotal)
+    return None
+
+def writeStringToHere(this: str, pathFilename: str | PathLike[Any] | PurePath) -> None:
+    """
+    Write a string to a file, creating parent directories if needed.
+
+    Parameters:
+        this: The string content to write to the file
+        pathFilename: The target file path where the string should be written
+    """
+    pathFilename = Path(pathFilename)
+    pathFilename.parent.mkdir(parents=True, exist_ok=True)
+    pathFilename.write_text(str(this))
+    return None

{mapfolding-0.8.0 → mapfolding-0.8.1}/mapFolding/noHomeYet.py

@@ -1,3 +1,15 @@
+"""
+Interface for retrieving known map folding totals from OEIS (Online Encyclopedia of Integer Sequences).
+
+This module provides utilities for accessing pre-computed map folding totals that are known
+from mathematical literature and stored in the OEIS. The functions cache results for
+performance and provide lookups based on map dimensions.
+
+The main functions are:
+- makeDictionaryFoldsTotalKnown: Creates a dictionary of known folding totals indexed by map dimensions
+- getFoldsTotalKnown: Retrieves the folding total for a specific map shape, returning -1 if unknown
+"""
+
 from functools import cache
 from mapFolding.oeis import settingsOEIS
 

{mapfolding-0.8.0 → mapfolding-0.8.1}/mapFolding/oeis.py

@@ -1,4 +1,19 @@
-"""Everything implementing the The Online Encyclopedia of Integer Sequences (OEIS); _only_ things that implement _only_ the OEIS."""
+"""
+Interface to The Online Encyclopedia of Integer Sequences (OEIS) for map folding sequences.
+
+This module provides a comprehensive interface for accessing and utilizing integer sequences
+from the OEIS that relate to map folding problems. It implements functionality to:
+
+1. Retrieve sequence data from OEIS with local caching for performance
+2. Map sequence indices to corresponding map shapes based on sequence definitions
+3. Provide a command-line interface for sequence lookups
+4. Execute map folding computations for sequence terms not available in OEIS
+
+The module maintains a registry of implemented OEIS sequences (A001415-A001418, A195646)
+with their metadata, known values, and functions to convert between sequence indices and
+map dimensions. This allows the package to validate results against established mathematical
+literature and extend sequences beyond their currently known terms.
+"""
 from collections.abc import Callable
 from datetime import datetime, timedelta
 from mapFolding.theSSOT import thePathPackage