hunterMakesPy 0.1.0__py3-none-any.whl

hunterMakesPy/__init__.py

@@ -0,0 +1,16 @@
+"""`import hunterMakesPy as humpy`."""
+from hunterMakesPy.theTypes import identifierDotAttribute as identifierDotAttribute
+
+from hunterMakesPy.coping import raiseIfNone as raiseIfNone
+
+from hunterMakesPy.parseParameters import (defineConcurrencyLimit as defineConcurrencyLimit, intInnit as intInnit,
+	oopsieKwargsie as oopsieKwargsie)
+
+from hunterMakesPy.filesystemToolkit import (importLogicalPath2Identifier as importLogicalPath2Identifier,
+	importPathFilename2Identifier as importPathFilename2Identifier, makeDirsSafely as makeDirsSafely,
+    writeStringToHere as writeStringToHere)
+
+from hunterMakesPy.dataStructures import (autoDecodingRLE as autoDecodingRLE, stringItUp as stringItUp,
+	updateExtendPolishDictionaryLists as updateExtendPolishDictionaryLists)
+
+from hunterMakesPy._theSSOT import settingsPackage

hunterMakesPy/_theSSOT.py

@@ -0,0 +1,40 @@
+"""Primary: settings for this package.
+
+Secondary: settings for manufacturing.
+Tertiary: hardcoded values until I implement a dynamic solution.
+"""
+from importlib.util import find_spec
+from pathlib import Path
+from tomli import loads as tomli_loads
+from typing import TYPE_CHECKING
+import dataclasses
+
+if TYPE_CHECKING:
+	from importlib.machinery import ModuleSpec
+
+try:
+	identifierPackagePACKAGING: str = tomli_loads(Path("pyproject.toml").read_text())["project"]["name"]
+except Exception:  # noqa: BLE001
+	identifierPackagePACKAGING = "hunterMakesPy"
+
+def getPathPackageINSTALLING() -> Path:
+    """Return the root directory of the installed package."""
+    try:
+        moduleSpecification: ModuleSpec | None = find_spec(identifierPackagePACKAGING)
+        if moduleSpecification and moduleSpecification.origin:
+            pathFilename = Path(moduleSpecification.origin)
+            return pathFilename.parent if pathFilename.is_file() else pathFilename
+    except ModuleNotFoundError:
+        pass
+    return Path.cwd()
+
+@dataclasses.dataclass
+class PackageSettings:
+	fileExtension: str = dataclasses.field(default='.py', metadata={'evaluateWhen': 'installing'})
+	"""Default file extension for generated code files."""
+	identifierPackage: str = dataclasses.field(default = identifierPackagePACKAGING, metadata={'evaluateWhen': 'packaging'})
+	"""Name of this package, used for import paths and configuration."""
+	pathPackage: Path = dataclasses.field(default_factory=getPathPackageINSTALLING, metadata={'evaluateWhen': 'installing'})
+	"""Absolute path to the installed package directory."""
+
+settingsPackage = PackageSettings()

hunterMakesPy/coping.py

