pycparser 3.0__tar.gz → 3.11__tar.gz

{pycparser-3.0 → pycparser-3.11}/LICENSE

@@ -1,6 +1,6 @@
 pycparser -- A C parser in Python
 
-Copyright (c) 2008-2022, Eli Bendersky
+Copyright (c) 2008-2027, Eli Bendersky
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

{pycparser-3.0/pycparser.egg-info → pycparser-3.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycparser
-Version: 3.0
+Version: 3.11
 Summary: C parser in Python
 Author-email: Eli Bendersky <eliben@gmail.com>
 Maintainer-email: Eli Bendersky <eliben@gmail.com>
@@ -13,14 +13,15 @@ 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 :: 3.15
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Dynamic: license-file
 
-===============
-pycparser v3.00
-===============
+=========
+pycparser
+=========
 
 
 .. image:: https://github.com/eliben/pycparser/workflows/pycparser-tests/badge.svg
@@ -86,7 +87,7 @@ standard (ISO/IEC 9899).
 How is pycparser licensed?
 --------------------------
 
-`BSD license <https://github.com/eliben/pycparser/blob/master/LICENSE>`_.
+`BSD license <https://github.com/eliben/pycparser/blob/main/LICENSE>`_.
 
 Contact details
 ---------------
@@ -191,9 +192,8 @@ There are a few points to keep in mind when modifying **pycparser**:
 
 * The code for **pycparser**'s AST nodes is automatically generated from a
   configuration file - ``_c_ast.cfg``, by ``_ast_gen.py``. If you modify the AST
-  configuration, make sure to re-generate the code. This can be done by running
-  the ``_ast_gen.py`` script (from the repository root or the
-  ``pycparser`` directory).
+  configuration or the generator, run ``make regen-ast`` from the repository
+  root to re-generate ``pycparser/c_ast.py`` and run ``make format``.
 * Read the docstring in the constructor of the ``CParser`` class for details
   on configuration and compatibility arguments.
 

{pycparser-3.0 → pycparser-3.11}/README.rst

@@ -1,6 +1,6 @@
-===============
-pycparser v3.00
-===============
+=========
+pycparser
+=========
 
 
 .. image:: https://github.com/eliben/pycparser/workflows/pycparser-tests/badge.svg
@@ -66,7 +66,7 @@ standard (ISO/IEC 9899).
 How is pycparser licensed?
 --------------------------
 
-`BSD license <https://github.com/eliben/pycparser/blob/master/LICENSE>`_.
+`BSD license <https://github.com/eliben/pycparser/blob/main/LICENSE>`_.
 
 Contact details
 ---------------
@@ -171,9 +171,8 @@ There are a few points to keep in mind when modifying **pycparser**:
 
 * The code for **pycparser**'s AST nodes is automatically generated from a
   configuration file - ``_c_ast.cfg``, by ``_ast_gen.py``. If you modify the AST
-  configuration, make sure to re-generate the code. This can be done by running
-  the ``_ast_gen.py`` script (from the repository root or the
-  ``pycparser`` directory).
+  configuration or the generator, run ``make regen-ast`` from the repository
+  root to re-generate ``pycparser/c_ast.py`` and run ``make format``.
 * Read the docstring in the constructor of the ``CParser`` class for details
   on configuration and compatibility arguments.
 

{pycparser-3.0 → pycparser-3.11}/examples/c-to-c.py

@@ -13,7 +13,7 @@ import sys
 # your site-packages/ with setup.py
 sys.path.extend([".", ".."])
 
-from pycparser import parse_file, c_generator
+from pycparser import c_generator, parse_file
 
 
 def translate_to_c(filename: str) -> None:

{pycparser-3.0 → pycparser-3.11}/examples/c_json.py

@@ -35,18 +35,18 @@
 #     }
 # ------------------------------------------------------------------------------
 import json
-import sys
 import re
-from typing import Any, Callable, Dict, Optional, Set, TypeVar
+import sys
+from collections.abc import Callable
+from typing import Any, TypeVar
 
 # This is not required if you've installed pycparser into
 # your site-packages/ with setup.py
 sys.path.extend([".", ".."])
 
-from pycparser import parse_file, c_ast
+from pycparser import c_ast, parse_file
 from pycparser.c_parser import Coord
 
-
 RE_CHILD_ARRAY = re.compile(r"(.*)\[(.*)\]")
 RE_INTERNAL_ATTR = re.compile("__.*__")
 
@@ -61,7 +61,7 @@ _R = TypeVar("_R")
 
 def memodict(fn: Callable[[_T], _R]) -> Callable[[_T], _R]:
     """Fast memoization decorator for a function taking a single argument"""
-    cache: Dict[_T, _R] = {}
+    cache: dict[_T, _R] = {}
 
     def memoized(arg: _T) -> _R:
         if arg in cache:
@@ -74,22 +74,22 @@ def memodict(fn: Callable[[_T], _R]) -> Callable[[_T], _R]:
 
 
 @memodict
-def child_attrs_of(klass: type[c_ast.Node]) -> Set[str]:
+def child_attrs_of(klass: type[c_ast.Node]) -> set[str]:
     """
     Given a Node class, get a set of child attrs.
     Memoized to avoid highly repetitive string manipulation
 
     """
     non_child_attrs = set(klass.attr_names)
-    all_attrs = set([i for i in klass.__slots__ if not RE_INTERNAL_ATTR.match(i)])
+    all_attrs: set[str] = {i for i in klass.__slots__ if not RE_INTERNAL_ATTR.match(i)}
     return all_attrs - non_child_attrs
 
 
-def to_dict(node: c_ast.Node) -> Dict[str, Any]:
+def to_dict(node: c_ast.Node) -> dict[str, Any]:
     """Recursively convert an ast into dict representation."""
     klass = node.__class__
 
-    result: Dict[str, Any] = {}
+    result: dict[str, Any] = {}
 
     # Metadata
     result["_nodetype"] = klass.__name__
@@ -115,10 +115,8 @@ def to_dict(node: c_ast.Node) -> Dict[str, Any]:
             result[array_name] = result.get(array_name, [])
             if array_index != len(result[array_name]):
                 raise CJsonError(
-                    "Internal ast error. Array {} out of order. "
-                    "Expected index {}, got {}".format(
-                        array_name, len(result[array_name]), array_index
-                    )
+                    f"Internal ast error. Array {array_name} out of order. "
+                    f"Expected index {len(result[array_name])}, got {array_index}"
                 )
             result[array_name].append(to_dict(child))
         else:
@@ -137,7 +135,7 @@ def to_json(node: c_ast.Node, **kwargs: Any) -> str:
     return json.dumps(to_dict(node), **kwargs)
 
 
-def file_to_dict(filename: str) -> Dict[str, Any]:
+def file_to_dict(filename: str) -> dict[str, Any]:
     """Load C file into dict representation of ast"""
     ast = parse_file(filename, use_cpp=True)
     return to_dict(ast)
@@ -149,7 +147,7 @@ def file_to_json(filename: str, **kwargs: Any) -> str:
     return to_json(ast, **kwargs)
 
 
-def _parse_coord(coord_str: Optional[str]) -> Optional[Coord]:
+def _parse_coord(coord_str: str | None) -> Coord | None:
     """Parse coord string (file:line[:column]) into Coord object."""
     if coord_str is None:
         return None
@@ -178,7 +176,7 @@ def _convert_to_obj(value: Any) -> Any:
             return value
 
 
-def from_dict(node_dict: Dict[str, Any]) -> c_ast.Node:
+def from_dict(node_dict: dict[str, Any]) -> c_ast.Node:
     """Recursively build an ast from dict representation"""
     class_name = node_dict.pop("_nodetype")
 

{pycparser-3.0 → pycparser-3.11}/examples/cdecl.py

@@ -34,13 +34,12 @@
 # -----------------------------------------------------------------
 import copy
 import sys
-from typing import Optional
 
 # This is not required if you've installed pycparser into
 # your site-packages/ with setup.py
 sys.path.extend([".", ".."])
 
-from pycparser import c_parser, c_ast
+from pycparser import c_ast, c_parser
 
 
 def explain_c_declaration(
@@ -73,7 +72,7 @@ def explain_c_declaration(
             expand_struct=expand_struct,
             expand_typedef=expand_typedef,
         )
-    except Exception as e:
+    except RuntimeError as e:
         return "Not a valid declaration: " + str(e)
 
     return _explain_decl_node(expanded)
@@ -174,16 +173,19 @@ def _expand_in_place(
     return decl
 
 
-def _find_struct(name: str, file_ast: c_ast.FileAST) -> Optional[c_ast.Struct]:
+def _find_struct(name: str, file_ast: c_ast.FileAST) -> c_ast.Struct | None:
     """Receives a struct name and return declared struct object in file_ast"""
     for node in file_ast.ext:
-        if isinstance(node, c_ast.Decl) and isinstance(node.type, c_ast.Struct):
-            if node.type.name == name:
-                return node.type
+        if (
+            isinstance(node, c_ast.Decl)
+            and isinstance(node.type, c_ast.Struct)
+            and node.type.name == name
+        ):
+            return node.type
     return None
 
 
-def _find_typedef(name: str, file_ast: c_ast.FileAST) -> Optional[c_ast.Typedef]:
+def _find_typedef(name: str, file_ast: c_ast.FileAST) -> c_ast.Typedef | None:
     """Receives a type name and return typedef object in file_ast"""
     for node in file_ast.ext:
         if isinstance(node, c_ast.Typedef) and node.name == name:

{pycparser-3.0 → pycparser-3.11}/examples/construct_ast_from_scratch.py

@@ -14,7 +14,6 @@ sys.path.extend([".", ".."])
 
 from pycparser import c_ast, c_generator
 
-
 # target C code:
 # int main() {
 #     return 0;

{pycparser-3.0 → pycparser-3.11}/examples/func_defs_add_param.py

@@ -11,7 +11,7 @@ import sys
 
 sys.path.extend([".", ".."])
 
-from pycparser import c_parser, c_ast, c_generator
+from pycparser import c_ast, c_generator, c_parser
 
 text = r"""
 void foo(int a, int b) {

pycparser-3.11/examples/typed_usage.py

@@ -0,0 +1,76 @@
+# ------------------------------------------------------------------------------
+# pycparser: typed_usage.py
+#
+# A minimal example of how static type checking helps use pycparser correctly.
+#
+# The important parts are the narrowings:
+# - ast.ext[...] entries start out as generic AST nodes
+# - Decl.coord is optional and must be checked before use
+# - Decl.type must be narrowed before accessing node-specific attributes
+#
+# Run it from the root directory of pycparser.
+# ------------------------------------------------------------------------------
+import sys
+
+# This is not required if you've installed pycparser into
+# your site-packages/ with setup.py
+sys.path.extend([".", ".."])
+
+from pycparser import c_ast, c_parser
+
+SAMPLE_DECL = "const unsigned int *value;"
+
+
+def parse_single_decl(source: str) -> c_ast.Decl:
+    ast = c_parser.CParser().parse(source, filename="<stdin>")
+    node = ast.ext[-1]
+
+    # Without this guard, type checkers only know that ext entries are Nodes.
+    if not isinstance(node, c_ast.Decl):
+        raise TypeError("expected a declaration")
+
+    return node
+
+
+def require_coord(node: c_ast.Node) -> c_parser.Coord:
+    coord = node.coord
+
+    # Without this guard, `coord.line` is a type error because coord may be None.
+    if coord is None:
+        raise ValueError("node has no source coordinate")
+
+    return coord
+
+
+def describe_type(type_node: c_ast.Node) -> str:
+    # Without these isinstance checks, attributes such as `.type`, `.quals`,
+    # and `.names` are not safe to access.
+    if isinstance(type_node, c_ast.TypeDecl):
+        quals = " ".join(type_node.quals)
+        base = describe_type(type_node.type)
+        return f"{quals} {base}".strip()
+
+    if isinstance(type_node, c_ast.PtrDecl):
+        quals = " ".join(type_node.quals)
+        pointer = "pointer"
+        if quals:
+            pointer = f"{quals} {pointer}"
+        return f"{pointer} to {describe_type(type_node.type)}"
+
+    if isinstance(type_node, c_ast.IdentifierType):
+        return " ".join(type_node.names)
+
+    raise TypeError(f"unsupported declaration type: {type_node.__class__.__name__}")
+
+
+def show_decl(source: str) -> None:
+    decl = parse_single_decl(source)
+    coord = require_coord(decl)
+    print(f"{decl.name}: {describe_type(decl.type)} at {coord}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1:
+        show_decl(sys.argv[1])
+    else:
+        show_decl(SAMPLE_DECL)

{pycparser-3.0 → pycparser-3.11}/examples/using_cpp_libc.py

@@ -15,7 +15,6 @@ sys.path.extend([".", ".."])
 
 from pycparser import parse_file
 
-
 if __name__ == "__main__":
     if len(sys.argv) > 1:
         filename = sys.argv[1]

{pycparser-3.0 → pycparser-3.11}/examples/using_gcc_E_libc.py

@@ -16,7 +16,6 @@ sys.path.extend([".", ".."])
 
 from pycparser import parse_file
 
-
 if __name__ == "__main__":
     if len(sys.argv) > 1:
         filename = sys.argv[1]

{pycparser-3.0 → pycparser-3.11}/pycparser/__init__.py

@@ -7,10 +7,9 @@
 # Eli Bendersky [https://eli.thegreenplace.net/]
 # License: BSD
 # -----------------------------------------------------------------
-__all__ = ["c_lexer", "c_parser", "c_ast"]
-__version__ = "3.00"
+__all__ = ["c_ast", "c_lexer", "c_parser"]
+__version__ = "3.11"
 
-import io
 from subprocess import check_output
 
 from . import c_parser
@@ -91,7 +90,7 @@ def parse_file(
     if use_cpp:
         text = preprocess_file(filename, cpp_path, cpp_args)
     else:
-        with io.open(filename, encoding=encoding) as f:
+        with open(filename, encoding=encoding) as f:
             text = f.read()
 
     if parser is None:

{pycparser-3.0 → pycparser-3.11}/pycparser/_ast_gen.py

@@ -2,10 +2,10 @@
 # _ast_gen.py
 #
 # Generates the AST Node classes from a specification given in
-# a configuration file. This module can also be run as a script to
-# regenerate c_ast.py from _c_ast.cfg (from the repo root or the
-# pycparser/ directory). Use 'make check' to reformat the generated
-# file after running this script.
+# a configuration file. Run 'make regen-ast' from the repository root
+# to regenerate c_ast.py from _c_ast.cfg and format the code.
+# This module can also be run as a script (from the repo root or the
+# pycparser/ directory); then run 'make format' from the repo root.
 #
 # The design of this module was inspired by astgen.py from the
 # Python 2.5 code-base.
@@ -13,8 +13,8 @@
 # Eli Bendersky [https://eli.thegreenplace.net/]
 # License: BSD
 # -----------------------------------------------------------------
-from string import Template
 import os
+from string import Template
 from typing import IO
 
 
@@ -105,6 +105,8 @@ class NodeCfg:
             slots = "'coord', '__weakref__'"
             arglist = "(self, coord=None)"
 
+        # Keep coord and __weakref__ last: Node.__repr__ relies on their
+        # positions when iterating over the node's fields.
         src += f"    __slots__ = ({slots})\n"
         src += f"    def __init__{arglist}:\n"
 
@@ -142,8 +144,7 @@ class NodeCfg:
                 src += f"            yield self.{child}\n"
 
             for seq_child in self.seq_child:
-                src += f"        for child in (self.{seq_child} or []):\n"
-                src += "            yield child\n"
+                src += f"        yield from self.{seq_child} or []\n"
 
             if not (self.child or self.seq_child):
                 # Empty generator
@@ -164,9 +165,12 @@ _PROLOGUE_COMMENT = r"""#-------------------------------------------------------
 # This code was automatically generated from _c_ast.cfg
 #
 # Do not modify it directly. Modify the configuration file and
-# run the generator again.
+# run 'make regen-ast' from the repository root to regenerate and format it.
 # ** ** *** ** **
 #
+# The order of generated __slots__ is significant to Node.__repr__.
+# ruff: noqa: RUF023
+#
 # pycparser: c_ast.py
 #
 # AST Node classes.
@@ -178,14 +182,15 @@ _PROLOGUE_COMMENT = r"""#-------------------------------------------------------
 """
 _PROLOGUE_CODE = r'''
 import sys
-from typing import Any, ClassVar, IO, Optional
+from typing import IO, Any, ClassVar
+
 
 def _repr(obj):
     """
     Get the representation of an object, with dedicated pprint-like format for lists.
     """
     if isinstance(obj, list):
-        return '[' + (',\n '.join((_repr(e).replace('\n', '\n ') for e in obj))) + '\n]'
+        return '[' + (',\n '.join(_repr(e).replace('\n', '\n ') for e in obj)) + '\n]'
     else:
         return repr(obj)
 
@@ -194,7 +199,7 @@ class Node:
     """ Abstract base class for AST nodes.
     """
     attr_names: ClassVar[tuple[str, ...]] = ()
-    coord: Optional[Any]
+    coord: Any | None
     def __repr__(self):
         """ Generates a python representation of the current node
         """
@@ -217,7 +222,6 @@ class Node:
     def children(self):
         """ A sequence of all children that are Nodes
         """
-        pass
 
     def show(
         self,
@@ -227,7 +231,7 @@ class Node:
         showemptyattrs: bool = True,
         nodenames: bool = False,
         showcoord: bool = False,
-        _my_node_name: Optional[str] = None,
+        _my_node_name: str | None = None,
     ):
         """ Pretty print the Node and all its attributes and
             children (recursively) to a buffer.
@@ -261,7 +265,7 @@ class Node:
 
         if self.attr_names:
             def is_empty(v):
-                v is None or (hasattr(v, '__len__') and len(v) == 0)
+                return v is None or (hasattr(v, '__len__') and len(v) == 0)
             nvlist = [(n, getattr(self,n)) for n in self.attr_names \
                         if showemptyattrs or not is_empty(getattr(self,n))]
             if attrnames:

{pycparser-3.0 → pycparser-3.11}/pycparser/_c_ast.cfg

@@ -2,6 +2,8 @@
 # pycparser: _c_ast.cfg
 #
 # Defines the AST Node classes used in pycparser.
+# After editing, run 'make regen-ast' from the repository root to
+# regenerate pycparser/c_ast.py and format the code.
 #
 # Each entry is a Node sub-class name, listing the attributes
 # and child nodes of the class:
@@ -48,6 +50,8 @@ Compound: [block_items**]
 CompoundLiteral: [type*, init*]
 
 # type: int, char, float, string, etc.
+# value: source spelling. A string may retain adjacent quoted fragments to
+# preserve escape boundaries, e.g. "\x1" "a".
 #
 Constant: [type, value]
 
@@ -123,6 +127,18 @@ FuncDecl: [args*, type*]
 #
 FuncDef: [decl*, param_decls**, body*]
 
+# One association in a C11 generic selection.
+# type: Typename, or None for the default association
+# expr: the result expression for this association
+#
+GenericAssociation: [type*, expr*]
+
+# A C11 _Generic expression. All associations are preserved in source order.
+# expr: the controlling expression (not evaluated by C)
+# associations: a nonempty sequence of GenericAssociation nodes
+#
+GenericSelection: [expr*, associations**]
+
 Goto: [name]
 
 ID: [name]
@@ -154,6 +170,9 @@ PtrDecl: [quals, type*]
 
 Return: [expr*]
 
+# A static assertion declaration. The condition is preserved without evaluation.
+# message: a string Constant, or None for the message-less extension
+#
 StaticAssert: [cond*, message*]
 
 # name: struct tag name

{pycparser-3.0 → pycparser-3.11}/pycparser/ast_transforms.py

@@ -7,7 +7,8 @@
 # License: BSD
 # ------------------------------------------------------------------------------
 
-from typing import Any, List, Tuple, cast
+from copy import deepcopy
+from typing import Any, cast
 
 from . import c_ast
 
@@ -99,7 +100,7 @@ def fix_switch_cases(switch_node: c_ast.Switch) -> c_ast.Switch:
 
 
 def _extract_nested_case(
-    case_node: c_ast.Case | c_ast.Default, stmts_list: List[c_ast.Node]
+    case_node: c_ast.Case | c_ast.Default, stmts_list: list[c_ast.Node]
 ) -> None:
     """Recursively extract consecutive Case statements that are made nested
     by the parser and add them to the stmts_list.
@@ -111,8 +112,8 @@ def _extract_nested_case(
 
 
 def fix_atomic_specifiers(
-    decl: c_ast.Decl | c_ast.Typedef,
-) -> c_ast.Decl | c_ast.Typedef:
+    decl: c_ast.Decl | c_ast.Typedef | c_ast.Typename,
+) -> c_ast.Decl | c_ast.Typedef | c_ast.Typename:
     """Atomic specifiers like _Atomic(type) are unusually structured,
     conferring a qualifier upon the contained type.
 
@@ -127,17 +128,16 @@ def fix_atomic_specifiers(
         if not found:
             break
 
-    # Make sure to add an _Atomic qual on the topmost decl if needed. Also
-    # restore the declname on the innermost TypeDecl (it gets placed in the
-    # wrong place during construction).
+    # Match the declaration's qualifiers to the innermost TypeDecl, as for
+    # ordinary declarations. Qualifiers moved onto pointers belong only on
+    # those PtrDecl nodes. Also restore the name lost with the wrapper TypeDecl.
     typ: Any = decl
     while not isinstance(typ, c_ast.TypeDecl):
         try:
             typ = typ.type
         except AttributeError:
             return decl
-    if "_Atomic" in typ.quals and "_Atomic" not in decl.quals:
-        decl.quals.append("_Atomic")
+    decl.quals = typ.quals[:]
     if typ.declname is None:
         typ.declname = decl.name
 
@@ -145,8 +145,8 @@ def fix_atomic_specifiers(
 
 
 def _fix_atomic_specifiers_once(
-    decl: c_ast.Decl | c_ast.Typedef,
-) -> Tuple[c_ast.Decl | c_ast.Typedef, bool]:
+    decl: c_ast.Decl | c_ast.Typedef | c_ast.Typename,
+) -> tuple[c_ast.Decl | c_ast.Typedef | c_ast.Typename, bool]:
     """Performs one 'fix' round of atomic specifiers.
     Returns (modified_decl, found) where found is True iff a fix was made.
     """
@@ -168,7 +168,17 @@ def _fix_atomic_specifiers_once(
 
     assert isinstance(parent, c_ast.TypeDecl)
     assert grandparent is not None
-    cast(Any, grandparent).type = node.type
-    if "_Atomic" not in node.type.quals:
-        node.type.quals.append("_Atomic")
+    # Declaration specifiers are shared by comma-separated declarators. Copy
+    # the contained type before attaching qualifiers, coordinates, and a name.
+    typ = deepcopy(node.type)
+    if typ.coord is None:
+        # Preserve the declarator coord for _Atomic(T) so TypeDecl doesn't lose
+        # its location when we replace the wrapper Typename.
+        typ.coord = parent.coord
+    # Qualifiers outside _Atomic(T) apply to T itself. In particular, const in
+    # const _Atomic(int *) qualifies the pointer, not the pointed-to int.
+    typ.quals = parent.quals + typ.quals
+    if "_Atomic" not in typ.quals:
+        typ.quals.append("_Atomic")
+    cast(Any, grandparent).type = typ
     return decl, True