astToolkit 0.1.0__py3-none-any.whl

astToolkit/_toolIfThis.py

@@ -0,0 +1,192 @@
+"""
+AST Node Predicate and Access Utilities for Pattern Matching and Traversal
+
+This module provides utilities for accessing and matching AST nodes in a consistent way. It contains three primary
+classes:
+
+1. DOT: Provides consistent accessor methods for AST node attributes across different node types, simplifying the access
+	to node properties.
+
+2. be: Offers type-guard functions that verify AST node types, enabling safe type narrowing for static type checking and
+	improving code safety.
+
+3. ifThis: Contains predicate functions for matching AST nodes based on various criteria, enabling precise targeting of
+	nodes for analysis or transformation.
+
+These utilities form the foundation of the pattern-matching component in the AST manipulation framework, working in
+conjunction with the NodeChanger and NodeTourist classes to enable precise and targeted code transformations. Together,
+they implement a declarative approach to AST manipulation that separates node identification (ifThis), type verification
+(be), and data access (DOT).
+"""
+
+from collections.abc import Callable
+from astToolkit import ast_Identifier, Be, DOT, ImaCallToName
+from typing import Any, TypeGuard
+import ast
+
+class IfThis:
+	"""
+	Provide predicate functions for matching and filtering AST nodes based on various criteria.
+
+	The ifThis class contains static methods that generate predicate functions used to test whether AST nodes match
+	specific criteria. These predicates can be used with NodeChanger and NodeTourist to identify and process specific
+	patterns in the AST.
+
+	The class provides predicates for matching various node types, attributes, identifiers, and structural patterns,
+	enabling precise targeting of AST elements for analysis or transformation.
+	"""
+	@staticmethod
+	def is_arg_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.arg] | bool]:
+		"""see also `isArgument_Identifier`"""
+		return lambda node: Be.arg(node) and IfThis.isIdentifier(identifier)(DOT.arg(node))
+	@staticmethod
+	def is_keyword_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.keyword] | bool]:
+		"""see also `isArgument_Identifier`"""
+		return lambda node: Be.keyword(node) and IfThis.isIdentifier(identifier)(DOT.arg(node))
+
+	@staticmethod
+	def isAnnAssign_targetIs(targetPredicate: Callable[[ast.expr], TypeGuard[ast.expr] | bool]) -> Callable[[ast.AST], TypeGuard[ast.AnnAssign] | bool]:
+		def workhorse(node: ast.AST) -> TypeGuard[ast.AnnAssign] | bool:
+			return Be.AnnAssign(node) and targetPredicate(DOT.target(node))
+		return workhorse
+
+	@staticmethod
+	def isArgument_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.arg | ast.keyword] | bool]:
+		return lambda node: (Be.arg(node) or Be.keyword(node)) and IfThis.isIdentifier(identifier)(DOT.arg(node))
+
+	@staticmethod
+	def isAssignAndTargets0Is(targets0Predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], TypeGuard[ast.AnnAssign] | bool]:
+		""" `node` is `ast.Assign` and `node.targets[0]` matches `targets0Predicate`."""
+		return lambda node: Be.Assign(node) and targets0Predicate(node.targets[0])
+	@staticmethod
+	def isAssignAndValueIs(valuePredicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], TypeGuard[ast.Assign] | bool]:
+		""" `node` is `ast.Assign` and `node.value` matches `valuePredicate`. """
+		return lambda node: Be.Assign(node) and valuePredicate(DOT.value(node))
+
+	@staticmethod
+	def isAttribute_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Attribute] | bool]:
+		""" 1. `node` is `ast.Attribute`,
+			2. zero or more direct descendants in an unbroken chain are `ast.Attribute`, `ast.Subscript`, or `ast.Starred`,
+			3. the direct descendant chain ends with `ast.Name`, and
+			4. the `ast.Name` `id` attribute is `identifier`."""
+		def workhorse(node: ast.AST) -> TypeGuard[ast.Attribute]:
+			return Be.Attribute(node) and IfThis.isNestedName_Identifier(identifier)(DOT.value(node))
+		return workhorse
+	@staticmethod
+	def isAttributeName(node: ast.AST) -> TypeGuard[ast.Attribute]:
+		""" Displayed as Name.attribute."""
+		return Be.Attribute(node) and Be.Name(DOT.value(node))
+	@staticmethod
+	def isAttributeNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Attribute] | bool]:
+		return lambda node: IfThis.isAttributeName(node) and IfThis.isName_Identifier(namespace)(DOT.value(node)) and IfThis.isIdentifier(identifier)(DOT.attr(node))
+
+	@staticmethod
+	def isAttributeNamespace_IdentifierLessThanOrEqual(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+		return lambda node: (Be.Compare(node)
+					and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(node.left)
+					and Be.LtE(node.ops[0]))
+
+	@staticmethod
+	def isAugAssignAndTargetIs(targetPredicate: Callable[[ast.expr], TypeGuard[ast.expr] | bool]) -> Callable[[ast.AST], TypeGuard[ast.AugAssign] | bool]:
+		def workhorse(node: ast.AST) -> TypeGuard[ast.AugAssign] | bool:
+			return Be.AugAssign(node) and targetPredicate(DOT.target(node))
+		return workhorse
+
+	@staticmethod
+	def isCall_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ImaCallToName] | bool]:
+		def workhorse(node: ast.AST) -> TypeGuard[ImaCallToName] | bool:
+			return IfThis.isCallToName(node) and IfThis.isIdentifier(identifier)(DOT.id(DOT.func(node)))
+		return workhorse
+
+	@staticmethod
+	def isCallAttributeNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Call] | bool]:
+		def workhorse(node: ast.AST) -> TypeGuard[ast.Call] | bool:
+			return Be.Call(node) and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(DOT.func(node))
+		return workhorse
+	@staticmethod
+	def isCallToName(node: ast.AST) -> TypeGuard[ImaCallToName]:
+		return Be.Call(node) and Be.Name(DOT.func(node))
+
+	@staticmethod
+	def isClassDef_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.ClassDef] | bool]:
+		return lambda node: Be.ClassDef(node) and IfThis.isIdentifier(identifier)(DOT.name(node))
+
+	@staticmethod
+	def isConstant_value(value: Any) -> Callable[[ast.AST], TypeGuard[ast.Constant] | bool]:
+		return lambda node: Be.Constant(node) and DOT.value(node) == value
+
+	@staticmethod
+	def isFunctionDef_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.FunctionDef] | bool]:
+		return lambda node: Be.FunctionDef(node) and IfThis.isIdentifier(identifier)(DOT.name(node))
+
+	@staticmethod
+	def isIdentifier(identifier: ast_Identifier) -> Callable[[ast_Identifier | None], TypeGuard[ast_Identifier] | bool]:
+		return lambda node: node == identifier
+
+	@staticmethod
+	def isIfUnaryNotAttributeNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.If] | bool]:
+		return lambda node: (Be.If(node)
+					and IfThis.isUnaryNotAttributeNamespace_Identifier(namespace, identifier)(node.test))
+
+	@staticmethod
+	def isName_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Name] | bool]:
+		return lambda node: Be.Name(node) and IfThis.isIdentifier(identifier)(DOT.id(node))
+	@staticmethod
+	def isNestedName_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Attribute | ast.Starred | ast.Subscript] | bool]:
+		""" `node` is `ast.Name`
+
+			OR
+
+			1. `node` is one of `ast.Attribute`, `ast.Subscript`, or `ast.Starred`,
+			2. zero or more direct descendants in an unbroken chain are `ast.Attribute`, `ast.Subscript`, or `ast.Starred`,
+			3. the direct descendant chain ends with `ast.Name`,
+
+			and
+
+			The `ast.Name` `id` attribute is `identifier`."""
+		def workhorse(node: ast.AST) -> TypeGuard[ast.Attribute | ast.Starred | ast.Subscript] | bool:
+			return IfThis.isName_Identifier(identifier)(node) or IfThis.isAttribute_Identifier(identifier)(node) or IfThis.isSubscript_Identifier(identifier)(node) or IfThis.isStarred_Identifier(identifier)(node)
+		return workhorse
+
+	@staticmethod
+	def isStarred_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Starred] | bool]:
+		""" 1. `node` is `ast.Starred`,
+			2. zero or more direct descendants in an unbroken chain are `ast.Attribute`, `ast.Subscript`, or `ast.Starred`,
+			3. the direct descendant chain ends with `ast.Name`, and
+			4. the `ast.Name` `id` attribute is `identifier`."""
+		def workhorse(node: ast.AST) -> TypeGuard[ast.Starred]:
+			return Be.Starred(node) and IfThis.isNestedName_Identifier(identifier)(DOT.value(node))
+		return workhorse
+	@staticmethod
+	def isSubscript_Identifier(identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.Subscript] | bool]:
+		""" 1. `node` is `ast.Subscript`,
+			2. zero or more direct descendants in an unbroken chain are `ast.Attribute`, `ast.Subscript`, or `ast.Starred`,
+			3. the direct descendant chain ends with `ast.Name`, and
+			4. the `ast.Name` `id` attribute is `identifier`."""
+		def workhorse(node: ast.AST) -> TypeGuard[ast.Subscript]:
+			return Be.Subscript(node) and IfThis.isNestedName_Identifier(identifier)(DOT.value(node))
+		return workhorse
+
+	@staticmethod
+	def isUnaryNotAttributeNamespace_Identifier(namespace: ast_Identifier, identifier: ast_Identifier) -> Callable[[ast.AST], TypeGuard[ast.UnaryOp] | bool]:
+		return lambda node: (Be.UnaryOp(node)
+					and Be.Not(node.op)
+					and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(node.operand))
+
+	@staticmethod
+	def matchesMeButNotAnyDescendant(predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
+		return lambda node: predicate(node) and IfThis.matchesNoDescendant(predicate)(node)
+	@staticmethod
+	def matchesNoDescendant(predicate: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
+		def workhorse(node: ast.AST) -> bool:
+			for descendant in ast.walk(node):
+				if descendant is not node and predicate(descendant):
+					return False
+			return True
+		return workhorse
+
+	@staticmethod
+	def unparseIs(astAST: ast.AST) -> Callable[[ast.AST], bool]:
+		def workhorse(node: ast.AST) -> bool:
+			return ast.unparse(node) == ast.unparse(astAST)
+		return workhorse

astToolkit/_toolMake.py

@@ -0,0 +1,339 @@
+"""This file is generated automatically, so changes to this file will be lost."""
+from collections.abc import Sequence
+from astToolkit import astDOTParamSpec, astDOTTryStar, astDOTTypeAlias, astDOTTypeVar, astDOTTypeVarTuple, astDOTtype_param
+from astToolkit import ast_Identifier, ast_expr_Slice, intORstr, intORstrORtype_params, intORtype_params, str_nameDOTname
+from typing import Any, Literal
+import ast
+
+class Make:
+    """
+	Almost all parameters described here are only accessible through a method's `**keywordArguments` parameter.
+
+	Parameters:
+		context (ast.Load()): Are you loading from, storing to, or deleting the identifier? The `context` (also, `ctx`) value is `ast.Load()`, `ast.Store()`, or `ast.Del()`.
+		col_offset (0): int Position information specifying the column where an AST node begins.
+		end_col_offset (None): int|None Position information specifying the column where an AST node ends.
+		end_lineno (None): int|None Position information specifying the line number where an AST node ends.
+		level (0): int Module import depth level that controls relative vs absolute imports. Default 0 indicates absolute import.
+		lineno: int Position information manually specifying the line number where an AST node begins.
+		kind (None): str|None Used for type annotations in limited cases.
+		type_comment (None): str|None "type_comment is an optional string with the type annotation as a comment." or `# type: ignore`.
+		type_params: list[ast.type_param] Type parameters for generic type definitions.
+
+	The `ast._Attributes`, lineno, col_offset, end_lineno, and end_col_offset, hold position information; however, they are, importantly, _not_ `ast._fields`.
+	"""
+
+    @staticmethod
+    def alias(name: ast_Identifier, asName: ast_Identifier | None=None, **keywordArguments: int) -> ast.alias:
+        return ast.alias(name, asName, **keywordArguments)
+
+    @staticmethod
+    def AnnAssign(target: ast.Name | ast.Attribute | ast.Subscript, annotation: ast.expr, value: ast.expr | None, **keywordArguments: int) -> ast.AnnAssign:
+        return ast.AnnAssign(target, annotation, value, **keywordArguments, simple=int(isinstance(target, ast.Name)))
+
+    @staticmethod
+    def arg(arg: ast_Identifier, annotation: ast.expr | None, **keywordArguments: intORstr) -> ast.arg:
+        return ast.arg(arg, annotation, **keywordArguments)
+
+    @staticmethod
+    def arguments(posonlyargs: list[ast.arg]=[], args: list[ast.arg]=[], vararg: ast.arg | None=None, kwonlyargs: list[ast.arg]=[], kw_defaults: Sequence[ast.expr | None]=[None], kwarg: ast.arg | None=None, defaults: Sequence[ast.expr]=[], **keywordArguments: int) -> ast.arguments:
+        return ast.arguments(posonlyargs, args, vararg, kwonlyargs, list(kw_defaults), kwarg, list(defaults), **keywordArguments)
+
+    @staticmethod
+    def Assert(test: ast.expr, msg: ast.expr | None, **keywordArguments: int) -> ast.Assert:
+        return ast.Assert(test, msg, **keywordArguments)
+
+    @staticmethod
+    def Assign(targets: Sequence[ast.expr], value: ast.expr, **keywordArguments: intORstr) -> ast.Assign:
+        return ast.Assign(list(targets), value, **keywordArguments)
+
+    @staticmethod
+    def AsyncFor(target: ast.expr, iter: ast.expr, body: Sequence[ast.stmt], orElse: Sequence[ast.stmt]=[], **keywordArguments: intORstr) -> ast.AsyncFor:
+        return ast.AsyncFor(target, iter, list(body), list(orElse), **keywordArguments)
+
+    @staticmethod
+    def AsyncFunctionDef(name: ast_Identifier, args: ast.arguments, body: Sequence[ast.stmt], decorator_list: Sequence[ast.expr]=[], returns: ast.expr | None=None, **keywordArguments: intORstrORtype_params) -> ast.AsyncFunctionDef:
+        return ast.AsyncFunctionDef(name, args, list(body), list(decorator_list), returns, **keywordArguments)
+
+    @staticmethod
+    def AsyncWith(items: list[ast.withitem], body: Sequence[ast.stmt], **keywordArguments: intORstr) -> ast.AsyncWith:
+        return ast.AsyncWith(items, list(body), **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 (e.g., `ast.Name`.)
+		attribute: an `ast_Identifier` after a dot `.`; you can pass multiple `attribute` and they will be chained together.
+	"""
+
+        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
+    def AugAssign(target: ast.Name | ast.Attribute | ast.Subscript, op: ast.operator, value: ast.expr, **keywordArguments: int) -> ast.AugAssign:
+        return ast.AugAssign(target, op, value, **keywordArguments)
+
+    @staticmethod
+    def Await(value: ast.expr, **keywordArguments: int) -> ast.Await:
+        return ast.Await(value, **keywordArguments)
+
+    @staticmethod
+    def BinOp(left: ast.expr, op: ast.operator, right: ast.expr, **keywordArguments: int) -> ast.BinOp:
+        return ast.BinOp(left, op, right, **keywordArguments)
+
+    @staticmethod
+    def BoolOp(op: ast.boolop, values: Sequence[ast.expr], **keywordArguments: int) -> ast.BoolOp:
+        return ast.BoolOp(op, list(values), **keywordArguments)
+
+    @staticmethod
+    def Call(callee: ast.expr, args: Sequence[ast.expr]=[], list_keyword: list[ast.keyword]=[], **keywordArguments: int) -> ast.Call:
+        return ast.Call(callee, list(args), list_keyword, **keywordArguments)
+
+    @staticmethod
+    def ClassDef(name: ast_Identifier, bases: Sequence[ast.expr], list_keyword: list[ast.keyword]=[], body: Sequence[ast.stmt]=[], decorator_list: Sequence[ast.expr]=[], **keywordArguments: intORtype_params) -> ast.ClassDef:
+        return ast.ClassDef(name, list(bases), list_keyword, list(body), list(decorator_list), **keywordArguments)
+
+    @staticmethod
+    def Compare(left: ast.expr, ops: Sequence[ast.cmpop], comparators: Sequence[ast.expr], **keywordArguments: int) -> ast.Compare:
+        return ast.Compare(left, list(ops), list(comparators), **keywordArguments)
+
+    @staticmethod
+    def comprehension(target: ast.expr, iter: ast.expr, ifs: Sequence[ast.expr], is_async: int, **keywordArguments: int) -> ast.comprehension:
+        return ast.comprehension(target, iter, list(ifs), is_async, **keywordArguments)
+
+    @staticmethod
+    def Constant(value: Any, **keywordArguments: intORstr) -> ast.Constant:
+        return ast.Constant(value, **keywordArguments)
+
+    @staticmethod
+    def Delete(targets: Sequence[ast.expr], **keywordArguments: int) -> ast.Delete:
+        return ast.Delete(list(targets), **keywordArguments)
+
+    @staticmethod
+    def Dict(keys: Sequence[ast.expr | None], values: Sequence[ast.expr], **keywordArguments: int) -> ast.Dict:
+        return ast.Dict(list(keys), list(values), **keywordArguments)
+
+    @staticmethod
+    def DictComp(key: ast.expr, value: ast.expr, generators: list[ast.comprehension], **keywordArguments: int) -> ast.DictComp:
+        return ast.DictComp(key, value, generators, **keywordArguments)
+
+    @staticmethod
+    def ExceptHandler(type: ast.expr | None, name: ast_Identifier | None, body: Sequence[ast.stmt], **keywordArguments: int) -> ast.ExceptHandler:
+        return ast.ExceptHandler(type, name, list(body), **keywordArguments)
+
+    @staticmethod
+    def Expr(value: ast.expr, **keywordArguments: int) -> ast.Expr:
+        return ast.Expr(value, **keywordArguments)
+
+    @staticmethod
+    def Expression(body: ast.expr) -> ast.Expression:
+        return ast.Expression(body)
+
+    @staticmethod
+    def For(target: ast.expr, iter: ast.expr, body: Sequence[ast.stmt], orElse: Sequence[ast.stmt]=[], **keywordArguments: intORstr) -> ast.For:
+        return ast.For(target, iter, list(body), list(orElse), **keywordArguments)
+
+    @staticmethod
+    def FormattedValue(value: ast.expr, conversion: int, format_spec: ast.expr | None, **keywordArguments: int) -> ast.FormattedValue:
+        return ast.FormattedValue(value, conversion, format_spec, **keywordArguments)
+
+    @staticmethod
+    def FunctionDef(name: ast_Identifier, args: ast.arguments, body: Sequence[ast.stmt], decorator_list: Sequence[ast.expr]=[], returns: ast.expr | None=None, **keywordArguments: intORstrORtype_params) -> ast.FunctionDef:
+        return ast.FunctionDef(name, args, list(body), list(decorator_list), returns, **keywordArguments)
+
+    @staticmethod
+    def FunctionType(argtypes: Sequence[ast.expr], returns: ast.expr) -> ast.FunctionType:
+        return ast.FunctionType(list(argtypes), returns)
+
+    @staticmethod
+    def GeneratorExp(elt: ast.expr, generators: list[ast.comprehension], **keywordArguments: int) -> ast.GeneratorExp:
+        return ast.GeneratorExp(elt, generators, **keywordArguments)
+
+    @staticmethod
+    def Global(names: list[ast_Identifier], **keywordArguments: int) -> ast.Global:
+        return ast.Global(names, **keywordArguments)
+
+    @staticmethod
+    def If(test: ast.expr, body: Sequence[ast.stmt], orElse: Sequence[ast.stmt]=[], **keywordArguments: int) -> ast.If:
+        return ast.If(test, list(body), list(orElse), **keywordArguments)
+
+    @staticmethod
+    def IfExp(test: ast.expr, body: ast.expr, orElse: ast.expr, **keywordArguments: int) -> ast.IfExp:
+        return ast.IfExp(test, body, orElse, **keywordArguments)
+
+    @staticmethod
+    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(module: ast_Identifier | None, list_alias: list[ast.alias], **keywordArguments: int) -> ast.ImportFrom:
+        return ast.ImportFrom(module, list_alias, **keywordArguments, level=0)
+
+    @staticmethod
+    def Interactive(body: Sequence[ast.stmt]) -> ast.Interactive:
+        return ast.Interactive(list(body))
+
+    @staticmethod
+    def JoinedStr(values: Sequence[ast.expr], **keywordArguments: int) -> ast.JoinedStr:
+        return ast.JoinedStr(list(values), **keywordArguments)
+
+    @staticmethod
+    def keyword(arg: ast_Identifier | None, value: ast.expr, **keywordArguments: int) -> ast.keyword:
+        return ast.keyword(arg, value, **keywordArguments)
+
+    @staticmethod
+    def Lambda(args: ast.arguments, body: ast.expr, **keywordArguments: int) -> ast.Lambda:
+        return ast.Lambda(args, body, **keywordArguments)
+
+    @staticmethod
+    def List(elts: Sequence[ast.expr], context: ast.expr_context=ast.Load(), **keywordArguments: int) -> ast.List:
+        return ast.List(list(elts), context, **keywordArguments)
+
+    @staticmethod
+    def ListComp(elt: ast.expr, generators: list[ast.comprehension], **keywordArguments: int) -> ast.ListComp:
+        return ast.ListComp(elt, generators, **keywordArguments)
+
+    @staticmethod
+    def Match(subject: ast.expr, cases: list[ast.match_case], **keywordArguments: int) -> ast.Match:
+        return ast.Match(subject, cases, **keywordArguments)
+
+    @staticmethod
+    def match_case(pattern: ast.pattern, guard: ast.expr | None, body: Sequence[ast.stmt], **keywordArguments: int) -> ast.match_case:
+        return ast.match_case(pattern, guard, list(body), **keywordArguments)
+
+    @staticmethod
+    def MatchAs(pattern: ast.pattern | None, name: ast_Identifier | None, **keywordArguments: int) -> ast.MatchAs:
+        return ast.MatchAs(pattern, name, **keywordArguments)
+
+    @staticmethod
+    def MatchClass(cls: ast.expr, patterns: Sequence[ast.pattern], kwd_attrs: list[ast_Identifier], kwd_patterns: Sequence[ast.pattern], **keywordArguments: int) -> ast.MatchClass:
+        return ast.MatchClass(cls, list(patterns), kwd_attrs, list(kwd_patterns), **keywordArguments)
+
+    @staticmethod
+    def MatchMapping(keys: Sequence[ast.expr], patterns: Sequence[ast.pattern], rest: ast_Identifier | None, **keywordArguments: int) -> ast.MatchMapping:
+        return ast.MatchMapping(list(keys), list(patterns), rest, **keywordArguments)
+
+    @staticmethod
+    def MatchOr(patterns: Sequence[ast.pattern], **keywordArguments: int) -> ast.MatchOr:
+        return ast.MatchOr(list(patterns), **keywordArguments)
+
+    @staticmethod
+    def MatchSequence(patterns: Sequence[ast.pattern], **keywordArguments: int) -> ast.MatchSequence:
+        return ast.MatchSequence(list(patterns), **keywordArguments)
+
+    @staticmethod
+    def MatchSingleton(value: Literal[True, False] | None, **keywordArguments: int) -> ast.MatchSingleton:
+        return ast.MatchSingleton(value, **keywordArguments)
+
+    @staticmethod
+    def MatchStar(name: ast_Identifier | None, **keywordArguments: int) -> ast.MatchStar:
+        return ast.MatchStar(name, **keywordArguments)
+
+    @staticmethod
+    def MatchValue(value: ast.expr, **keywordArguments: int) -> ast.MatchValue:
+        return ast.MatchValue(value, **keywordArguments)
+
+    @staticmethod
+    def Module(body: Sequence[ast.stmt], type_ignores: list[ast.TypeIgnore]=[]) -> ast.Module:
+        return ast.Module(list(body), type_ignores)
+
+    @staticmethod
+    def Name(id: ast_Identifier, context: ast.expr_context=ast.Load(), **keywordArguments: int) -> ast.Name:
+        return ast.Name(id, context, **keywordArguments)
+
+    @staticmethod
+    def NamedExpr(target: ast.Name, value: ast.expr, **keywordArguments: int) -> ast.NamedExpr:
+        return ast.NamedExpr(target, value, **keywordArguments)
+
+    @staticmethod
+    def Nonlocal(names: list[ast_Identifier], **keywordArguments: int) -> ast.Nonlocal:
+        return ast.Nonlocal(names, **keywordArguments)
+
+    @staticmethod
+    def ParamSpec(name: ast_Identifier, default_value: ast.expr | None, **keywordArguments: int) -> astDOTParamSpec:
+        return astDOTParamSpec(name, default_value, **keywordArguments)
+
+    @staticmethod
+    def Raise(exc: ast.expr | None, cause: ast.expr | None, **keywordArguments: int) -> ast.Raise:
+        return ast.Raise(exc, cause, **keywordArguments)
+
+    @staticmethod
+    def Return(value: ast.expr | None, **keywordArguments: int) -> ast.Return:
+        return ast.Return(value, **keywordArguments)
+
+    @staticmethod
+    def Set(elts: Sequence[ast.expr], **keywordArguments: int) -> ast.Set:
+        return ast.Set(list(elts), **keywordArguments)
+
+    @staticmethod
+    def SetComp(elt: ast.expr, generators: list[ast.comprehension], **keywordArguments: int) -> ast.SetComp:
+        return ast.SetComp(elt, generators, **keywordArguments)
+
+    @staticmethod
+    def Slice(lower: ast.expr | None, upper: ast.expr | None, step: ast.expr | None, **keywordArguments: int) -> ast.Slice:
+        return ast.Slice(lower, upper, step, **keywordArguments)
+
+    @staticmethod
+    def Starred(value: ast.expr, context: ast.expr_context=ast.Load(), **keywordArguments: int) -> ast.Starred:
+        return ast.Starred(value, context, **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 Try(body: Sequence[ast.stmt], handlers: list[ast.ExceptHandler], orElse: Sequence[ast.stmt], finalbody: Sequence[ast.stmt]=[], **keywordArguments: int) -> ast.Try:
+        return ast.Try(list(body), handlers, list(orElse), list(finalbody), **keywordArguments)
+
+    @staticmethod
+    def TryStar(body: Sequence[ast.stmt], handlers: list[ast.ExceptHandler], orElse: Sequence[ast.stmt], finalbody: Sequence[ast.stmt]=[], **keywordArguments: int) -> astDOTTryStar:
+        return astDOTTryStar(list(body), handlers, list(orElse), list(finalbody), **keywordArguments)
+
+    @staticmethod
+    def Tuple(elts: Sequence[ast.expr], context: ast.expr_context=ast.Load(), **keywordArguments: int) -> ast.Tuple:
+        return ast.Tuple(list(elts), context, **keywordArguments)
+
+    @staticmethod
+    def TypeAlias(name: ast.Name, type_params: Sequence[astDOTtype_param], value: ast.expr, **keywordArguments: int) -> astDOTTypeAlias:
+        return astDOTTypeAlias(name, list(type_params), value, **keywordArguments)
+
+    @staticmethod
+    def TypeIgnore(lineno: int, tag: ast_Identifier, **keywordArguments: int) -> ast.TypeIgnore:
+        return ast.TypeIgnore(lineno, tag, **keywordArguments)
+
+    @staticmethod
+    def TypeVar(name: ast_Identifier, bound: ast.expr | None, default_value: ast.expr | None, **keywordArguments: int) -> astDOTTypeVar:
+        return astDOTTypeVar(name, bound, default_value, **keywordArguments)
+
+    @staticmethod
+    def TypeVarTuple(name: ast_Identifier, default_value: ast.expr | None, **keywordArguments: int) -> astDOTTypeVarTuple:
+        return astDOTTypeVarTuple(name, default_value, **keywordArguments)
+
+    @staticmethod
+    def UnaryOp(op: ast.unaryop, operand: ast.expr, **keywordArguments: int) -> ast.UnaryOp:
+        return ast.UnaryOp(op, operand, **keywordArguments)
+
+    @staticmethod
+    def While(test: ast.expr, body: Sequence[ast.stmt], orElse: Sequence[ast.stmt]=[], **keywordArguments: int) -> ast.While:
+        return ast.While(test, list(body), list(orElse), **keywordArguments)
+
+    @staticmethod
+    def With(items: list[ast.withitem], body: Sequence[ast.stmt], **keywordArguments: intORstr) -> ast.With:
+        return ast.With(items, list(body), **keywordArguments)
+
+    @staticmethod
+    def withitem(context_expr: ast.expr, optional_vars: ast.expr | None, **keywordArguments: int) -> ast.withitem:
+        return ast.withitem(context_expr, optional_vars, **keywordArguments)
+
+    @staticmethod
+    def Yield(value: ast.expr | None, **keywordArguments: int) -> ast.Yield:
+        return ast.Yield(value, **keywordArguments)
+
+    @staticmethod
+    def YieldFrom(value: ast.expr, **keywordArguments: int) -> ast.YieldFrom:
+        return ast.YieldFrom(value, **keywordArguments)

astToolkit/_toolThen.py

@@ -0,0 +1,63 @@
+"""
+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 astToolkit import ast_Identifier, NodeORattribute
+from typing import Any
+import ast
+
+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 appendTo(listOfAny: list[Any]) -> Callable[[ast.AST | ast_Identifier], ast.AST | ast_Identifier]:
+		def workhorse(node: ast.AST | ast_Identifier) -> ast.AST | ast_Identifier:
+			listOfAny.append(node)
+			return node
+		return workhorse
+
+	@staticmethod
+	def extractIt(node: NodeORattribute) -> NodeORattribute:
+		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(_removeMe: ast.AST) -> None:
+		return None
+
+	@staticmethod
+	def replaceWith(astAST: NodeORattribute) -> Callable[[NodeORattribute], NodeORattribute]:
+		return lambda _replaceMe: astAST
+
+	@staticmethod
+	def updateKeyValueIn(key: Callable[..., Any], value: Callable[..., Any], dictionary: dict[Any, Any]) -> Callable[[ast.AST], dict[Any, Any]]:
+		def workhorse(node: ast.AST) -> dict[Any, Any]:
+			dictionary.setdefault(key(node), value(node))
+			return dictionary
+		return workhorse

astToolkit/_toolboxAST.py

@@ -0,0 +1,57 @@
+from astToolkit import ast_Identifier, IfThis, IngredientsFunction, LedgerOfImports, NodeTourist, Then
+from astToolkit import FREAKOUT
+import ast
+
+def astModuleToIngredientsFunction(astModule: ast.AST, identifierFunctionDef: ast_Identifier) -> IngredientsFunction:
+	"""
+	Extract a function definition from an AST module and create an `IngredientsFunction`.
+
+	This function finds a function definition with the specified identifier in the given AST module, extracts it, and
+	stores all module imports in the `LedgerOfImports`.
+
+	Parameters:
+		astModule: The AST module containing the function definition.
+		identifierFunctionDef: The name of the function to extract.
+
+	Returns:
+		ingredientsFunction: `IngredientsFunction` object containing the `ast.FunctionDef` and _all_ imports from the
+		source module.
+
+	Raises:
+		FREAKOUT: If the function definition is not found.
+	"""
+	astFunctionDef = extractFunctionDef(astModule, identifierFunctionDef)
+	if not astFunctionDef: raise FREAKOUT
+	return IngredientsFunction(astFunctionDef, LedgerOfImports(astModule))
+
+def extractClassDef(module: ast.AST, identifier: ast_Identifier) -> ast.ClassDef | None:
+	"""
+	Extract a class definition with a specific name from an AST module.
+
+	This function searches through an AST module for a class definition that matches the provided identifier and returns
+	it if found.
+
+	Parameters:
+		module: The AST module to search within.
+		identifier: The name of the class to find.
+
+	Returns:
+		astClassDef|None: The matching class definition AST node, or `None` if not found.
+	"""
+	return NodeTourist(IfThis.isClassDef_Identifier(identifier), Then.extractIt).captureLastMatch(module)
+
+def extractFunctionDef(module: ast.AST, identifier: ast_Identifier) -> ast.FunctionDef | None:
+	"""
+	Extract a function definition with a specific name from an AST module.
+
+	This function searches through an AST module for a function definition that matches the provided identifier and
+	returns it if found.
+
+	Parameters:
+		module: The AST module to search within.
+		identifier: The name of the function to find.
+
+	Returns:
+		astFunctionDef|None: The matching function definition AST node, or `None` if not found.
+	"""
+	return NodeTourist(IfThis.isFunctionDef_Identifier(identifier), Then.extractIt).captureLastMatch(module)