@@ -0,0 +1,73 @@
+"""Utility functions for handling `None` values and coping with common programming patterns.
+
+(AI generated docstring)
+
+This module provides helper functions for defensive programming and error handling, particularly for dealing with `None` values that should not occur in correct program flow.
+
+"""
+from typing import TypeVar
+
+TypeSansNone = TypeVar('TypeSansNone')
+
+def raiseIfNone(returnTarget: TypeSansNone | None, errorMessage: str | None = None) -> TypeSansNone:
+	"""Raise a `ValueError` if the target value is `None`, otherwise return the value: tell the type checker that the return value is not `None`.
+
+	(AI generated docstring)
+
+	This is a defensive programming function that converts unexpected `None` values into explicit errors with context. It is useful for asserting that functions that might return `None` have actually returned a meaningful value.
+
+	Parameters
+	----------
+	returnTarget : TypeSansNone | None
+		The value to check for `None`. If not `None`, this value is returned unchanged.
+	errorMessage : str | None = None
+		Custom error message to include in the `ValueError`. If `None`, a default message with debugging hints is used.
+
+	Returns
+	-------
+	returnTarget : TypeSansNone
+		The original `returnTarget` value, guaranteed to not be `None`.
+
+	Raises
+	------
+	ValueError
+		If `returnTarget` is `None`.
+
+	Examples
+	--------
+	Ensure a function result is not `None`:
+
+	```python
+	def findFirstMatch(listItems: list[str], pattern: str) -> str | None:
+		for item in listItems:
+			if pattern in item:
+				return item
+		return None
+
+	listFiles = ['document.txt', 'image.png', 'data.csv']
+	filename = raiseIfNone(findFirstMatch(listFiles, '.txt'))
+	# Returns 'document.txt'
+	```
+
+	Handle dictionary lookups with custom error messages:
+
+	```python
+	configurationMapping = {'host': 'localhost', 'port': 8080}
+	host = raiseIfNone(configurationMapping.get('host'),
+					"Configuration must include 'host' setting")
+	# Returns 'localhost'
+
+	# This would raise ValueError with custom message:
+	# database = raiseIfNone(configurationMapping.get('database'),
+	#                       "Configuration must include 'database' setting")
+	```
+
+	Thanks
+	------
+	sobolevn, https://github.com/sobolevn, for the seed of the function. https://github.com/python/typing/discussions/1997#discussioncomment-13108399
+
+	"""
+	if returnTarget is None:
+		message = errorMessage or 'A function unexpectedly returned `None`. Hint: look at the traceback immediately before `raiseIfNone`.'
+		raise ValueError(message)
+	return returnTarget

hunterMakesPy/dataStructures.py

