cxxheaderparser
A pure python C++ header parser that parses C++ headers in a mildly naive manner that allows it to handle many C++ constructs, including many modern (C++11 and beyond) features.
This is a complete rewrite of the CppHeaderParser library. CppHeaderParser
is really useful for some tasks, but it's implementation is a truly terrible
ugly hack built on top of other terrible hacks. This rewrite tries to learn
from CppHeaderParser and leave its ugly baggage behind.
Goals:
- Parse syntatically valid C++ and provide a useful (and documented!) pure python API to work with the parsed data
- Process incomplete headers (doesn't need to process includes)
- Provide enough information for binding generators to wrap C++ code
- Handle common C++ features, but it may struggle with obscure or overly complex things (feel free to make a PR to fix it!)
Non-goals:
- Does not produce a full AST, use Clang if you need that
- Not intended to validate C++, which means this will not reject all invalid C++ headers! Use a compiler if you need that
- Parser requires a C++ preprocessor. If you are parsing
headers that contain macros, you should preprocess your code using the
excellent pure python preprocessor pcpp
or your favorite compiler
- We have implemented support for PCPP, GCC, and MSVC -- but it is not enabled
by default. See the
cxxheaderparser.preprocessormodule for how to enable it.
- We have implemented support for PCPP, GCC, and MSVC -- but it is not enabled
by default. See the
- Probably won't be able to parse most IOCCC entries
There are two APIs available:
- A visitor-style interface to build up your own custom data structures
- A simple visitor that stores everything in a giant data structure
Live Demo
A pyodide-powered interactive demo is at https://robotpy.github.io/cxxheaderparser/
Documentation
Documentation can be found at https://cxxheaderparser.readthedocs.io
Install
Requires Python 3.6+, no non-stdlib dependencies if using Python 3.7+.
pip install cxxheaderparser
Usage
To see a dump of the data parsed from a header:
# pprint format
python -m cxxheaderparser myheader.h
# JSON format
python -m cxxheaderparser --mode=json myheader.h
# dataclasses repr format
python -m cxxheaderparser --mode=repr myheader.h
# dataclasses repr format (formatted with black)
python -m cxxheaderparser --mode=brepr myheader.h
See the documentation for anything more complex.
Bugs
This should handle even complex C++ code with few problems, but there are almost certainly weird edge cases that it doesn't handle. Additionally, not all C++17/20 constructs are supported yet (but contributions welcome!).
If you find an bug, we encourage you to submit a pull request! New changes will only be accepted if there are tests to cover the change you made (and if they don’t break existing tests).
It's really easy to add new tests, see the README in the tests directory.
Author
cxxheaderparser was created by Dustin Spicuzza
Credit
- Partially derived from and inspired by the
CppHeaderParserproject originally developed by Jashua Cloutier - An embedded version of PLY is used for lexing tokens
- Portions of the lexer grammar and other ideas were derived from pycparser
- The source code is liberally sprinkled with comments containing C++ parsing grammar mostly derived from the Hyperlinked C++ BNF Grammar
- cppreference.com has been invaluable for understanding many of the weird quirks of C++, and some of the unit tests use examples from there
- Compiler Explorer has been invaluable for validating my understanding of C++ by allowing me to quickly type in quirky C++ constructs to see if they actually compile
License
BSD License
Metadata
Release files for cxxheaderparser 2.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cxxheaderparser-2.2.0.tar.gz | 60.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cxxheaderparser-2.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 128.1 kB
Release files / cxxheaderparser-2.2.0.tar.gz
| Download URL | cxxheaderparser-2.2.0.tar.gz |
|---|---|
| Size | 60.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
220f9f4efadfbc8ebbbdea82ae0ba0e11d82f118efce3b701f19945a937cb515
|
|
BLAKE2b-256 checksum How to use checksums |
1ec3546f5d26067f412818b353f28037d480c02f21a1d35b1d1248735c0eaabd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / cxxheaderparser-2.2.0-py3-none-any.whl
| Download URL | cxxheaderparser-2.2.0-py3-none-any.whl |
|---|---|
| Size | 67.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cccf8db541be342fc6e2450dec168a77bafe87a65a4a89b547b529c92dbe792e
|
|
BLAKE2b-256 checksum How to use checksums |
eb7f9785e4e42e0e3481471bbb008f737595944cf03a91e23e00ac2b4a04b170
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency log
