mapFolding 0.8.5__py3-none-any.whl → 0.9.0__py3-none-any.whl

mapFolding/someAssemblyRequired/_tool_Make.py

@@ -1,11 +1,24 @@
+"""
+AST Node Construction Utilities for Python Code Generation
+
+This module provides the Make class with static methods for creating AST nodes
+with sane defaults. It abstracts away the complexity of constructing AST nodes
+directly, making programmatic code generation more intuitive and less error-prone.
+
+The Make class serves as a factory for creating various types of AST nodes needed
+in code generation, transformation, and analysis workflows. Each method follows
+a consistent pattern that maps cleanly to Python's syntax while handling the
+details of AST node construction.
+"""
+
 from collections.abc import Sequence
 from mapFolding.someAssemblyRequired import (
 	ast_expr_Slice,
 	ast_Identifier,
-	ImaAnnotationType,
 	intORlist_ast_type_paramORstr_orNone,
 	intORstr_orNone,
 	list_ast_type_paramORstr_orNone,
+	str_nameDOTname,
 )
 from typing import Any
 import ast
@@ -29,71 +42,86 @@ class Make:
 	@staticmethod
 	def alias(name: ast_Identifier, asname: ast_Identifier | None = None) -> ast.alias:
 		return ast.alias(name, asname)
+
 	@staticmethod
-	def AnnAssign(target: ast.Attribute | ast.Name | ast.Subscript, annotation: ImaAnnotationType, value: ast.expr | None = None, **keywordArguments: int) -> ast.AnnAssign: # `simple: int`: uses a clever int-from-boolean to assign the correct value to the `simple` attribute. So, don't make it a method parameter.
+	def AnnAssign(target: ast.Attribute | ast.Name | ast.Subscript, annotation: ast.expr, value: ast.expr | None = None, **keywordArguments: int) -> ast.AnnAssign: # `simple: int`: uses a clever int-from-boolean to assign the correct value to the `simple` attribute. So, don't make it a method parameter.
 		return ast.AnnAssign(target, annotation, value, simple=int(isinstance(target, ast.Name)), **keywordArguments)
+
 	@staticmethod
 	def arg(identifier: ast_Identifier, annotation: ast.expr | None = None, **keywordArguments: intORstr_orNone) -> ast.arg:
 		return ast.arg(identifier, annotation, **keywordArguments)
+
 	@staticmethod
 	def argumentsSpecification(posonlyargs:list[ast.arg]=[], args:list[ast.arg]=[], vararg:ast.arg|None=None, kwonlyargs:list[ast.arg]=[], kw_defaults:list[ast.expr|None]=[None], kwarg:ast.arg|None=None, defaults:list[ast.expr]=[]) -> ast.arguments:
 		return ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)
+
 	@staticmethod
 	def Assign(listTargets: Any, value: ast.expr, **keywordArguments: intORstr_orNone) -> ast.Assign:
 		return ast.Assign(listTargets, value, **keywordArguments)