@@ -0,0 +1,265 @@
+"""Provides utilities for string extraction from nested data structures and merges multiple dictionaries containing lists into one dictionary."""
+
+from collections.abc import Iterator, Mapping
+from numpy import integer
+from numpy.typing import NDArray
+from typing import Any
+import more_itertools
+import python_minifier
+import re as regex
+
+def autoDecodingRLE(arrayTarget: NDArray[integer[Any]], *, assumeAddSpaces: bool = False) -> str:  # noqa: C901, PLR0915
+	"""Transform a NumPy array into a compact, self-decoding run-length encoded string representation.
+
+	This function converts a NumPy array into a string that, when evaluated as Python code,
+	recreates the original array structure. The function employs two compression strategies:
+	1. Python's `range` syntax for consecutive integer sequences
+	2. Multiplication syntax for repeated elements
+
+	The resulting string representation is designed to be both human-readable and space-efficient,
+	especially for large cartesian mappings with repetitive patterns. When this string is used
+	as a data source, Python will automatically decode it into Python `list`, which if used as an
+	argument to `numpy.array()`, will recreate the original array structure.
+
+	Parameters
+	----------
+	arrayTarget : NDArray[integer[Any]]
+		(array2target) The NumPy array to be encoded.
+	assumeAddSpaces : bool = False
+		(assume2add2spaces) Affects internal length comparison during compression decisions.
+		This parameter doesn't directly change output format but influences whether
+		`range` or multiplication syntax is preferred in certain cases. The parameter
+		exists because the Abstract Syntax Tree (AST) inserts spaces in its string
+		representation.
+
+	Returns
+	-------
+	rleString : str
+		(rle2string) A string representation of the array using run-length encoding that,
+		when evaluated as Python code, reproduces the original array structure.
+
+	Notes
+	-----
+	The "autoDecoding" feature means that the string representation evaluates directly
+	to the desired data structure without explicit decompression steps.
+
+	"""
+	def sliceNDArrayToNestedLists(arraySlice: NDArray[integer[Any]]) -> Any:
+		def getLengthOption(optionAsStr: str) -> int:
+			# `assumeAddSpaces` characters: `,` 1; `]*` 2  # noqa: ERA001
+			return assumeAddSpaces * (optionAsStr.count(',') + optionAsStr.count(']*') * 2) + len(optionAsStr)
+
+		if arraySlice.ndim > 1:
+			axisOfOperation = 0
+			return [sliceNDArrayToNestedLists(arraySlice[index]) for index in range(arraySlice.shape[axisOfOperation])]
+		if arraySlice.ndim == 1:
+			arraySliceAsList: list[int | range] = []
+			cache_consecutiveGroup_addMe: dict[Iterator[Any], list[int] | list[range]] = {}
+			for consecutiveGroup in more_itertools.consecutive_groups(arraySlice.tolist()):
+				if consecutiveGroup in cache_consecutiveGroup_addMe:
+					addMe = cache_consecutiveGroup_addMe[consecutiveGroup]
+				else:
+					ImaSerious: list[int] = list(consecutiveGroup)
+					ImaRange = [range(ImaSerious[0], ImaSerious[-1] + 1)]
+					ImaRangeAsStr = python_minifier.minify(str(ImaRange)).replace('range(0,', 'range(').replace('range', '*range')
+
+					option1 = ImaRange
+					option1AsStr = ImaRangeAsStr
+					option2 = ImaSerious
+					option2AsStr = None
+
+					# alpha, potential function
+					option1AsStr = option1AsStr or python_minifier.minify(str(option1))
+					lengthOption1 = getLengthOption(option1AsStr)
+
+					option2AsStr = option2AsStr or python_minifier.minify(str(option2))
+					lengthOption2 = getLengthOption(option2AsStr)
+
+					if lengthOption1 < lengthOption2:
+						addMe = option1
+					else:
+						addMe = option2
+
+					cache_consecutiveGroup_addMe[consecutiveGroup] = addMe
+
+				arraySliceAsList += addMe
+
+			listRangeAndTuple: list[int | range | tuple[int | range, int]] = []
+			cache_malkovichGrouped_addMe: dict[tuple[int | range, int], list[tuple[int | range, int]] | list[int | range]] = {}
+			for malkovichGrouped in more_itertools.run_length.encode(arraySliceAsList):
+				if malkovichGrouped in cache_malkovichGrouped_addMe:
+					addMe = cache_malkovichGrouped_addMe[malkovichGrouped]
+				else:
+					lengthMalkovich = malkovichGrouped[-1]
+					malkovichAsList = list(more_itertools.run_length.decode([malkovichGrouped]))
+					malkovichMalkovich = f"[{malkovichGrouped[0]}]*{lengthMalkovich}"
+
+					option1 = [malkovichGrouped]
+					option1AsStr = malkovichMalkovich
+					option2 = malkovichAsList
+					option2AsStr = None
+
+					# beta, potential function
+					option1AsStr = option1AsStr or python_minifier.minify(str(option1))
+					lengthOption1 = getLengthOption(option1AsStr)
+
+					option2AsStr = option2AsStr or python_minifier.minify(str(option2))
+					lengthOption2 = getLengthOption(option2AsStr)
+
+					if lengthOption1 < lengthOption2:
+						addMe = option1
+					else:
+						addMe = option2
+
+					cache_malkovichGrouped_addMe[malkovichGrouped] = addMe
+
+				listRangeAndTuple += addMe
+
+			return listRangeAndTuple
+		return arraySlice
+
+	arrayAsNestedLists = sliceNDArrayToNestedLists(arrayTarget)
+
+	arrayAsStr = python_minifier.minify(str(arrayAsNestedLists))
+
+	patternRegex = regex.compile(
+		"(?<!rang)(?:"
+		# Pattern 1: Comma ahead, bracket behind  # noqa: ERA001
+		"(?P<joinAhead>,)\\((?P<malkovich>\\d+),(?P<multiple>\\d+)\\)(?P<bracketBehind>])|"
+		# Pattern 2: Bracket or start ahead, comma behind  # noqa: ERA001
+		"(?P<bracketOrStartAhead>\\[|^.)\\((?P<malkovichmalkovich>\\d+),(?P<multiple_fml>\\d+)\\)(?P<joinBehind>,)|"
+		# Pattern 3: Bracket ahead, bracket behind  # noqa: ERA001
+		"(?P<bracketAhead>\\[)\\((?P<malkovichmalkovichmalkovich>\\d+),(?P<multiple_whatever>\\d+)\\)(?P<bracketBehindbracketBehind>])|"
+		# Pattern 4: Comma ahead, comma behind  # noqa: ERA001
+		"(?P<joinAhead_prayharder>,)\\((?P<malkovichmalkovichmalkovichmalkovich>\\d+),(?P<multiple_prayharder>\\d+)\\)(?P<joinBehind_prayharder>,)"
+		")"
+	)
+
+	def replacementByContext(match: regex.Match[str]) -> str:
+		"""Generate replacement string based on context patterns."""
+		yourIdentifiersSuck = match.groupdict()
+		joinAhead = yourIdentifiersSuck.get('joinAhead') or yourIdentifiersSuck.get('joinAhead_prayharder')
+		malkovich = yourIdentifiersSuck.get('malkovich') or yourIdentifiersSuck.get('malkovichmalkovich') or yourIdentifiersSuck.get('malkovichmalkovichmalkovich') or yourIdentifiersSuck.get('malkovichmalkovichmalkovichmalkovich')
+		multiple = yourIdentifiersSuck.get('multiple') or yourIdentifiersSuck.get('multiple_fml') or yourIdentifiersSuck.get('multiple_whatever') or yourIdentifiersSuck.get('multiple_prayharder')
+		joinBehind = yourIdentifiersSuck.get('joinBehind') or yourIdentifiersSuck.get('joinBehind_prayharder')
+
+		replaceAhead = "]+[" if joinAhead == "," else "["
+
+		replaceBehind = "+[" if joinBehind == "," else ""
+
+		return f"{replaceAhead}{malkovich}]*{multiple}{replaceBehind}"
+
+	arrayAsStr = patternRegex.sub(replacementByContext, arrayAsStr)
+	arrayAsStr = patternRegex.sub(replacementByContext, arrayAsStr)
+
+	# Replace `range(0,stop)` syntax with `range(stop)` syntax.  # noqa: ERA001
+	# Add unpack operator `*` for automatic decoding when evaluated.
+	return arrayAsStr.replace('range(0,', 'range(').replace('range', '*range')
+
+def stringItUp(*scrapPile: Any) -> list[str]:  # noqa: C901
+	"""Convert, if possible, every element in the input data structure to a string.
+
+	Order is not preserved or readily predictable.
+
+	Parameters
+	----------
+	*scrapPile : Any
+		(scrap2pile) One or more data structures to unpack and convert to strings.
+
+	Returns
+	-------
+	listStrungUp : list[str]
+		(list2strung2up) A `list` of string versions of all convertible elements.
+
+	"""
+	scrap = None
+	listStrungUp: list[str] = []
+
+	def drill(KitKat: Any) -> None:  # noqa: C901, PLR0912
+		match KitKat:
+			case str():
+				listStrungUp.append(KitKat)
+			case bool() | bytearray() | bytes() | complex() | float() | int() | memoryview() | None:
+				listStrungUp.append(str(KitKat)) # pyright: ignore [reportUnknownArgumentType]
+			case dict():
+				for broken, piece in KitKat.items(): # pyright: ignore [reportUnknownVariableType]
+					drill(broken)
+					drill(piece)
+			case list() | tuple() | set() | frozenset() | range():
+				for kit in KitKat: # pyright: ignore [reportUnknownVariableType]
+					drill(kit)
+			case _:
+				if hasattr(KitKat, '__iter__'):  # Unpack other iterables
+					for kat in KitKat:
+						drill(kat)
+				else:
+					try:
+						sharingIsCaring = KitKat.__str__()
+						listStrungUp.append(sharingIsCaring)
+					except AttributeError:
+						pass
+					except TypeError:  # "The error traceback provided indicates that there is an issue when calling the __str__ method on an object that does not have this method properly defined, leading to a TypeError."
+						pass
+					except:
+						print(f"\nWoah! I received '{repr(KitKat)}'.\nTheir report card says, 'Plays well with others: Needs improvement.'\n")  # noqa: RUF010, T201
+						raise
+	try:
+		for scrap in scrapPile:
+			drill(scrap)
+	except RecursionError:
+		listStrungUp.append(repr(scrap))
+	return listStrungUp
+
+def updateExtendPolishDictionaryLists(*dictionaryLists: Mapping[str, list[Any] | set[Any] | tuple[Any, ...]], destroyDuplicates: bool = False, reorderLists: bool = False, killErroneousDataTypes: bool = False) -> dict[str, list[Any]]:
+	"""Merge multiple dictionaries containing `list` into a single dictionary.
+
+	With options to handle duplicates, `list` ordering, and erroneous data types.
+
+	Parameters
+	----------
+	*dictionaryLists : Mapping[str, list[Any] | set[Any] | tuple[Any, ...]]
+		(dictionary2lists) Variable number of dictionaries to be merged. If only one dictionary is passed, it will be processed based on the provided options.
+	destroyDuplicates : bool = False
+		(destroy2duplicates) If `True`, removes duplicate elements from the `list`. Defaults to `False`.
+	reorderLists : bool = False
+		(reorder2lists) If `True`, sorts the `list`. Defaults to `False`.
+	killErroneousDataTypes : bool = False
+		(kill2erroneous2data2types) If `True`, skips dictionary keys or dictionary values that cause a `TypeError` during merging. Defaults to `False`.
+
+	Returns
+	-------
+	ePluribusUnum : dict[str, list[Any]]
+		(e2pluribus2unum) A single dictionary with merged `list` based on the provided options. If only one dictionary is passed,
+		it will be cleaned up based on the options.
+
+	Notes
+	-----
+	The returned value, `ePluribusUnum`, is a so-called primitive dictionary (`dict`). Furthermore, every dictionary key is a
+	so-called primitive string (cf. `str()`) and every dictionary value is a so-called primitive `list` (`list`). If
+	`dictionaryLists` has other data types, the data types will not be preserved. That could have unexpected consequences.
+	Conversion from the original data type to a `list`, for example, may not preserve the order even if you want the order to be
+	preserved.
+
+	"""
+	ePluribusUnum: dict[str, list[Any]] = {}
+
+	for dictionaryListTarget in dictionaryLists:
+		for keyName, keyValue in dictionaryListTarget.items():
+			try:
+				ImaStr = str(keyName)
+				ImaList = list(keyValue)
+				ePluribusUnum.setdefault(ImaStr, []).extend(ImaList)
+			except TypeError:  # noqa: PERF203
+				if killErroneousDataTypes:
+					continue
+				else:
+					raise
+
+	if destroyDuplicates:
+		for ImaStr, ImaList in ePluribusUnum.items():
+			ePluribusUnum[ImaStr] = list(dict.fromkeys(ImaList))
+	if reorderLists:
+		for ImaStr, ImaList in ePluribusUnum.items():
+			ePluribusUnum[ImaStr] = sorted(ImaList)
+
+	return ePluribusUnum

