hunterMakesPy 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

hunterMakesPy/Z0Z_CallableFunction.py

@@ -0,0 +1,70 @@
+"""Protocols for callable functions with full type safety."""
+from collections.abc import Callable
+from types import CellType, CodeType, MethodType
+from typing import Any, overload, ParamSpec, Protocol, runtime_checkable, Self, TypeVar, TypeVarTuple
+import sys
+
+#======== Stolen, uh, I mean copied from typeshed:stdlib\_typeshed\__init__.pyi ========
+type AnnotationForm = Any
+
+if sys.version_info >= (3, 14):
+	from annotationlib import Format
+
+# NOTE These return annotations, which can be arbitrary objects
+	type AnnotateFunc = Callable[[Format], dict[str, AnnotationForm]]
+	type EvaluateFunc = Callable[[Format], AnnotationForm]
+#======== End stolen, uh, I mean copied from typeshed:stdlib\_typeshed\__init__.pyi ========
+
+@runtime_checkable
+class CallableFunction[**P, R](Protocol):
+	"""A Protocol representing callable functions with descriptor support.
+
+	Mimics types.FunctionType while being a drop-in replacement for `collections.abc.Callable`. Includes all standard function
+	attributes and the descriptor protocol for proper method binding.
+
+	Note: @runtime_checkable only validates attribute presence, not signatures.
+	"""
+
+# NOTE: The eehhhh, IDK... section
+	__doc__: str | None
+	__wrapped__: Any  # For functools.wraps support
+# NOTE: End eehhhh, IDK... section
+
+	@property
+	def __closure__(self) -> tuple[CellType, ...] | None:
+		"""Tuple of cells that contain bindings for the function's free variables."""
+		...
+	__code__: CodeType
+	__defaults__: tuple[Any, ...] | None
+	__dict__: dict[str, Any]
+	@property
+	def __globals__(self) -> dict[str, Any]:
+		"""The global namespace in which the function was defined."""
+		...
+	__name__: str
+	__qualname__: str
+	__annotations__: dict[str, AnnotationForm]
+	if sys.version_info >= (3, 14):
+		__annotate__: AnnotateFunc | None
+	__kwdefaults__: dict[str, Any] | None
+	@property
+	def __builtins__(self) -> dict[str, Any]:
+		"""The built-in namespace in which the function was defined."""
+		...
+	__type_params__: tuple[TypeVar | ParamSpec | TypeVarTuple, ...]
+	__module__: str
+
+	def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+		"""Execute the callable with the given arguments."""
+		...
+
+	@overload
+	def __get__(self, instance: None, owner: type, /) -> Self: ...
+	@overload
+	def __get__(self, instance: object, owner: type | None = None, /) -> MethodType: ...
+	def __get__(self, instance: object | None, owner: type | None = None) -> Self | MethodType:
+		"""Descriptor protocol for method binding.
+
+		Returns self when accessed on the class, or a bound MethodType when accessed on an instance.
+		"""
+		...

hunterMakesPy/__init__.py

@@ -8,15 +8,22 @@ This package provides:
 
 """
 
-from hunterMakesPy.theTypes import identifierDotAttribute as identifierDotAttribute, Ordinals as Ordinals
+# isort: split
+from hunterMakesPy.theTypes import (
+	CallableFunction as CallableFunction, identifierDotAttribute as identifierDotAttribute, Ordinals as Ordinals)
 
+# isort: split
 from hunterMakesPy.coping import PackageSettings as PackageSettings, raiseIfNone as raiseIfNone
 
+# isort: split
 from hunterMakesPy.parseParameters import defineConcurrencyLimit, intInnit, oopsieKwargsie
 
+# isort: split
 from hunterMakesPy.filesystemToolkit import (
 	importLogicalPath2Identifier, importPathFilename2Identifier, makeDirsSafely, writePython, writeStringToHere)
 
+# isort: split
 from hunterMakesPy.dataStructures import autoDecodingRLE, stringItUp, updateExtendPolishDictionaryLists
 
+# isort: split
 from hunterMakesPy._theSSOT import settingsPackage  # pyright: ignore[reportUnusedImport]

hunterMakesPy/coping.py

@@ -2,14 +2,12 @@
 from importlib.util import find_spec
 from pathlib import Path
 from tomllib import loads as tomllib_loads
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING
 import dataclasses
 
 if TYPE_CHECKING:
 	from importlib.machinery import ModuleSpec
 
-TypeSansNone = TypeVar('TypeSansNone')
-
 def getIdentifierPackagePACKAGING(identifierPackageFALLBACK: str) -> str:
 	"""Get package name from pyproject.toml or fallback to provided value."""
 	try:
@@ -85,7 +83,7 @@ class PackageSettings:
 		if self.pathPackage == Path() and self.identifierPackage:
 			self.pathPackage = getPathPackageINSTALLING(self.identifierPackage)
 
-def raiseIfNone(expression: TypeSansNone | None, errorMessage: str | None = None) -> TypeSansNone:
+def raiseIfNone[TypeSansNone](expression: TypeSansNone | None, errorMessage: str | None = None) -> TypeSansNone:
 	"""Convert the `expression` return annotation from '`cerPytainty | None`' to '`cerPytainty`' because `expression` cannot be `None`; `raise` an `Exception` if you're wrong.
 
 	The Python interpreter evaluates `expression` to a value: think of a function call or an attribute access. You can use

hunterMakesPy/pytestForYourUse.py

