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 | Provenance | Actions |
|---|---|---|---|---|
| cxxheaderparser-2.2.0.tar.gz | 60.7 kB | With provenance | Details for cxxheaderparser-2.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cxxheaderparser-2.2.0-py3-none-any.whl | Python 3 | none | any | Details for cxxheaderparser-2.2.0-py3-none-any.whl |
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 logSecurity for cxxheaderparser 2.2.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cxxheaderparser-2.2.0.tar.gz
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 logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.