hunterMakesPy/filesystemToolkit.py

@@ -0,0 +1,114 @@
+"""File system and module import utilities.
+
+This module provides basic file I/O utilities such as writing tabular data to files, computing canonical relative paths, importing
+callables from modules, and safely creating directories.
+
+"""
+
+from hunterMakesPy import identifierDotAttribute
+from os import PathLike
+from pathlib import Path, PurePath
+from typing import Any, TYPE_CHECKING, TypeVar
+import contextlib
+import importlib
+import importlib.util
+import io
+
+if TYPE_CHECKING:
+	from types import ModuleType
+
+归个 = TypeVar('归个')
+
+def importLogicalPath2Identifier(logicalPathModule: identifierDotAttribute, identifier: str, packageIdentifierIfRelative: str | None = None) -> 归个:
+	"""Import an `identifier`, such as a function or `class`, from a module using its logical path.
+
+	This function imports a module and retrieves a specific attribute (function, class, or other object) from that module.
+
+	Parameters
+	----------
+	logicalPathModule : identifierDotAttribute
+		The logical path to the module, using dot notation (e.g., 'scipy.signal.windows').
+	identifier : str
+		The identifier of the object to retrieve from the module.
+	packageIdentifierIfRelative : str | None = None
+		The package name to use as the anchor point if `logicalPathModule` is a relative import. `None` means an absolute import.
+
+	Returns
+	-------
+	identifierImported : 归个
+		The identifier (function, class, or object) retrieved from the module.
+
+	"""
+	moduleImported: ModuleType = importlib.import_module(logicalPathModule, packageIdentifierIfRelative)
+	return getattr(moduleImported, identifier)
+
+def importPathFilename2Identifier(pathFilename: PathLike[Any] | PurePath, identifier: str, moduleIdentifier: str | None = None) -> 归个:
+	"""Load an identifier from a Python file.
+
+	This function imports a specified Python file as a module, extracts an identifier from it by name, and returns that
+	identifier.
+
+	Parameters
+	----------
+	pathFilename : PathLike[Any] | PurePath
+		Path to the Python file to import.
+	identifier : str
+		Name of the identifier to extract from the imported module.
+	moduleIdentifier : str | None = None
+		Name to use for the imported module. If `None`, the filename stem is used.
+
+	Returns
+	-------
+	identifierImported : 归个
+		The identifier extracted from the imported module.
+
+	Raises
+	------
+	ImportError
+		If the file cannot be imported or the importlib specification is invalid.
+	AttributeError
+		If the identifier does not exist in the imported module.
+
+	"""
+	pathFilename = Path(pathFilename)
+
+	importlibSpecification = importlib.util.spec_from_file_location(moduleIdentifier or pathFilename.stem, pathFilename)
+	if importlibSpecification is None or importlibSpecification.loader is None:
+		message = f"I received\n\t`{pathFilename = }`,\n\t`{identifier = }`, and\n\t`{moduleIdentifier = }`.\n\tAfter loading, \n\t`importlibSpecification` {'is `None`' if importlibSpecification is None else 'has a value'} and\n\t`importlibSpecification.loader` is unknown."
+		raise ImportError(message)
+
+	moduleImported_jk_hahaha: ModuleType = importlib.util.module_from_spec(importlibSpecification)
+	importlibSpecification.loader.exec_module(moduleImported_jk_hahaha)
+	return getattr(moduleImported_jk_hahaha, identifier)
+
+def makeDirsSafely(pathFilename: Any) -> None:
+	"""Create parent directories for a given path safely.
+
+	This function attempts to create all necessary parent directories for a given path. If the directory already exists or if
+	there's an `OSError` during creation, it will silently continue without raising an exception.
+
+	Parameters
+	----------
+	pathFilename : Any
+		A path-like object or file object representing the path for which to create parent directories. If it's an IO stream
+		object, no directories will be created.
+
+	"""
+	if not isinstance(pathFilename, io.IOBase):
+		with contextlib.suppress(OSError):
+			Path(pathFilename).parent.mkdir(parents=True, exist_ok=True)
+
+def writeStringToHere(this: str, pathFilename: PathLike[Any] | PurePath) -> None:
+	"""Write a string to a file, creating parent directories as needed.
+
+	Parameters
+	----------
+	this : str
+		The string content to write to the file.
+	pathFilename : PathLike[Any] | PurePath
+		The path and filename where the string will be written.
+
+	"""
+	pathFilename = Path(pathFilename)
+	makeDirsSafely(pathFilename)
+	pathFilename.write_text(str(this), encoding='utf-8')