astToolkit 0.5.0__tar.gz → 0.5.2__tar.gz

{asttoolkit-0.5.0 → asttoolkit-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astToolkit
-Version: 0.5.0
+Version: 0.5.2
 Summary: A powerfully composable, type-safe toolkit for Python abstract syntax tree (AST) manipulation, analysis, transformation, and code generation with a layered architecture designed for building sophisticated code processing assembly-lines.
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
@@ -30,7 +30,7 @@ Requires-Dist: Z0Z_tools
 Requires-Dist: autoflake
 Requires-Dist: python_minifier
 Requires-Dist: tomli
-Requires-Dist: typing-extensions
+Requires-Dist: typing-extensions>=4.10.0
 Provides-Extra: testing
 Requires-Dist: mypy; extra == "testing"
 Requires-Dist: pytest; extra == "testing"
@@ -59,7 +59,7 @@ Don't use it for simple text-based code manipulation—use regex or string opera
 astToolkit implements a layered architecture designed for composability and type safety:
 
 1. **Core "Atomic" Classes** - The foundation of the system:
-   - `Be`: Type guards that return `TypeGuard[ast.NodeType]` for safe type narrowing.
+   - `Be`: Type guards that return `TypeIs[ast.NodeType]` for safe type narrowing.
    - `DOT`: Read-only accessors that retrieve node attributes with proper typing.
    - `Grab`: Transformation functions that modify specific attributes while preserving node structure.
    - `Make`: Factory methods that create properly configured AST nodes with consistent interfaces.
@@ -192,7 +192,7 @@ class IfThis(astToolkit_IfThis):
   def isAttributeNamespaceIdentifierGreaterThan0(
       namespace: str,
       identifier: str
-      ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+      ) -> Callable[[ast.AST], TypeIs[ast.Compare] | bool]:
 
     return lambda node: (
         Be.Compare(node)
@@ -204,7 +204,7 @@ class IfThis(astToolkit_IfThis):
   def isWhileAttributeNamespaceIdentifierGreaterThan0(
       namespace: str,
       identifier: str
-      ) -> Callable[[ast.AST], TypeGuard[ast.While] | bool]:
+      ) -> Callable[[ast.AST], TypeIs[ast.While] | bool]:
 
     return lambda node: (
         Be.While(node)
@@ -292,7 +292,7 @@ To create specialized patterns for your codebase, extend the core classes:
 ```python
 from astToolkit import str, Be, IfThis as astToolkit_IfThis
 from collections.abc import Callable
-from typing import TypeGuard
+from typing import TypeIs
 import ast
 
 class IfThis(astToolkit_IfThis):
@@ -300,7 +300,7 @@ class IfThis(astToolkit_IfThis):
     def isAttributeNamespaceIdentifierGreaterThan0(
         namespace: str,
         identifier: str
-    ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+    ) -> Callable[[ast.AST], TypeIs[ast.Compare] | bool]:
         """Find comparisons like 'state.counter > 0'"""
         return lambda node: (
             Be.Compare(node)
@@ -313,7 +313,7 @@ class IfThis(astToolkit_IfThis):
     def isWhileAttributeNamespaceIdentifierGreaterThan0(
         namespace: str,
         identifier: str
-    ) -> Callable[[ast.AST], TypeGuard[ast.While] | bool]:
+    ) -> Callable[[ast.AST], TypeIs[ast.While] | bool]:
         """Find while loops like 'while state.counter > 0:'"""
         return lambda node: (
             Be.While(node)

{asttoolkit-0.5.0 → asttoolkit-0.5.2}/README.md

@@ -16,7 +16,7 @@ Don't use it for simple text-based code manipulation—use regex or string opera
 astToolkit implements a layered architecture designed for composability and type safety:
 
 1. **Core "Atomic" Classes** - The foundation of the system:
-   - `Be`: Type guards that return `TypeGuard[ast.NodeType]` for safe type narrowing.
+   - `Be`: Type guards that return `TypeIs[ast.NodeType]` for safe type narrowing.
    - `DOT`: Read-only accessors that retrieve node attributes with proper typing.
    - `Grab`: Transformation functions that modify specific attributes while preserving node structure.
    - `Make`: Factory methods that create properly configured AST nodes with consistent interfaces.
@@ -149,7 +149,7 @@ class IfThis(astToolkit_IfThis):
   def isAttributeNamespaceIdentifierGreaterThan0(
       namespace: str,
       identifier: str
-      ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+      ) -> Callable[[ast.AST], TypeIs[ast.Compare] | bool]:
 
     return lambda node: (
         Be.Compare(node)
@@ -161,7 +161,7 @@ class IfThis(astToolkit_IfThis):
   def isWhileAttributeNamespaceIdentifierGreaterThan0(
       namespace: str,
       identifier: str
-      ) -> Callable[[ast.AST], TypeGuard[ast.While] | bool]:
+      ) -> Callable[[ast.AST], TypeIs[ast.While] | bool]:
 
     return lambda node: (
         Be.While(node)
@@ -249,7 +249,7 @@ To create specialized patterns for your codebase, extend the core classes:
 ```python
 from astToolkit import str, Be, IfThis as astToolkit_IfThis
 from collections.abc import Callable
-from typing import TypeGuard
+from typing import TypeIs
 import ast
 
 class IfThis(astToolkit_IfThis):
@@ -257,7 +257,7 @@ class IfThis(astToolkit_IfThis):
     def isAttributeNamespaceIdentifierGreaterThan0(
         namespace: str,
         identifier: str
-    ) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+    ) -> Callable[[ast.AST], TypeIs[ast.Compare] | bool]:
         """Find comparisons like 'state.counter > 0'"""
         return lambda node: (
             Be.Compare(node)
@@ -270,7 +270,7 @@ class IfThis(astToolkit_IfThis):
     def isWhileAttributeNamespaceIdentifierGreaterThan0(
         namespace: str,
         identifier: str
-    ) -> Callable[[ast.AST], TypeGuard[ast.While] | bool]:
+    ) -> Callable[[ast.AST], TypeIs[ast.While] | bool]:
         """Find while loops like 'while state.counter > 0:'"""
         return lambda node: (
             Be.While(node)

asttoolkit-0.5.2/astToolkit/__init__.py

@@ -0,0 +1,87 @@
+import sys
+
+from astToolkit._astTypes import (
+	ast_attributes as ast_attributes, ast_attributes_int as ast_attributes_int,
+	ast_attributes_type_comment as ast_attributes_type_comment, ConstantValueType as ConstantValueType,
+	hasDOTannotation as hasDOTannotation, hasDOTannotation_expr as hasDOTannotation_expr,
+	hasDOTannotation_exprOrNone as hasDOTannotation_exprOrNone, hasDOTarg as hasDOTarg,
+	hasDOTarg_str as hasDOTarg_str, hasDOTarg_strOrNone as hasDOTarg_strOrNone,
+	hasDOTargs as hasDOTargs, hasDOTargs_arguments as hasDOTargs_arguments,
+	hasDOTargs_list_arg as hasDOTargs_list_arg, hasDOTargs_list_expr as hasDOTargs_list_expr,
+	hasDOTargtypes as hasDOTargtypes, hasDOTasname as hasDOTasname, hasDOTattr as hasDOTattr,
+	hasDOTbases as hasDOTbases, hasDOTbody as hasDOTbody, hasDOTbody_expr as hasDOTbody_expr,
+	hasDOTbody_list_stmt as hasDOTbody_list_stmt, hasDOTbound as hasDOTbound,
+	hasDOTcases as hasDOTcases, hasDOTcause as hasDOTcause, hasDOTcls as hasDOTcls,
+	hasDOTcomparators as hasDOTcomparators, hasDOTcontext_expr as hasDOTcontext_expr,
+	hasDOTconversion as hasDOTconversion, hasDOTctx as hasDOTctx,
+	hasDOTdecorator_list as hasDOTdecorator_list,
+	hasDOTdefaults as hasDOTdefaults, hasDOTelt as hasDOTelt, hasDOTelts as hasDOTelts,
+	hasDOTexc as hasDOTexc, hasDOTfinalbody as hasDOTfinalbody, hasDOTformat_spec as hasDOTformat_spec,
+	hasDOTfunc as hasDOTfunc, hasDOTgenerators as hasDOTgenerators, hasDOTguard as hasDOTguard,
+	hasDOThandlers as hasDOThandlers, hasDOTid as hasDOTid, hasDOTifs as hasDOTifs,
+	hasDOTis_async as hasDOTis_async, hasDOTitems as hasDOTitems, hasDOTiter as hasDOTiter,
+	hasDOTkey as hasDOTkey, hasDOTkeys as hasDOTkeys, hasDOTkeys_list_expr as hasDOTkeys_list_expr,
+	hasDOTkeys_list_exprOrNone as hasDOTkeys_list_exprOrNone, hasDOTkeywords as hasDOTkeywords,
+	hasDOTkind as hasDOTkind, hasDOTkw_defaults as hasDOTkw_defaults, hasDOTkwarg as hasDOTkwarg,
+	hasDOTkwd_attrs as hasDOTkwd_attrs, hasDOTkwd_patterns as hasDOTkwd_patterns,
+	hasDOTkwonlyargs as hasDOTkwonlyargs, hasDOTleft as hasDOTleft, hasDOTlevel as hasDOTlevel,
+	hasDOTlineno as hasDOTlineno, hasDOTlower as hasDOTlower, hasDOTmodule as hasDOTmodule,
+	hasDOTmsg as hasDOTmsg, hasDOTname as hasDOTname, hasDOTname_Name as hasDOTname_Name,
+	hasDOTname_str as hasDOTname_str, hasDOTname_strOrNone as hasDOTname_strOrNone,
+	hasDOTnames as hasDOTnames, hasDOTnames_list_alias as hasDOTnames_list_alias,
+	hasDOTnames_list_str as hasDOTnames_list_str, hasDOTop as hasDOTop,
+	hasDOTop_boolop as hasDOTop_boolop, hasDOTop_operator as hasDOTop_operator,
+	hasDOTop_unaryop as hasDOTop_unaryop, hasDOToperand as hasDOToperand, hasDOTops as hasDOTops,
+	hasDOToptional_vars as hasDOToptional_vars, hasDOTorelse as hasDOTorelse,
+	hasDOTorelse_expr as hasDOTorelse_expr, hasDOTorelse_list_stmt as hasDOTorelse_list_stmt,
+	hasDOTpattern as hasDOTpattern, hasDOTpattern_pattern as hasDOTpattern_pattern,
+	hasDOTpattern_patternOrNone as hasDOTpattern_patternOrNone, hasDOTpatterns as hasDOTpatterns,
+	hasDOTposonlyargs as hasDOTposonlyargs, hasDOTrest as hasDOTrest, hasDOTreturns as hasDOTreturns,
+	hasDOTreturns_expr as hasDOTreturns_expr, hasDOTreturns_exprOrNone as hasDOTreturns_exprOrNone,
+	hasDOTright as hasDOTright, hasDOTsimple as hasDOTsimple, hasDOTslice as hasDOTslice,
+	hasDOTstep as hasDOTstep, hasDOTsubject as hasDOTsubject, hasDOTtag as hasDOTtag,
+	hasDOTtarget as hasDOTtarget, hasDOTtarget_expr as hasDOTtarget_expr,
+	hasDOTtarget_Name as hasDOTtarget_Name,
+	hasDOTtarget_NameOrAttributeOrSubscript as hasDOTtarget_NameOrAttributeOrSubscript,
+	hasDOTtargets as hasDOTtargets, hasDOTtest as hasDOTtest, hasDOTtype as hasDOTtype,
+	hasDOTtype_comment as hasDOTtype_comment, hasDOTtype_ignores as hasDOTtype_ignores,
+	hasDOTtype_params as hasDOTtype_params, hasDOTupper as hasDOTupper, hasDOTvalue as hasDOTvalue,
+	hasDOTvalue_boolOrNone as hasDOTvalue_boolOrNone,
+	hasDOTvalue_ConstantValueType as hasDOTvalue_ConstantValueType,
+	hasDOTvalue_expr as hasDOTvalue_expr, hasDOTvalue_exprOrNone as hasDOTvalue_exprOrNone,
+	hasDOTvalues as hasDOTvalues, hasDOTvararg as hasDOTvararg,
+	identifierDotAttribute as identifierDotAttribute, 个 as 个, 个return as 个return, 木 as 木,
+)
+if sys.version_info >= (3, 13):
+	from astToolkit._astTypes import hasDOTdefault_value as hasDOTdefault_value
+
+# from astToolkit._dumpFunctionDef import dump as dump
+from astToolkit._dumpHandmade import dump as dump
+
+from astToolkit._toolkitNodeVisitor import (
+	NodeChanger as NodeChanger,
+	NodeTourist as NodeTourist,
+)
+
+from astToolkit._toolBe import Be as Be
+from astToolkit._toolClassIsAndAttribute import ClassIsAndAttribute as ClassIsAndAttribute
+from astToolkit._toolDOT import DOT as DOT
+from astToolkit._toolGrab import Grab as Grab
+from astToolkit._toolMake import Make as Make
+
+from astToolkit._toolIfThis import IfThis as IfThis
+from astToolkit._toolThen import Then as Then
+
+from astToolkit._toolkitContainers import (
+	IngredientsFunction as IngredientsFunction,
+	IngredientsModule as IngredientsModule,
+	LedgerOfImports as LedgerOfImports,
+)
+
+from astToolkit._toolkitAST import (
+	astModuleToIngredientsFunction as astModuleToIngredientsFunction,
+	extractClassDef as extractClassDef,
+	extractFunctionDef as extractFunctionDef,
+	parseLogicalPath2astModule as parseLogicalPath2astModule,
+	parsePathFilename2astModule as parsePathFilename2astModule,
+)

{asttoolkit-0.5.0 → asttoolkit-0.5.2}/astToolkit/_astTypes.py

@@ -1,12 +1,12 @@
+# pyright: reportMatchNotExhaustive=false
 """This file is generated automatically, so changes to this file will be lost."""
 from types import EllipsisType
-from typing import Any, TypeAlias as typing_TypeAlias, TypeVar as typing_TypeVar, TypedDict
+from typing import TypeAlias as typing_TypeAlias, TypedDict, TypeVar as typing_TypeVar
 import ast
 import sys
-intORstr: typing_TypeAlias = Any
-intORstrORtype_params: typing_TypeAlias = Any
-intORtype_params: typing_TypeAlias = Any
+
 ConstantValueType: typing_TypeAlias = bool | bytes | complex | EllipsisType | float | int | None | range | str
+identifierDotAttribute: typing_TypeAlias = str
 木 = typing_TypeVar('木', bound=ast.AST, covariant=True)
 个 = typing_TypeVar('个', covariant=True)
 个return = typing_TypeVar('个return', covariant=True)

{asttoolkit-0.5.0 → asttoolkit-0.5.2}/astToolkit/_dumpFunctionDef.py

@@ -38,12 +38,16 @@ def dump(node, annotate_fields=True, include_attributes=False, *, indent=None, s
                 if value is None and getattr(cls, name, ...) is None:
                     keywords = True
                     continue
-                if not show_empty and (value is None or value == []) and (not isinstance(node, (Constant, MatchSingleton))):
-                    args_buffer.append(repr(value))
-                    continue
-                elif not keywords:
-                    args.extend(args_buffer)
-                    args_buffer = []
+                if not show_empty:
+                    if value == []:
+                        field_type = cls._field_types.get(name, object)
+                        if getattr(field_type, '__origin__', ...) is list:
+                            if not keywords:
+                                args_buffer.append(repr(value))
+                            continue
+                    if not keywords:
+                        args.extend(args_buffer)
+                        args_buffer = []
                 value, simple = _format(value, level)
                 allsimple = allsimple and simple
                 if keywords:

{asttoolkit-0.5.0 → asttoolkit-0.5.2}/astToolkit/_dumpHandmade.py

@@ -1,37 +1,33 @@
-from ast import AST, Constant, MatchSingleton
+from ast import AST
+from astToolkit import ConstantValueType
 
-def dump(
-    node, annotate_fields=True, include_attributes=False,
-    *,
-    indent=None, show_empty=False,
-):
-    """
-    Return a formatted dump of the tree in node.  This is mainly useful for
-    debugging purposes.  If annotate_fields is true (by default),
-    the returned string will show the names and the values for fields.
-    If annotate_fields is false, the result string will be more compact by
-    omitting unambiguous field names.  Attributes such as line
-    numbers and column offsets are not dumped by default.  If this is wanted,
-    include_attributes can be set to true.  If indent is a non-negative
-    integer or string, then the tree will be pretty-printed with that indent
-    level. None (the default) selects the single line representation.
-    If show_empty is False, then empty lists and fields that are None
-    will be omitted from the output for better readability.
+def dump(node: AST, annotate_fields: bool = True, include_attributes: bool = False, *, indent: int | str | None = None, show_empty: bool = False) -> str:
+    """Return a formatted string representation of an AST node.
+
+    Parameters:
+        node: The AST node to format
+        annotate_fields (True): Whether to include field names in the output
+        include_attributes (False): Whether to include node attributes in addition to fields
+        indent (None): String for indentation or number of spaces; `None` for single-line output
+        show_empty (False): Whether to include fields with empty list or `None` values
+
+    Returns:
+        formattedString: String representation of the AST node with specified formatting
     """
-    def _format(node, level=0):
+    def _format(node: ConstantValueType | AST | list[AST] | list[str], level: int = 0) -> tuple[str, bool]:
         if indent_str is not None:
             level += 1
-            prefix = '\n' + indent_str * level
-            sep = ',\n' + indent_str * level
+            prefix: str = '\n' + indent_str * level
+            sep: str = ',\n' + indent_str * level
         else:
             prefix = ''
             sep = ', '
         if isinstance(node, AST):
-            cls = type(node)
-            args = []
-            args_buffer = []
-            allsimple = True
-            keywords = annotate_fields
+            cls: type[AST] = type(node)
+            args: list[str] = []
+            args_buffer: list[str] = []
+            allsimple: bool = True
+            keywords: bool = annotate_fields
             for name in node._fields:
                 try:
                     value = getattr(node, name)
@@ -43,18 +39,16 @@ def dump(
                         args.append('%s=%s' % (name, value))
                     keywords = True
                     continue
-                elif (
-                    not show_empty
-                    and (value is None or value == [])
-                    # Special cases:
-                    # `Constant(value=None)` and `MatchSingleton(value=None)`
-                    and not isinstance(node, (Constant, MatchSingleton))
-                ):
-                    args_buffer.append(repr(value))
-                    continue
-                elif not keywords:
-                    args.extend(args_buffer)
-                    args_buffer = []
+                if not show_empty:
+                    if value == []:
+                        field_type = cls._field_types.get(name, object)
+                        if getattr(field_type, '__origin__', ...) is list:
+                            if not keywords:
+                                args_buffer.append(repr(value))
+                            continue
+                    if not keywords:
+                        args.extend(args_buffer)
+                        args_buffer = []
                 value_formatted, simple = _format(value, level)
                 allsimple = allsimple and simple
                 if keywords:
@@ -78,7 +72,7 @@ def dump(
         elif isinstance(node, list):
             if not node:
                 return ('[]', True)
-            return '[%s%s]' % (prefix, sep.join(_format(x, level)[0] for x in node)), False
+            return ('[%s%s]' % (prefix, sep.join(_format(x, level)[0] for x in node)), False)
         return (repr(node), True)
 
     if not isinstance(node, AST):

asttoolkit-0.5.2/astToolkit/_theSSOT.py

@@ -0,0 +1,22 @@
+from importlib import import_module as importlib_import_module
+from inspect import getfile as inspect_getfile
+from pathlib import Path
+import dataclasses
+
+identifierPackage = 'astToolkit'
+
+def getPathPackageINSTALLING() -> Path:
+    pathPackage: Path = Path(inspect_getfile(importlib_import_module(identifierPackage)))
+    if pathPackage.is_file():
+        pathPackage = pathPackage.parent
+    return pathPackage
+
+@dataclasses.dataclass
+class PackageSettings:
+    fileExtension: str = dataclasses.field(default='.py')
+    'Default file extension for generated code files.'
+    packageName: str = dataclasses.field(default=identifierPackage)
+    '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.'
+packageSettings = PackageSettings()