Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/iamdefinitelyahuman/py-solc-ast

A tool for exploring the solc abstract syntax tree
https://github.com/iamdefinitelyahuman/py-solc-ast

ethereum py-solc solc solidity web3py

Last synced: about 11 hours ago
JSON representation

A tool for exploring the solc abstract syntax tree

Awesome Lists containing this project

README 

        
# 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

[, ]

```



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



```



### Interacting with Nodes



Each node has the following attributes:



```python

>>> node



>>> 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



>>> 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

[, ]



>>> source_node[1]



>>> source_node['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

[, , , , ]



>>> source_node['SafeMath']['mul']



>>> source_node['SafeMath']['mul']

[, , , ]

```



### 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"}

)

[]

```



`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()

[, ]

```



## 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).