Metadata-Version: 2.1
Name: py-solc-ast
Version: 1.2.6
Summary: A tool for exploring the abstract syntax tree generated by solc.
Home-page: https://github.com/iamdefinitelyahuman/py-solc-ast
Author: Ben Hauser
Author-email: ben@hauser.id
License: MIT
Description: # solc-ast
        
        [![Pypi Status](https://img.shields.io/pypi/v/py-solc-ast.svg)](https://pypi.org/project/py-solc-ast/) [![Build Status](https://img.shields.io/github/workflow/status/iamdefinitelyahuman/py-solc-ast/main%20workflow/master)](https://github.com/iamdefinitelyahuman/py-solc-ast/actions) [![Coverage Status](https://img.shields.io/codecov/c/github/iamdefinitelyahuman/py-solc-ast)](https://codecov.io/gh/iamdefinitelyahuman/py-solc-ast)
        
        A tool for exploring the Solidity abstrax syntrax tree as generated by the [solc](https://github.com/ethereum/solidity) compiler.
        
        ## Installation
        
        You can install the latest release via `pip`:
        
        ```bash
        $ pip install py-solc-ast
        ```
        
        Or clone the repo and use `setuptools`:
        
        ```bash
        $ python setup.py install
        ```
        
        ## Usage
        
        First, use [py-solc-x](https://github.com/iamdefinitelyahuman/py-solc-x) to compile your contracts to the [standard JSON output format](https://solidity.readthedocs.io/en/latest/using-the-compiler.html#output-description).
        
        ```python
        >>> import json
        >>> import solcx
        >>> input_json = json.load(open('input.json'))
        >>> output_json = solcx.compile_standard(input_json)
        ```
        
        Next, import `solcast` and initialize using `from_standard_output_json` or `from_standard_output`. This returns a list of `SourceUnit` objects, which each represent the base AST node in a Solidity source file.
        
        ```python
        >>> import solcast
        >>> nodes = solcast.from_standard_output(output_json)
        >>> nodes
        [<SourceUnit iterable 'contracts/Token.sol'>, <SourceUnit iterable 'contracts/SafeMath.sol'>]
        ```
        
        You can also generate a single `SourceUnit` directly from that source's AST:
        
        ```python
        >>> import solcast
        >>> node = solcast.from_ast(output_json["sources"]["contracts/Token.sol"]["ast"])
        >>> node
        <SourceUnit iterable 'contracts/Token.sol'>
        ```
        
        ### Interacting with Nodes
        
        Each node has the following attributes:
        
        ```python
        >>> node
        <FunctionDefinition iterable 'mul'>
        
        >>> node.depth  # Number of nodes between this node and the SourceUnit
        2
        
        >>> node.offset  # Absolute source offsets as a (start, stop) tuple
        (1693, 2151)
        
        >>> node.contract_id  # Contract ID as given by the standard compiler JSON
        2
        
        >>> node.fields  # List of fields for this node
        ['baseNodeType', 'documentation', 'id', 'implemented', 'kind', 'modifiers', 'name', 'nodeType', 'nodes', 'parameters', 'returnParameters', 'scope', 'src', 'stateMutability', 'superFunction', 'visibility']
        
        ```
        
        Fields mostly follow the expected [AST grammar](https://solidity.readthedocs.io/en/latest/miscellaneous.html#language-grammar). One notable difference: `Block` nodes are omitted and the body of each `Block` is available within it's parent as the attribute `nodes`. Nodes containing a body are iterable and can be accessed with list-like syntax. Additionally, any child node with a `name` field is accessible using dict-like syntax.
        
        The following additional fields are also available:
        
        * Most nodes have a `baseNodeType` field as defined in [grammar.py](solcast/grammar.py)
        * `ContractDefinition` nodes have `dependencies` and `libraries` fields that point to related `ContractDefition` nodes
        
        Some Examples:
        
        ```python
        >>> source_node
        <SourceUnit iterable 'contracts/math/SafeMath.sol'>
        
        >>> source_node.keys()
        ['absolutePath', 'children', 'contract_id', 'depth', 'exportedSymbols', 'id', 'is_child_of', 'is_parent_of', 'keys', 'nodeType', 'nodes', 'offset', 'parent', 'parents', 'src']
        
        >>> source_node.nodes
        [<PragmaDirective object>, <ContractDefinition iterable 'SafeMath'>]
        
        >>> source_node[1]
        <ContractDefinition iterable 'SafeMath'>
        
        >>> source_node['SafeMath']
        <ContractDefinition iterable 'SafeMath'>
        
        >>> source_node['SafeMath'].keys()
        ['baseContracts', 'children', 'contractDependencies', 'contractKind', 'contract_id', 'dependencies', 'depth', 'documentation', 'fullyImplemented', 'id', 'is_child_of', 'is_parent_of', 'keys', 'libraries', 'linearizedBaseContracts', 'name', 'nodeType', 'nodes', 'offset', 'parent', 'parents', 'scope', 'src']
        
        >>> source_node['SafeMath'].nodes
        [<FunctionDefinition iterable 'add'>, <FunctionDefinition iterable 'sub'>, <FunctionDefinition iterable 'mul'>, <FunctionDefinition iterable 'div'>, <FunctionDefinition iterable 'mod'>]
        
        >>> source_node['SafeMath']['mul']
        <FunctionDefinition iterable 'mul'>
        
        >>> source_node['SafeMath']['mul']
        [<IfStatement object>, <VariableDeclarationStatement object>, <FunctionCall object>, <Return object>]
        ```
        
        ### Exploring the Tree
        
        The `Node.children()` method is used to search and filter through child nodes of a given node. It takes any of the following keyword arguments:
        
        * `depth`: Number of levels of children to traverse. `0` returns only this node.
        * `include_self`: Includes this node in the results.
        * `include_parents`: Includes nodes that match in the results, when they also have child nodes that match.
        * `include_children`: If True, as soon as a match is found it's children will not be included in the search.
        * `required_offset`: Only match nodes with a source offset that contains this offset.
        * `offset_limits`: Only match nodes when their source offset is contained inside this source offset.
        * `filters`: Dictionary of `{'attribute': "value"}` that children must match. Can also be given as a list of dicts, children that match any of the dicts will be returned.
        * `exclude_filter`: Dictionary of `{'attribute': "value"}` that children cannot match.
        
        ```python
        >>> node = s['Token']['transfer']
        >>> node.children(
            include_children=False,
            filters={'nodeType': "FunctionCall", "expression.name": "require"}
        )
        [<FunctionCall>]
        ```
        
        `Node.parent()` and `Node.parents()` are used to travel back up the tree. They take the following arguments:
        
        * `depth`: Depth limit. If given as a negative value, it will be subtracted from this object's depth.
        * `filters`: Dictionary of `{'attribute': "value"}` that parents must match.
        
        `Node.parent()` returns one result, `Node.parents()` returns a list of matches.
        
        ```python
        >>> node.parents()
        [<ContractDefinition iterable 'Token'>, <SourceUnit iterable object 'contracts/Token.sol'>]
        ```
        
        ## Tests
        
        To run the test suite:
        
        ```bash
        $ tox
        ```
        
        ## Development
        
        Comments, questions, criticisms and pull requests are welcomed! Feel free to open an issue if you encounter a problem or would like to suggest a new feature.
        
        ## License
        
        This project is licensed under the [MIT license](LICENSE).
        
Keywords: ethereum,solidity,solc,ast
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6, <4
Description-Content-Type: text/markdown