@@ -6,5 +6,4 @@ Note: These test functions are now in `hunterMakesPy.tests` with all other tests
 """
 
 from hunterMakesPy.tests.test_parseParameters import (
-	PytestFor_defineConcurrencyLimit as PytestFor_defineConcurrencyLimit, PytestFor_intInnit as PytestFor_intInnit,
-	PytestFor_oopsieKwargsie as PytestFor_oopsieKwargsie)
+	PytestFor_defineConcurrencyLimit, PytestFor_intInnit, PytestFor_oopsieKwargsie)

hunterMakesPy/tests/conftest.py

@@ -1,3 +1,11 @@
+"""Configuration and fixtures for pytest.
+
+(AI generated docstring)
+
+This module provides shared fixtures and utility functions for the test suite,
+including data paths, source code samples, and standardized assertion helpers.
+
+"""
 # pyright: standard
 from collections.abc import Callable
 from typing import Any
@@ -6,11 +14,26 @@ import pathlib
 import pytest
 
 # SSOT for test data paths and filenames
-pathDataSamples = pathlib.Path("hunterMakesPy/tests/dataSamples")
+pathDataSamples: pathlib.Path = pathlib.Path("hunterMakesPy/tests/dataSamples")
 
 # Fixture to provide a temporary directory for filesystem tests
 @pytest.fixture
 def pathTmpTesting(tmp_path: pathlib.Path) -> pathlib.Path:
+	"""Provide a temporary directory for filesystem tests.
+
+	(AI generated docstring)
+
+	Parameters
+	----------
+	tmp_path : pathlib.Path
+		The pytest built-in temporary path fixture.
+
+	Returns
+	-------
+	pathTmpTesting : pathlib.Path
+		The path to the temporary directory.
+
+	"""
 	return tmp_path
 
 # Fixture for predictable Python source code samples
@@ -44,7 +67,27 @@ def listFileContentsFibonacci() -> list[str]:
 	return ['fibonacci8', 'fibonacci13', 'fibonacci21', 'fibonacci34']
 
 def uniformTestFailureMessage(expected: Any, actual: Any, functionName: str, *arguments: Any, **keywordArguments: Any) -> str:
-	"""Format assertion message for any test comparison."""
+	"""Format assertion message for any test comparison.
+
+	Parameters
+	----------
+	expected : Any
+		The expected value or outcome.
+	actual : Any
+		The actual value or outcome received.
+	functionName : str
+		The name of the function or test case being executed.
+	*arguments : Any
+		Positional arguments passed to the function having its return value checked.
+	**keywordArguments : Any
+		Keyword arguments passed to the function having its return value checked.
+
+	Returns
+	-------
+	message : str
+		A formatted failure message detailing the expectation vs reality.
+
+	"""
 	listArgumentComponents: list[str] = [str(parameter) for parameter in arguments]
 	listKeywordComponents: list[str] = [f"{key}={value}" for key, value in keywordArguments.items()]
 	joinedArguments: str = ', '.join(listArgumentComponents + listKeywordComponents)
@@ -54,7 +97,22 @@ def uniformTestFailureMessage(expected: Any, actual: Any, functionName: str, *ar
 			f"Got: {actual}")
 
 def standardizedEqualTo(expected: Any, functionTarget: Callable[..., Any], *arguments: Any, **keywordArguments: Any) -> None:
-	"""Template for most tests to compare the actual outcome with the expected outcome, including expected errors."""
+	"""Template for most tests to compare actual outcome with expected outcome.
+
+	Includes handling for expected errors/exceptions.
+
+	Parameters
+	----------
+	expected : Any
+		The expected return value, or an Exception type if an error is expected.
+	functionTarget : Callable[..., Any]
+		The function to call and test.
+	*arguments : Any
+		Positional arguments to pass to `functionTarget`.
+	**keywordArguments : Any
+		Keyword arguments to pass to `functionTarget`.
+
+	"""
 	if type(expected) == type[Exception]:  # noqa: E721
 		messageExpected: str = expected.__name__
 	else:
@@ -63,7 +121,23 @@ def standardizedEqualTo(expected: Any, functionTarget: Callable[..., Any], *argu
 	try:
 		messageActual = actual = functionTarget(*arguments, **keywordArguments)
 	except Exception as actualError:
-		messageActual: str = type(actualError).__name__
+		messageActual = type(actualError).__name__
 		actual = type(actualError)
 
-	assert actual == expected, uniformTestFailureMessage(messageExpected, messageActual, functionTarget.__name__, *arguments, **keywordArguments)
+	functionName: str = getattr(functionTarget, "__name__", functionTarget.__class__.__name__)
+	assert actual == expected, uniformTestFailureMessage(messageExpected, messageActual, functionName, *arguments, **keywordArguments)
+
+# Why I wish I could figure out how to implement standardized* test functions.
+# ruff: noqa: ERA001
+	# standardizedEqualTo(expected, updateExtendPolishDictionaryLists, *value_dictionaryLists, **keywordArguments)
+# NOTE one line of code with `standardizedEqualTo` (above) replaced the following ten lines of code. Use `standardizedEqualTo`.
+	# if isinstance(expected, type) and issubclass(expected, Exception):
+	#	 with pytest.raises(expected):
+	#		 updateExtendPolishDictionaryLists(*value_dictionaryLists, **keywordArguments)
+	# else:
+	#	 result = updateExtendPolishDictionaryLists(*value_dictionaryLists, **keywordArguments)
+	#	 if description == "Set values":  # Special handling for unordered sets
+	#		 for key in result:
+	#			 assert sorted(result[key]) == sorted(expected[key])
+	#	 else:
+	#		 assert result == expected