hunterMakesPy 0.1.2__tar.gz → 0.2.1__tar.gz

{huntermakespy-0.1.2 → huntermakespy-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hunterMakesPy
-Version: 0.1.2
+Version: 0.2.1
 Summary: Easy Python functions making making functional Python functions easier.
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
@@ -32,7 +33,7 @@ License-File: LICENSE
 Requires-Dist: charset_normalizer
 Requires-Dist: more_itertools
 Requires-Dist: numpy
-Requires-Dist: python_minifier
+Requires-Dist: python_minifier; python_version < "3.14"
 Provides-Extra: development
 Requires-Dist: mypy; extra == "development"
 Requires-Dist: pyupgrade; extra == "development"
@@ -73,7 +74,7 @@ def findConfiguration(configName: str) -> dict[str, str] | None:
 
 config = raiseIfNone(
     findConfiguration("database"),
-    "Configuration 'database' is required but not found"
+    "I could not find Configuration 'database', but I need it to continue."
 )
 ```
 
@@ -82,19 +83,19 @@ config = raiseIfNone(
 Parameter validation, integer parsing, and concurrency handling.
 
 ```python
-from hunterMakesPy import defineConcurrencyLimit, intInnit, oopsieKwargsie
+import hunterMakesPy as humpy
 
 # Smart concurrency limit calculation
-cpuLimit = defineConcurrencyLimit(limit=0.75)  # Use 75% of available CPUs
-cpuLimit = defineConcurrencyLimit(limit=True)  # Use exactly 1 CPU
-cpuLimit = defineConcurrencyLimit(limit=4)     # Use exactly 4 CPUs
+cpuLimit = humpy.defineConcurrencyLimit(limit=0.75)  # Use 75% of available CPUs
+cpuLimit = humpy.defineConcurrencyLimit(limit=True)  # Use exactly 1 CPU
+cpuLimit = humpy.defineConcurrencyLimit(limit=4)     # Use exactly 4 CPUs
 
 # Robust integer validation
-validatedIntegers = intInnit([1, "2", 3.0, "4"], "port_numbers")
+validatedIntegers = humpy.intInnit([1, "2", 3.0, "4"], "port_numbers")
 
 # String-to-boolean conversion for configuration
 userInput = "True"
-booleanValue = oopsieKwargsie(userInput)  # Returns True
+booleanValue = humpy.oopsieKwargsie(userInput)  # Returns True
 ```
 
 ## File System Utilities
@@ -102,20 +103,15 @@ booleanValue = oopsieKwargsie(userInput)  # Returns True
 Safe file operations and dynamic module importing.
 
 ```python
-from hunterMakesPy import (
-    importLogicalPath2Identifier,
-    importPathFilename2Identifier,
-    makeDirsSafely,
-    writeStringToHere
-)
+import hunterMakesPy as humpy
 
 # Dynamic imports
-gcdFunction = importLogicalPath2Identifier("math", "gcd")
-customFunction = importPathFilename2Identifier("path/to/module.py", "functionName")
+gcdFunction = humpy.importLogicalPath2Identifier("math", "gcd")
+customFunction = humpy.importPathFilename2Identifier("path/to/module.py", "functionName")
 
 # Safe file operations
 pathFilename = Path("deep/nested/directory/file.txt")
-writeStringToHere("content", pathFilename)  # Creates directories automatically
+humpy.writeStringToHere("content", pathFilename)  # Creates directories automatically
 ```
 
 ## Data Structure Manipulation
@@ -123,21 +119,21 @@ writeStringToHere("content", pathFilename)  # Creates directories automatically
 Utilities for string extraction, data flattening, and array compression.
 
 ```python
-from hunterMakesPy import stringItUp, updateExtendPolishDictionaryLists, autoDecodingRLE
+import hunterMakesPy as humpy
 import numpy
 
 # Extract all strings from nested data structures
 nestedData = {"config": [1, "host", {"port": 8080}], "users": ["alice", "bob"]}
-allStrings = stringItUp(nestedData)  # ['config', 'host', 'port', 'users', 'alice', 'bob']
+allStrings = humpy.stringItUp(nestedData)  # ['config', 'host', 'port', 'users', 'alice', 'bob']
 
 # Merge dictionaries containing lists
-dictionaryAlpha = {"servers": ["web1", "web2"], "databases": ["db1"]}
-dictionaryBeta = {"servers": ["web3"], "databases": ["db2", "db3"]}
-merged = updateExtendPolishDictionaryLists(dictionaryAlpha, dictionaryBeta, destroyDuplicates=True)
+dictionaryAlpha = {"servers": ["chicago", "tokyo"], "databases": ["elm"]}
+dictionaryBeta = {"servers": ["mumbai"], "databases": ["oak", "cedar"]}
+merged = humpy.updateExtendPolishDictionaryLists(dictionaryAlpha, dictionaryBeta, destroyDuplicates=True)
 
 # Compress NumPy arrays with run-length encoding
 arrayData = numpy.array([1, 2, 3, 4, 5, 5, 5, 6, 7, 8, 9])
-compressed = autoDecodingRLE(arrayData)  # "[1,*range(2,6)]+[5]*2+[*range(6,10)]"
+compressed = humpy.autoDecodingRLE(arrayData)  # "[1,*range(2,6)]+[5]*2+[*range(6,10)]"
 ```
 
 ## Testing
@@ -145,7 +141,7 @@ compressed = autoDecodingRLE(arrayData)  # "[1,*range(2,6)]+[5]*2+[*range(6,10)]
 The package includes comprehensive test suites that you can import and run:
 
 ```python
-from hunterMakesPy.pytestForYourUse import (
+from hunterMakesPy.tests.test_parseParameters import (
     PytestFor_defineConcurrencyLimit,
     PytestFor_intInnit,
     PytestFor_oopsieKwargsie
@@ -157,8 +153,9 @@ for nameOfTest, callablePytest in listOfTests:
     callablePytest()
 
 # Or test your own compatible functions
-@pytest.mark.parametrize("nameOfTest,callablePytest",
-                        PytestFor_intInnit(callableToTest=myFunction))
+@pytest.mark.parametrize(
+  "nameOfTest,callablePytest"
+  , PytestFor_intInnit(callableToTest=myFunction))
 def test_myFunction(nameOfTest, callablePytest):
     callablePytest()
 ```

{huntermakespy-0.1.2 → huntermakespy-0.2.1}/README.md

@@ -28,7 +28,7 @@ def findConfiguration(configName: str) -> dict[str, str] | None:
 
 config = raiseIfNone(
     findConfiguration("database"),
-    "Configuration 'database' is required but not found"
+    "I could not find Configuration 'database', but I need it to continue."
 )
 ```
 
@@ -37,19 +37,19 @@ config = raiseIfNone(
 Parameter validation, integer parsing, and concurrency handling.
 
 ```python
-from hunterMakesPy import defineConcurrencyLimit, intInnit, oopsieKwargsie
+import hunterMakesPy as humpy
 
 # Smart concurrency limit calculation
-cpuLimit = defineConcurrencyLimit(limit=0.75)  # Use 75% of available CPUs
-cpuLimit = defineConcurrencyLimit(limit=True)  # Use exactly 1 CPU
-cpuLimit = defineConcurrencyLimit(limit=4)     # Use exactly 4 CPUs
+cpuLimit = humpy.defineConcurrencyLimit(limit=0.75)  # Use 75% of available CPUs
+cpuLimit = humpy.defineConcurrencyLimit(limit=True)  # Use exactly 1 CPU
+cpuLimit = humpy.defineConcurrencyLimit(limit=4)     # Use exactly 4 CPUs
 
 # Robust integer validation
-validatedIntegers = intInnit([1, "2", 3.0, "4"], "port_numbers")
+validatedIntegers = humpy.intInnit([1, "2", 3.0, "4"], "port_numbers")
 
 # String-to-boolean conversion for configuration
 userInput = "True"
-booleanValue = oopsieKwargsie(userInput)  # Returns True
+booleanValue = humpy.oopsieKwargsie(userInput)  # Returns True
 ```
 
 ## File System Utilities
@@ -57,20 +57,15 @@ booleanValue = oopsieKwargsie(userInput)  # Returns True
 Safe file operations and dynamic module importing.
 
 ```python
-from hunterMakesPy import (
-    importLogicalPath2Identifier,
-    importPathFilename2Identifier,
-    makeDirsSafely,
-    writeStringToHere
-)
+import hunterMakesPy as humpy
 
 # Dynamic imports
-gcdFunction = importLogicalPath2Identifier("math", "gcd")
-customFunction = importPathFilename2Identifier("path/to/module.py", "functionName")
+gcdFunction = humpy.importLogicalPath2Identifier("math", "gcd")
+customFunction = humpy.importPathFilename2Identifier("path/to/module.py", "functionName")
 
 # Safe file operations
 pathFilename = Path("deep/nested/directory/file.txt")
-writeStringToHere("content", pathFilename)  # Creates directories automatically
+humpy.writeStringToHere("content", pathFilename)  # Creates directories automatically
 ```
 
 ## Data Structure Manipulation
@@ -78,21 +73,21 @@ writeStringToHere("content", pathFilename)  # Creates directories automatically
 Utilities for string extraction, data flattening, and array compression.
 
 ```python
-from hunterMakesPy import stringItUp, updateExtendPolishDictionaryLists, autoDecodingRLE
+import hunterMakesPy as humpy
 import numpy
 
 # Extract all strings from nested data structures
 nestedData = {"config": [1, "host", {"port": 8080}], "users": ["alice", "bob"]}
-allStrings = stringItUp(nestedData)  # ['config', 'host', 'port', 'users', 'alice', 'bob']
+allStrings = humpy.stringItUp(nestedData)  # ['config', 'host', 'port', 'users', 'alice', 'bob']
 
 # Merge dictionaries containing lists
-dictionaryAlpha = {"servers": ["web1", "web2"], "databases": ["db1"]}
-dictionaryBeta = {"servers": ["web3"], "databases": ["db2", "db3"]}
-merged = updateExtendPolishDictionaryLists(dictionaryAlpha, dictionaryBeta, destroyDuplicates=True)
+dictionaryAlpha = {"servers": ["chicago", "tokyo"], "databases": ["elm"]}
+dictionaryBeta = {"servers": ["mumbai"], "databases": ["oak", "cedar"]}
+merged = humpy.updateExtendPolishDictionaryLists(dictionaryAlpha, dictionaryBeta, destroyDuplicates=True)
 
 # Compress NumPy arrays with run-length encoding
 arrayData = numpy.array([1, 2, 3, 4, 5, 5, 5, 6, 7, 8, 9])
-compressed = autoDecodingRLE(arrayData)  # "[1,*range(2,6)]+[5]*2+[*range(6,10)]"
+compressed = humpy.autoDecodingRLE(arrayData)  # "[1,*range(2,6)]+[5]*2+[*range(6,10)]"
 ```
 
 ## Testing
@@ -100,7 +95,7 @@ compressed = autoDecodingRLE(arrayData)  # "[1,*range(2,6)]+[5]*2+[*range(6,10)]
 The package includes comprehensive test suites that you can import and run:
 
 ```python
-from hunterMakesPy.pytestForYourUse import (
+from hunterMakesPy.tests.test_parseParameters import (
     PytestFor_defineConcurrencyLimit,
     PytestFor_intInnit,
     PytestFor_oopsieKwargsie
@@ -112,8 +107,9 @@ for nameOfTest, callablePytest in listOfTests:
     callablePytest()
 
 # Or test your own compatible functions
-@pytest.mark.parametrize("nameOfTest,callablePytest",
-                        PytestFor_intInnit(callableToTest=myFunction))
+@pytest.mark.parametrize(
+  "nameOfTest,callablePytest"
+  , PytestFor_intInnit(callableToTest=myFunction))
 def test_myFunction(nameOfTest, callablePytest):
     callablePytest()
 ```

{huntermakespy-0.1.2 → huntermakespy-0.2.1}/hunterMakesPy/__init__.py

@@ -7,6 +7,7 @@ This package provides:
 - Utilities for string extraction from nested data structures and merging dictionaries of lists.
 
 """
+# pyright: reportUnusedImport=false
 from hunterMakesPy.theTypes import identifierDotAttribute as identifierDotAttribute
 
 from hunterMakesPy.coping import PackageSettings as PackageSettings, raiseIfNone as raiseIfNone
@@ -18,7 +19,11 @@ from hunterMakesPy.filesystemToolkit import (importLogicalPath2Identifier as imp
 	importPathFilename2Identifier as importPathFilename2Identifier, makeDirsSafely as makeDirsSafely,
 	writeStringToHere as writeStringToHere)
 
-from hunterMakesPy.dataStructures import (autoDecodingRLE as autoDecodingRLE, stringItUp as stringItUp,
-	updateExtendPolishDictionaryLists as updateExtendPolishDictionaryLists)
+from hunterMakesPy.dataStructures import stringItUp as stringItUp, updateExtendPolishDictionaryLists as updateExtendPolishDictionaryLists
+
+import sys
+
+if sys.version_info < (3, 14):
+    from hunterMakesPy.dataStructures import autoDecodingRLE as autoDecodingRLE
 
 from hunterMakesPy._theSSOT import settingsPackage

huntermakespy-0.2.1/hunterMakesPy/dataStructures.py

@@ -0,0 +1,268 @@
+"""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 re as regex
+import sys
+
+if sys.version_info < (3, 14):
+	import python_minifier
+
+	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."""
+				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<multiply>\\d+)\\)(?P<bracketBehind>])|"
+			# Pattern 2: Bracket or start ahead, comma behind  # noqa: ERA001
+			"(?P<bracketOrStartAhead>\\[|^.)\\((?P<malkovichMalkovich>\\d+),(?P<multiplyIDK>\\d+)\\)(?P<joinBehind>,)|"
+			# Pattern 3: Bracket ahead, bracket behind  # noqa: ERA001
+			"(?P<bracketAhead>\\[)\\((?P<malkovichMalkovichMalkovich>\\d+),(?P<multiply_whatever>\\d+)\\)(?P<bracketBehindBracketBehind>])|"
+			# Pattern 4: Comma ahead, comma behind  # noqa: ERA001
+			"(?P<joinAheadJoinAhead>,)\\((?P<malkovichMalkovichMalkovichMalkovich>\\d+),(?P<multiplyOrSomething>\\d+)\\)(?P<joinBehindJoinBehind>,)"
+			")"
+		)
+
+		def replacementByContext(match: regex.Match[str]) -> str:
+			"""Generate replacement string based on context patterns."""
+			elephino = match.groupdict()
+			joinAhead = elephino.get('joinAhead') or elephino.get('joinAheadJoinAhead')
+			malkovich = elephino.get('malkovich') or elephino.get('malkovichMalkovich') or elephino.get('malkovichMalkovichMalkovich') or elephino.get('malkovichMalkovichMalkovichMalkovich')
+			multiply = elephino.get('multiply') or elephino.get('multiplyIDK') or elephino.get('multiply_whatever') or elephino.get('multiplyOrSomething')
+			joinBehind = elephino.get('joinBehind') or elephino.get('joinBehindJoinBehind')
+
+			replaceAhead = "]+[" if joinAhead == "," else "["
+
+			replaceBehind = "+[" if joinBehind == "," else ""
+
+			return f"{replaceAhead}{malkovich}]*{multiply}{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:
+				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-0.1.2 → huntermakespy-0.2.1}/hunterMakesPy/filesystemToolkit.py

@@ -1,6 +1,6 @@
 """File system and module import utilities.
 
-This module provides basic file I/O utilities such as importing callables from modules, and safely creating directories.
+This module provides basic file I/O utilities such as importing callables from modules, safely creating directories, and writing to files or streams (pipes).
 
 """
 
@@ -97,17 +97,25 @@ def makeDirsSafely(pathFilename: Any) -> None:
 		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.
+def writeStringToHere(this: str, pathFilename: PathLike[Any] | PurePath | io.TextIOBase) -> None:
+	"""Write a string to a file or text stream.
+
+	This function writes a string to either a file path or an open text stream. For file paths, it creates parent directories as
+	needed and writes with UTF-8 encoding. For text streams, it writes directly to the stream and flushes the buffer.
 
 	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.
+		The string content to write.
+	pathFilename : PathLike[Any] | PurePath | io.TextIOBase
+		The target destination: either a file path or an open text stream.
 
 	"""
-	pathFilename = Path(pathFilename)
-	makeDirsSafely(pathFilename)
-	pathFilename.write_text(str(this), encoding='utf-8')
+	if isinstance(pathFilename, io.TextIOBase):
+		pathFilename.write(str(this))
+		pathFilename.flush()
+	else:
+		pathFilename = Path(pathFilename)
+		makeDirsSafely(pathFilename)
+		pathFilename.write_text(str(this), encoding='utf-8')
+