{"id":15650409,"url":"https://github.com/iamdefinitelyahuman/py-solc-ast","last_synced_at":"2025-08-21T23:32:51.019Z","repository":{"id":48430202,"uuid":"189413851","full_name":"iamdefinitelyahuman/py-solc-ast","owner":"iamdefinitelyahuman","description":"A tool for exploring the solc abstract syntax tree","archived":false,"fork":false,"pushed_at":"2024-03-20T18:08:49.000Z","size":4080,"stargazers_count":37,"open_issues_count":4,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-10T10:03:49.990Z","etag":null,"topics":["ethereum","py-solc","solc","solidity","web3py"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamdefinitelyahuman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-30T12:55:38.000Z","updated_at":"2024-10-03T14:54:11.000Z","dependencies_parsed_at":"2024-06-18T21:52:43.885Z","dependency_job_id":null,"html_url":"https://github.com/iamdefinitelyahuman/py-solc-ast","commit_stats":{"total_commits":97,"total_committers":4,"mean_commits":24.25,"dds":"0.28865979381443296","last_synced_commit":"6b49342f6633e3ec09e875a8a435fcb5667c0554"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamdefinitelyahuman%2Fpy-solc-ast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamdefinitelyahuman%2Fpy-solc-ast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamdefinitelyahuman%2Fpy-solc-ast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamdefinitelyahuman%2Fpy-solc-ast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamdefinitelyahuman","download_url":"https://codeload.github.com/iamdefinitelyahuman/py-solc-ast/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230542288,"owners_count":18242332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ethereum","py-solc","solc","solidity","web3py"],"created_at":"2024-10-03T12:34:31.549Z","updated_at":"2024-12-20T06:06:10.739Z","avatar_url":"https://github.com/iamdefinitelyahuman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# solc-ast\n\n[![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)\n\nA tool for exploring the Solidity abstrax syntrax tree as generated by the [solc](https://github.com/ethereum/solidity) compiler.\n\n## Installation\n\nYou can install the latest release via `pip`:\n\n```bash\n$ pip install py-solc-ast\n```\n\nOr clone the repo and use `setuptools`:\n\n```bash\n$ python setup.py install\n```\n\n## Usage\n\nFirst, 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).\n\n```python\n\u003e\u003e\u003e import json\n\u003e\u003e\u003e import solcx\n\u003e\u003e\u003e input_json = json.load(open('input.json'))\n\u003e\u003e\u003e output_json = solcx.compile_standard(input_json)\n```\n\nNext, 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.\n\n```python\n\u003e\u003e\u003e import solcast\n\u003e\u003e\u003e nodes = solcast.from_standard_output(output_json)\n\u003e\u003e\u003e nodes\n[\u003cSourceUnit iterable 'contracts/Token.sol'\u003e, \u003cSourceUnit iterable 'contracts/SafeMath.sol'\u003e]\n```\n\nYou can also generate a single `SourceUnit` directly from that source's AST:\n\n```python\n\u003e\u003e\u003e import solcast\n\u003e\u003e\u003e node = solcast.from_ast(output_json[\"sources\"][\"contracts/Token.sol\"][\"ast\"])\n\u003e\u003e\u003e node\n\u003cSourceUnit iterable 'contracts/Token.sol'\u003e\n```\n\n### Interacting with Nodes\n\nEach node has the following attributes:\n\n```python\n\u003e\u003e\u003e node\n\u003cFunctionDefinition iterable 'mul'\u003e\n\n\u003e\u003e\u003e node.depth  # Number of nodes between this node and the SourceUnit\n2\n\n\u003e\u003e\u003e node.offset  # Absolute source offsets as a (start, stop) tuple\n(1693, 2151)\n\n\u003e\u003e\u003e node.contract_id  # Contract ID as given by the standard compiler JSON\n2\n\n\u003e\u003e\u003e node.fields  # List of fields for this node\n['baseNodeType', 'documentation', 'id', 'implemented', 'kind', 'modifiers', 'name', 'nodeType', 'nodes', 'parameters', 'returnParameters', 'scope', 'src', 'stateMutability', 'superFunction', 'visibility']\n\n```\n\nFields 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.\n\nThe following additional fields are also available:\n\n* Most nodes have a `baseNodeType` field as defined in [grammar.py](solcast/grammar.py)\n* `ContractDefinition` nodes have `dependencies` and `libraries` fields that point to related `ContractDefition` nodes\n\nSome Examples:\n\n```python\n\u003e\u003e\u003e source_node\n\u003cSourceUnit iterable 'contracts/math/SafeMath.sol'\u003e\n\n\u003e\u003e\u003e source_node.keys()\n['absolutePath', 'children', 'contract_id', 'depth', 'exportedSymbols', 'id', 'is_child_of', 'is_parent_of', 'keys', 'nodeType', 'nodes', 'offset', 'parent', 'parents', 'src']\n\n\u003e\u003e\u003e source_node.nodes\n[\u003cPragmaDirective object\u003e, \u003cContractDefinition iterable 'SafeMath'\u003e]\n\n\u003e\u003e\u003e source_node[1]\n\u003cContractDefinition iterable 'SafeMath'\u003e\n\n\u003e\u003e\u003e source_node['SafeMath']\n\u003cContractDefinition iterable 'SafeMath'\u003e\n\n\u003e\u003e\u003e source_node['SafeMath'].keys()\n['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']\n\n\u003e\u003e\u003e source_node['SafeMath'].nodes\n[\u003cFunctionDefinition iterable 'add'\u003e, \u003cFunctionDefinition iterable 'sub'\u003e, \u003cFunctionDefinition iterable 'mul'\u003e, \u003cFunctionDefinition iterable 'div'\u003e, \u003cFunctionDefinition iterable 'mod'\u003e]\n\n\u003e\u003e\u003e source_node['SafeMath']['mul']\n\u003cFunctionDefinition iterable 'mul'\u003e\n\n\u003e\u003e\u003e source_node['SafeMath']['mul']\n[\u003cIfStatement object\u003e, \u003cVariableDeclarationStatement object\u003e, \u003cFunctionCall object\u003e, \u003cReturn object\u003e]\n```\n\n### Exploring the Tree\n\nThe `Node.children()` method is used to search and filter through child nodes of a given node. It takes any of the following keyword arguments:\n\n* `depth`: Number of levels of children to traverse. `0` returns only this node.\n* `include_self`: Includes this node in the results.\n* `include_parents`: Includes nodes that match in the results, when they also have child nodes that match.\n* `include_children`: If True, as soon as a match is found it's children will not be included in the search.\n* `required_offset`: Only match nodes with a source offset that contains this offset.\n* `offset_limits`: Only match nodes when their source offset is contained inside this source offset.\n* `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.\n* `exclude_filter`: Dictionary of `{'attribute': \"value\"}` that children cannot match.\n\n```python\n\u003e\u003e\u003e node = s['Token']['transfer']\n\u003e\u003e\u003e node.children(\n    include_children=False,\n    filters={'nodeType': \"FunctionCall\", \"expression.name\": \"require\"}\n)\n[\u003cFunctionCall\u003e]\n```\n\n`Node.parent()` and `Node.parents()` are used to travel back up the tree. They take the following arguments:\n\n* `depth`: Depth limit. If given as a negative value, it will be subtracted from this object's depth.\n* `filters`: Dictionary of `{'attribute': \"value\"}` that parents must match.\n\n`Node.parent()` returns one result, `Node.parents()` returns a list of matches.\n\n```python\n\u003e\u003e\u003e node.parents()\n[\u003cContractDefinition iterable 'Token'\u003e, \u003cSourceUnit iterable object 'contracts/Token.sol'\u003e]\n```\n\n## Tests\n\nTo run the test suite:\n\n```bash\n$ tox\n```\n\n## Development\n\nComments, 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.\n\n## License\n\nThis project is licensed under the [MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamdefinitelyahuman%2Fpy-solc-ast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamdefinitelyahuman%2Fpy-solc-ast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamdefinitelyahuman%2Fpy-solc-ast/lists"}