pyVHDLModelTreesitter

[domWalters]

Hi,

Not an issue, more of a signpost to something people might find useful.

Last year I spent some of my free time developing a library that creates a pyVHDLModel from inspection of a tree-sitter parse of a VHDL source file as an alternative to pyVHDLParser or similar.

I haven't worked on it for a while, but something I'm doing at work has prompted me to freshen it up a bit and actually package it to pypi.

The source is available here: https://gitlab.com/dawalters/pyVHDLModelTreesitter

It is nowhere close to complete, but you can at the very least:

• Parse a document containing Entity declarations.
  • Other design units are not supported atm.
    • NotImplementedError will be raised if anything unsupported is found.
• Obtain the LibraryClauses, UseClauses, GenericConstantInterfaceItems, and PortSignalInterfaceItems related to an Entity.
  • GenericConstantInterfaceItem and PortSignalInterfaceItem support SimpleSubtypeSymbols only.

Some examples I run tests against can be seen here.

I'm gonna be adding some more features in the short term, primarily so I can read arbitrary files from an existing library and pull generics and ports for use in some documentation / git error checking hooks.

---

Note: There is a reasonably high chance I have misunderstood, or misinterpreted parts of pyVHDLModel. So the output may not be exactly correct.

Happy to make changes where this has happened.

[Paebbels]

Hello @domWalters.

As far as I know, tree-sitter has (had?) no VHDL support. Have you written your own code on top of tree-sitter to get VHDL parsed?

Does your implementation support comments? pyVHDLModel can annotate comments to objects like entities or ports. That's somehow my final goal to extract documentation and use it in Sphinx.

For the NotImplementedError error:
pyVHDLModel and other of my projects use pyTooling for some basic functionality. One fundamental element I added lately is warnings. See here: https://pytooling.github.io/pyTooling/Warning/index.html. Similar to an exception, you raise a Warning or CriticalWarning which traverses up int he call hierarchy. A with statement can collect the warning e.g. into a local list object. But differently to an exception, where execution is aborted when traversing upwards, execution continues after afterwards. Normal warnings can be collected, critical warnings must be collected, otherwise the cause an exception.

This technique is used in pyGHDL.dom for unsupported features. The list of collected warnings in in order of execution and you could implement a handler e.g. to print a warning or silently ignore them.

P.S.
If you have collected enough items like entity, architecture, use clause, packages, etc. You can lat pyVHDLModel generate a dependency graph and from there you get the hierarchy and the compile order graphs.

Just ask questions or open issues with questions in case you need help or details on undocumented items.

[domWalters]

As far as I know, tree-sitter has (had?) no VHDL support. Have you written your own code on top of tree-sitter to get VHDL parsed?

There was a flaky tree-sitter-vhdl about 5-6 years ago: https://github.com/alemuller/tree-sitter-vhdl

There was then this rewrite which became stable last year: https://github.com/jpt13653903/tree-sitter-vhdl

A year ago I requested that they host the python binding on PyPi: jpt13653903/tree-sitter-vhdl#42

I have been using these in nvim to perform syntax highlighting for multiple years at this point.

By way of an example of how the tree-sitter structure looks, here is the nvim :InspectTree of one of my test VHDL files:

All I'm doing in pyVHDLModelTreesitter at this point is a mix of running queries on the tree-sitter output (example of a query that extracts interface_declaration elements to make PortSignalInterfaceItems), and manually interrogating portions of the tree (example of how I'm creating *Literal objects).

Does your implementation support comments? pyVHDLModel can annotate comments to objects like entities or ports. That's somehow my final goal to extract documentation and use it in Sphinx.

It does not currently, but this would be possible (at a guess, relatively trivial) to implement.

Here's the same example from above with comments added showing how they appear in treesitter:

So you'd just find the next node at the same level of hierarchy, check it's a line_comment, and it's on the same line index.

For the NotImplementedError error: pyVHDLModel and other of my projects use pyTooling for some basic functionality. One fundamental element I added lately is warnings. See here: https://pytooling.github.io/pyTooling/Warning/index.html. Similar to an exception, you raise a Warning or CriticalWarning which traverses up int he call hierarchy. A with statement can collect the warning e.g. into a local list object. But differently to an exception, where execution is aborted when traversing upwards, execution continues after afterwards. Normal warnings can be collected, critical warnings must be collected, otherwise the cause an exception.