+
 	@staticmethod
 	def Attribute(value: ast.expr, *attribute: ast_Identifier, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Attribute:
 		""" If two `ast_Identifier` are joined by a dot `.`, they are _usually_ an `ast.Attribute`, but see `ast.ImportFrom`.
 		Parameters:
-			value: the part before the dot (Often `ast.Name`, but also `ast.Attribute`, `ast.Starred`, and `ast.Subscript`.)
+			value: the part before the dot (e.g., `ast.Name`.)
 			attribute: an `ast_Identifier` after a dot `.`; you can pass multiple `attribute` and they will be chained together.
 		"""
-		# TODO confirm the precision of the docstring.
-		def addDOTattribute(chain, identifier: ast_Identifier, context: ast.expr_context, **keywordArguments: int) -> ast.Attribute:
+		def addDOTattribute(chain: ast.expr, identifier: ast_Identifier, context: ast.expr_context, **keywordArguments: int) -> ast.Attribute:
 			return ast.Attribute(value=chain, attr=identifier, ctx=context, **keywordArguments)
 		buffaloBuffalo = addDOTattribute(value, attribute[0], context, **keywordArguments)
 		for identifier in attribute[1:None]:
 			buffaloBuffalo = addDOTattribute(buffaloBuffalo, identifier, context, **keywordArguments)
 		return buffaloBuffalo
+
 	@staticmethod
-	# TODO are the types for `callee` comprehensive?
-	# TODO is there an easier way to create precise typings for `ast`? I mean, it's a fucking closed system: there should be a lot of mystery involved.
-	def Call(callee: ast.Attribute | ast.Name | ast.Subscript, listArguments: Sequence[ast.expr] | None = None, list_astKeywords: Sequence[ast.keyword] | None = None) -> ast.Call:
+	def Call(callee: ast.expr, listArguments: Sequence[ast.expr] | None = None, list_astKeywords: Sequence[ast.keyword] | None = None) -> ast.Call:
 		return ast.Call(func=callee, args=list(listArguments) if listArguments else [], keywords=list(list_astKeywords) if list_astKeywords else [])
+
 	@staticmethod
 	def ClassDef(name: ast_Identifier, listBases: list[ast.expr]=[], list_keyword: list[ast.keyword]=[], body: list[ast.stmt]=[], decorator_list: list[ast.expr]=[], **keywordArguments: list_ast_type_paramORstr_orNone) -> ast.ClassDef:
 		return ast.ClassDef(name, listBases, list_keyword, body, decorator_list, **keywordArguments)
+
 	@staticmethod
 	def Constant(value: Any, **keywordArguments: intORstr_orNone) -> ast.Constant:
 		"""value: str|int|float|bool|None|bytes|bytearray|memoryview|complex|list|tuple|dict|set, or any other type that can be represented as a constant in Python."""
 		return ast.Constant(value, **keywordArguments)
+
 	@staticmethod
 	def Expr(value: ast.expr, **keywordArguments: int) -> ast.Expr:
 		return ast.Expr(value, **keywordArguments)
+
 	@staticmethod
 	def FunctionDef(name: ast_Identifier, argumentsSpecification:ast.arguments=ast.arguments(), body:list[ast.stmt]=[], decorator_list:list[ast.expr]=[], returns:ast.expr|None=None, **keywordArguments: intORlist_ast_type_paramORstr_orNone) -> ast.FunctionDef:
 		return ast.FunctionDef(name, argumentsSpecification, body, decorator_list, returns, **keywordArguments)
+
 	@staticmethod
-	def Import(moduleIdentifier: ast_Identifier, asname: ast_Identifier | None = None, **keywordArguments: int) -> ast.Import:
-		return ast.Import(names=[Make.alias(moduleIdentifier, asname)], **keywordArguments)
+	def Import(moduleWithLogicalPath: str_nameDOTname, asname: ast_Identifier | None = None, **keywordArguments: int) -> ast.Import:
+		return ast.Import(names=[Make.alias(moduleWithLogicalPath, asname)], **keywordArguments)
+
 	@staticmethod
-	def ImportFrom(moduleIdentifier: ast_Identifier, list_astAlias: list[ast.alias], **keywordArguments: int) -> ast.ImportFrom:
-		return ast.ImportFrom(moduleIdentifier, list_astAlias, **keywordArguments)
+	def ImportFrom(moduleWithLogicalPath: str_nameDOTname, list_astAlias: list[ast.alias], **keywordArguments: int) -> ast.ImportFrom:
+		return ast.ImportFrom(moduleWithLogicalPath, list_astAlias, **keywordArguments)
+
 	@staticmethod
 	def keyword(keywordArgument: ast_Identifier, value: ast.expr, **keywordArguments: int) -> ast.keyword:
 		return ast.keyword(arg=keywordArgument, value=value, **keywordArguments)
+
 	@staticmethod
 	def Module(body: list[ast.stmt] = [], type_ignores: list[ast.TypeIgnore] = []) -> ast.Module:
 		return ast.Module(body, type_ignores)
+
 	@staticmethod
 	def Name(identifier: ast_Identifier, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Name:
 		return ast.Name(identifier, context, **keywordArguments)
+
 	@staticmethod
 	def Return(value: ast.expr | None = None, **keywordArguments: int) -> ast.Return:
 		return ast.Return(value, **keywordArguments)
+
 	@staticmethod
 	def Subscript(value: ast.expr, slice: ast_expr_Slice, context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Subscript:
 		return ast.Subscript(value, slice, context, **keywordArguments)
+
 	@staticmethod
 	def Tuple(elements: Sequence[ast.expr] = [], context: ast.expr_context = ast.Load(), **keywordArguments: int) -> ast.Tuple:
 		return ast.Tuple(list(elements), context, **keywordArguments)

mapFolding/someAssemblyRequired/_tool_Then.py

@@ -1,67 +1,101 @@
+"""
+AST Node Transformation Actions for Python Code Manipulation
+
+This module provides the Then class with static methods for generating callable
+action functions that specify what to do with AST nodes that match predicates.
+These action functions are used primarily with NodeChanger and NodeTourist to
+transform or extract information from AST nodes.
+
+The module also contains the grab class that provides functions for modifying
+specific attributes of AST nodes while preserving their structure, enabling
+fine-grained control when transforming AST structures.
+
+Together, these classes provide a complete system for manipulating AST nodes
+once they have been identified using predicate functions from ifThis.
+"""
+
 from collections.abc import Callable, Sequence
 from mapFolding.someAssemblyRequired import ast_Identifier, astClassHasDOTvalue
 from typing import Any
 import ast
 
-class Then:
-	@staticmethod
-	def allOf(listActions: Sequence[Callable[[ast.AST], Any]]) -> Callable[[ast.AST], ast.AST]:
-		def workhorse(node: ast.AST) -> ast.AST:
-			for action in listActions: action(node)
-			return node
-		return workhorse
+class grab:
+	"""
+	Modify specific attributes of AST nodes while preserving the node structure.
 
-	@staticmethod
-	def appendTo(listOfAny: list[Any]) -> Callable[[ast.AST | ast_Identifier], list[Any]]:
-		def workhorse(node: ast.AST | ast_Identifier) -> list[Any]:
-			listOfAny.append(node)
-			return listOfAny
-		return workhorse
+	The grab class provides static methods that create transformation functions to modify
+	specific attributes of AST nodes. Unlike DOT which provides read-only access,
+	grab allows for targeted modifications of node attributes without replacing the
+	entire node.
 
+	Each method returns a function that takes a node, applies a transformation to a
+	specific attribute of that node, and returns the modified node. This enables fine-grained
+	control when transforming AST structures.
+	"""
 	@staticmethod
-	def DOTarg(action: Callable[[Any], Any]) -> Callable[[ast.arg | ast.keyword], ast.arg | ast.keyword]:
+	def argAttribute(action: Callable[[ast_Identifier | None], ast_Identifier]) -> Callable[[ast.arg | ast.keyword], ast.arg | ast.keyword]:
 		def workhorse(node: ast.arg | ast.keyword) -> ast.arg | ast.keyword:
 			node.arg = action(node.arg)
 			return node
 		return workhorse
+
 	@staticmethod
-	def DOTfunc(action: Callable[[Any], Any]) -> Callable[[ast.Call], ast.Call]:
+	def funcAttribute(action: Callable[[ast.expr], ast.expr]) -> Callable[[ast.Call], ast.Call]:
 		def workhorse(node: ast.Call) -> ast.Call:
 			node.func = action(node.func)
 			return node
 		return workhorse
+
 	@staticmethod
-	def DOTid(action: Callable[[Any], Any]) -> Callable[[ast.Name], ast.Name]:
+	def idAttribute(action: Callable[[ast_Identifier], ast_Identifier]) -> Callable[[ast.Name], ast.Name]:
 		def workhorse(node: ast.Name) -> ast.Name:
 			node.id = action(node.id)
 			return node
 		return workhorse
+
 	@staticmethod
-	def DOTtarget(action: Callable[[Any], Any]) -> Callable[[ast.AnnAssign | ast.AugAssign], ast.AnnAssign | ast.AugAssign]:
-		def workhorse(node: ast.AnnAssign | ast.AugAssign) -> ast.AnnAssign | ast.AugAssign:
-			node.target = action(node.target)
-			return node
-		return workhorse
-	@staticmethod
-	def DOTvalue(action: Callable[[Any], Any]) -> Callable[[astClassHasDOTvalue], astClassHasDOTvalue]:
+	def valueAttribute(action: Callable[[Any | ast.expr | bool | None], Any]) -> Callable[[astClassHasDOTvalue], astClassHasDOTvalue]:
 		def workhorse(node: astClassHasDOTvalue) -> astClassHasDOTvalue:
 			node.value = action(node.value)
 			return node
 		return workhorse
 
+class Then:
+	"""
+	Provide action functions that specify what to do with AST nodes that match predicates.
+
+	The Then class contains static methods that generate action functions used with
+	NodeChanger and NodeTourist to transform or extract information from AST nodes
+	that match specific predicates. These actions include node replacement, insertion,
+	extraction, and collection operations.
+
+	When paired with predicates from the ifThis class, Then methods complete the
+	pattern-matching-and-action workflow for AST manipulation.
+	"""
 	@staticmethod
-	def getIt(node: ast.AST) -> ast.AST | ast_Identifier:
+	def appendTo(listOfAny: list[Any]) -> Callable[[ast.AST | ast_Identifier], list[Any]]:
+		def workhorse(node: ast.AST | ast_Identifier) -> list[Any]:
+			listOfAny.append(node)
+			return listOfAny
+		return workhorse
+
+	@staticmethod
+	def extractIt(node: ast.AST) -> ast.AST | ast_Identifier:
 		return node
+
 	@staticmethod
 	def insertThisAbove(list_astAST: Sequence[ast.AST]) -> Callable[[ast.AST], Sequence[ast.AST]]:
 		return lambda aboveMe: [*list_astAST, aboveMe]
+
 	@staticmethod
 	def insertThisBelow(list_astAST: Sequence[ast.AST]) -> Callable[[ast.AST], Sequence[ast.AST]]:
 		return lambda belowMe: [belowMe, *list_astAST]
+
 	@staticmethod
 	def removeIt(_node: ast.AST) -> None: return None
+
 	@staticmethod
-	def replaceWith(astAST: ast.AST | ast_Identifier) -> Callable[[ast.AST], ast.AST | ast_Identifier]:
+	def replaceWith(astAST: Any) -> Callable[[Any], Any]:
 		return lambda _replaceMe: astAST
 
 	@staticmethod