This technique is used in pyGHDL.dom for unsupported features. The list of collected warnings in in order of execution and you could implement a handler e.g. to print a warning or silently ignore them.

This sounds like a good idea, I'll probably move to this approach. Thanks.

[Paebbels]

I'll add your project as a generator for pyVHDLModel.

[Paebbels]

I get this error message:

Python 3.14.2 free-threading build (tags/v3.14.2:df79316, Dec  5 2025, 17:11:07) [MSC v.1944 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from pyVHDLModelTreesitter import Document
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    from pyVHDLModelTreesitter import Document
  File "C:\Program Files\Python3.14\Lib\site-packages\pyVHDLModelTreesitter\__init__.py", line 21, in <module>
    from . import DesignUnit, Expression, Interface, Name, Symbol, treesitter
  File "C:\Program Files\Python3.14\Lib\site-packages\pyVHDLModelTreesitter\DesignUnit.py", line 25, in <module>
    from pyVHDLModelTreesitter.Interface import (
    ...<2 lines>...
    )
  File "C:\Program Files\Python3.14\Lib\site-packages\pyVHDLModelTreesitter\Interface.py", line 34, in <module>
    from pyVHDLModelTreesitter.treesitter import get_node_or_raise
  File "C:\Program Files\Python3.14\Lib\site-packages\pyVHDLModelTreesitter\treesitter\__init__.py", line 11, in <module>
    from pyVHDLModelTreesitter.treesitter import query
  File "C:\Program Files\Python3.14\Lib\site-packages\pyVHDLModelTreesitter\treesitter\query.py", line 9, in <module>
    import tree_sitter
  File "C:\Program Files\Python3.14\Lib\site-packages\tree_sitter\__init__.py", line 5, in <module>
    from ._binding import (
    ...<14 lines>...
    )
ModuleNotFoundError: No module named 'tree_sitter._binding'

[domWalters]

That looks like the tree-sitter package has not installed properly for some reason: tree-sitter/py-tree-sitter#280

Try force the reinstall:

pip install --force-reinstall --verbose tree-sitter

It should look similar to this:

.venv/lib/python3.10/site-packages/tree_sitter
├── __init__.py
├── __init__.pyi
├── _binding.cpython-310-x86_64-linux-gnu.so
└── py.typed

I've not tried it on a windows setup, so there may be some kind of platform issue.

[Paebbels]

C:\Users\Patrick_Lehmann> py -3.14 -m pip install --force-reinstall --verbose tree-sitter
Using pip 26.0.1 from C:\Program Files\Python3.14\Lib\site-packages\pip (python 3.14)
  Link requires a different Python (3.14.2 not in: '<3.12,>=3.8'): https://files.pythonhosted.org/packages/6b/46/c28e3280b4219cb662dd826377c511a4ef9267da471a7859c911e596e785/tree-sitter-0.21.0.tar.gz (from https://pypi.org/simple/tree-sitter/) (requires-python:<3.12,>=3.8)
Collecting tree-sitter
  Obtaining dependency information for tree-sitter from https://files.pythonhosted.org/packages/03/87/af9604ebe275a9345d88c3ace0cf2a1341aa3f8ef49dd9fc11662132df8a/tree_sitter-0.25.2-cp314-cp314-win_amd64.whl.metadata
  Using cached tree_sitter-0.25.2-cp314-cp314-win_amd64.whl.metadata (10 kB)
Using cached tree_sitter-0.25.2-cp314-cp314-win_amd64.whl (130 kB)
Installing collected packages: tree-sitter
  Attempting uninstall: tree-sitter
    Found existing installation: tree-sitter 0.25.2
    Uninstalling tree-sitter-0.25.2:
      Removing file or directory c:\program files\python3.14\lib\site-packages\tree_sitter-0.25.2.dist-info\
      Removing file or directory c:\program files\python3.14\lib\site-packages\tree_sitter\
      Successfully uninstalled tree-sitter-0.25.2
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
pyvhdlmodeltreesitter 0.2.2 requires pyvhdlmodel<=0.31.3, but you have pyvhdlmodel 0.33.1 which is incompatible.
Successfully installed tree-sitter-0.25.2

C:\Program Files\Python3.14\Lib\site-packages\tree_sitter> ll

    Directory: C:\Program Files\Python3.14\Lib\site-packages\tree_sitter

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          17.04.2026    20:10                __pycache__
-a---          17.04.2026    20:10           1754 __init__.py
-a---          17.04.2026    20:10          14226 __init__.pyi
-a---          17.04.2026    20:10         236032 _binding.cp314-win_amd64.pyd
-a---          17.04.2026    20:10              0 py.typed

*.pyd is a Python dynamic library created by Cython.

[Paebbels]

tree-sitter is broken on Python 3.14. I could load the file in 3.13.

[Paebbels]

OK, I'm now here:

>>> doc = Document.from_file("src/PoC/my_config_GENERIC.vhdl")
Traceback (most recent call last):
  File "<python-input-2>", line 1, in <module>
    doc = Document.from_file("src/PoC/my_config_GENERIC.vhdl")
  File "C:\Program Files\Python3.13\Lib\site-packages\pyVHDLModelTreesitter\_root.py", line 124, in from_file
    raise NotImplementedError(message)
NotImplementedError: Node of type 'package_declaration' is not supported

Looks like packages are not yet supported.
(I think you mentioned or documented it somewhere.)

>>> doc = Document.from_file("src/BigDesign/TopLevel_A0.2008.vhdl")
Traceback (most recent call last):
  File "<python-input-3>", line 1, in <module>
    doc = Document.from_file("src/BigDesign/TopLevel_A0.2008.vhdl")
  File "C:\Program Files\Python3.13\Lib\site-packages\pyVHDLModelTreesitter\_root.py", line 108, in from_file
    LibraryClause.from_treesitter_node(context_child),
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
  File "C:\Program Files\Python3.13\Lib\site-packages\pyVHDLModelTreesitter\DesignUnit.py", line 72, in from_treesitter_node
    library_namespace_nodes = get_nodes_or_raise(
        node,
    ...<2 lines>...
        LibraryNamespaces.TEXT,
    )
  File "C:\Program Files\Python3.13\Lib\site-packages\pyVHDLModelTreesitter\treesitter\_utils.py", line 30, in get_nodes_or_raise
    raise MissingNodeError(node, query_text, name)
pyVHDLModelTreesitter._error.MissingNodeError: Capture '@library': Not found in node: library PoC;: (library_clause (logical_name_list library: (identifier)))

I'm using BigDesign for testing: https://github.com/Paebbels/BigDesign

When loading a wrong filename I get:

>>> doc = Document.from_file("src/PoC/my_config.vhdl")
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    doc = Document.from_file("src/PoC/my_config.vhdl")
  File "C:\Program Files\Python3.13\Lib\site-packages\pyVHDLModelTreesitter\_root.py", line 91, in from_file
    tree = PARSER.parse(path.read_bytes())
                        ~~~~~~~~~~~~~~~^^
  File "C:\Program Files\Python3.13\Lib\pathlib\_abc.py", line 625, in read_bytes
    with self.open(mode='rb') as f:
         ~~~~~~~~~^^^^^^^^^^^
  File "C:\Program Files\Python3.13\Lib\pathlib\_local.py", line 537, in open
    return io.open(self, mode, buffering, encoding, errors, newline)
           ~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: 'src\\PoC\\my_config.vhdl'

I recommend to implement you own Exceptions and implement exception chaining. Either you run a path.exists() before and create an exception, or you try-except it.

Try-except example from pyGHDL.dom:

try:
  ...
except FileNotFoundError as ex:
  raise DOMException(f"Sourcefile '{self._filename}' not found.") from ex

This allows later for precise error reporting and nice error printing using ex.__cause__.

[domWalters]

I've got a fix for that @library capture; turns out ieee, std, and work all parse as library_namespace but custom libraries are just identifier in the tree-sitter output.

Gonna put in as many warnings on missing features (rather than exceptions), then I'll push a new version to pypi.

[Paebbels]

turns out ieee, std, and work all parse as library_namespace

From language side, only work is correct as a special name. All others are always identifiers.

[Paebbels]

I noticed, I missed to answer on #100.