Repository navigation
Releases
v0.9.4
Fixed
- A short Swift name can no longer build a hundred megabytes before it is refused. A
substitution can be repeated two thousand times and each level of nesting multiplies
that, so a 50-character name spelled out to 100 million characters, and took eight
seconds, beforemax_outputwas looked at. The bound now stops the spelling as it is
written. A name may also copy at most four million characters out of its word table,
where 40,000 characters used to ask for 400 MB. - An MSVC name's back-references are counted as they are read. A digit stands for a
whole earlier name or parameter, and the scopes and parameters were only measured one
at a time, so 60,000 characters of?f@AAA...@111...@YAXXZtook three gigabytes to
refuse. It now takes a few megabytes. - An Itanium name's back-references are counted in all.
S_andT_stand for a
type of any size, each type was held tomax_outputby itself, and a parameter list
or an argument list of them was only measured after it had been joined: 12,000
characters took 780 MB to refuse. What a name's back-references stand for is now
capped at sixteen timesmax_output, twice over what any of 394,000 real names needs
relative to its own output. - A Rust v0 name full of back-references to one const is read in linear time. Each
one scanned the const's digits again a character at a time, so 62,000 characters took
nine seconds. It now takes a few hundredths. - Detecting a JNI name no longer goes quadratic on a long one. Every
__was tried
as the signature separator, decoding the whole name each time, before any length
limit applied: 1.2 million characters took a minute. The tries are now rationed by
the name's length. elf_image()andmacho_image()refuse a file whose segments cover it many times
over. Each segment is copied, and a 218 KB ELF with four thousand program headers
that each name the whole file took 1.7 GB. Segments that add up to more than twice
the file are now aMalformedImage.- A control character that only appears once a name is decoded no longer reaches the
output. 0.9.3 refused a name that held one and would spell it. Go's%1b, JNI's
_0001band a Swift punycoded identifier decode to one from clean text, so
go:main.f%1b%5b31mXstill came back with an escape sequence in it. Every spelling is
now checked,demangle_type()'s anddemangle_symbolic()'s included. demangle --strictwrites a name's control characters as escapes in its
complaint. The error already did; the name in front of it was written raw, so a
name could set the terminal's title or clear the screen from standard error.- The cache no longer keeps an entry bigger than it is allowed to be. A name refused
for its length was cached all the same, and one entry could be any size: a 30 MB name
stayed held at 240 MB against a budget of 96. A name overmax_inputis not cached,
and neither is any entry heavier than half the budget. - D names keep the caller's limits.
_Dmainwas answered beforemax_inputand
max_outputwere looked at, andmax_depthnever reached the parser, so
Limits(max_depth=8)read a type nested two hundred deep. A run of type qualifiers
is also joined once: sixty thousand of them took seconds, each wrapping the whole
spelling again.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.9.3
Fixed
- An ELF version suffix no longer slips past
max_inputandmax_output. The suffix
is cut off before the name is parsed and was added back without being counted, so
_Z1fv@followed by a megabyte of anything came back a megabyte long. The bounds now
cover the whole symbol and what is rendered for it. - A control character in a name no longer reaches the output. An Itanium or Rust
name with an escape sequence in a version suffix, a clone suffix or an identifier was
spelled with it, where MSVC and Swift names were already refused.demangle()now
hands such a name back unchanged anddemangle_strict()raisesParseError.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.9.2
Fixed
- A short MSVC name can no longer take minutes. A dynamic initialiser nested in
another was read twice at each level, so twenty of them in a 540-character name took ten
seconds and every further one doubled it. It now takes milliseconds. - A short g++ 2.x name can no longer hang
demangle()or run it out of memory.
f__FiN99999999_0repeats an argument a hundred million times andH999999999_
claims as many template arguments, and both are read by detection without being asked
for. A name now gets 16,384 arguments in all, and a template can't claim more arguments
than it has characters left.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.9.1
Changed
- A Rust name behind a PE import thunk reads as Rust.
__imp__ZN...17h<hash>Ewas
read as C++, the way llvm-cxxfilt reads it, which kept the hash and left escapes like
$LT$in. It is nowimport thunk forplus the same spelling the name gets on its
own, and v0 names behind the prefix are read too. Windows-gnu Rust binaries are full
of these: one RustyStealer sample has 686.
Fixed
- Objective-C++ names with
id<P>orClass<P>read every later back-reference
right. Under protocols clang writesidandClassas builtins, which take no
substitution entry, and they were given one, so_Z1pPU11objcproto1P11objc_objectS0_
came outp(id<P>, objc_object<P>)instead ofp(id<P>, id<P>), and some names were
refused. llvm-cxxfilt and GNU c++filt have the same bug. Found in the symbol table of
the SeaFlower macOS sample. - Swift reads the
Mddemangling cache variable. Upstream's mangler now writes
$s4main5KlassCACYTcMdwhere it wrote...MD, and the name came back unchanged. Both
spellings read, and so does the newMR(mangled name ref for type metadata for).
The Swift reference build moves to swiftlang/swiftmain@251fbaad, and
swift-upstream.txttakes the edited row and threeMnTwavectors: 538 / 538.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.9.0
Changed
- The playground runs on Pyodide 0.29.5 (Python 3.13), up from 0.26.4, in a module
worker. The page downloads 1.5 MB less to start, and a build removes runtime files the
pin no longer names, so an old release's loader is never served next to the new one. Spelling()takes onlyleftandright.is_function,is_array,ref_kind
andmemberscome from the class now, through private subclasses the builder picks,
so a plain name costs two attribute stores rather than six and Itanium runs about 2%
fewer instructions. Code that passed those keywords should callSPELLING_BUILDER's
methods instead.
Performance
- Itanium names read about twice as fast on CPython. The wheels for Linux, macOS
and Windows on CPython 3.11 to 3.14 now carry the reader, the spelling builder and the
Itanium parser compiled with mypyc, from the same source: 19 us a name cold over the
libstdc++ and real-world corpora, against 40 for 0.6.0 and for the pure code. The
output is the same byte for byte. PyPy, free-threaded builds, other platforms and
--no-binaryinstalls get the pure wheel, which is unchanged. - The playground reads its first name about half a second sooner. A site built on
Python 3.13, the runtime's own, ships the package as bytecode, so the browser no longer
compiles it on every visit.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.8.0
Changed
LimitExceededis no longer aParseError. It derives fromDemanglingError
directly, soexcept ParseErrorstops taking "too large to read under these limits"
for "malformed". Code that caughtParseErrorto cover both should catch
DemanglingError. It has nopositionany more; it never had one to give.demangle_all()refuses a single name. Astris an iterable ofstr, so
demangle_all("_Z1fv")came back as['_', 'Z', '1', 'f', 'v']. Onestror bytes
object is aTypeErrornow.demangle_text()andfind_symbols()say what was wrong with atextthat is not
astr. It was aTypeErrorout ofre, andfind_symbols()raised it at the
firstnext()rather than at the call.
Added
Node.find()takes a node class as well as akindstring:tree.find(Name)
yieldsNamenodes, subclasses included, and a type checker then knows their fields.CacheStats, theTypedDictthatcache_stats()returns, in place of
dict[str, Any].- Annotations on the rest of the core: the node constructors,
Reader, the registry
and the fields ofLanguagePluginandStyle, so a scheme written against them is
type-checked.DemanglingErrordeclares themangledevery subclass sets.
Performance
- MSVC names read about 1.4x faster cold over a symbol table (msvc-boost.txt: 64 to
46 us a name). The template instantiations a name spells out are remembered across
names now, not just within one, so a table that writes out the same
std::basic_string<...>thousands of times reads it once. The memo is bounded at
about 8M characters andcache_clear()empties it. Output is unchanged. - Swift names read about 8% faster cold (swift-real-world.txt: 53 to 49 us a name, 17%
fewer instructions). Identifiers are split into words by a regular expression rather
than a loop over characters, and the commonest productions, nominal types, tuples and
function types, pop the stack directly instead of through helpers. Output is
unchanged.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.7.1
Fixed
- A name nested past the interpreter's stack is a
LimitExceededon PyPy too. On
PyPy theRecursionErrorcan overflow the stack a second time while it unwinds, and
PyPy then raisesTypeError("couldn't record exception context ...")in its place.
demangle_strict(),parse()anddemangle_type()reported that as
ParseError: ... parser failed; they now report the recursion bound it stands for, as
they do on CPython, which is unaffected. - The MSVC parser no longer runs PyPy's stack out. A name nested thousands of levels
deep through nested symbols or local scopes, read underRELAXED_LIMITS, could abort
the PyPy process outright ("Fatal Python error: Aborted"), which noexceptcan catch.
On PyPy it now asks the interpreter at each new depth whether its stack is nearly
full, and stops there with the sameLimitExceeded("recursion depth"). CPython makes
no extra call. style()andLimitsrefuse values no parser can use.style("llvm", msvc=False)
andLimits(max_depth="64")were accepted, and every name then failed inside the
parser, whichdemangle()reports by handing the name back: the whole table came back
unread with no error. Both are aValueErrornow, as is an options object for a scheme
that takes none. A misspelt option,msvc={"caling_convention": False}, was a
TypeErrorfromdataclasses.replace; it is theValueErrorstyle()documents, and
names the scheme's options. Code that caughtTypeErrorthere has to catch
ValueErrornow.
Changed
- The API reference shows types. Signatures on the site carry their annotations and
return types, the Public API page's contents list the functions rather than the
modules they live in, and the navigation is grouped into guide, reference,
conformance and development. - The rest of the public surface is annotated.
Node's methods, the exceptions'
constructors,register_language,register_style,load_pluginsand
demangle_streamhad no annotations, soparse(name).spell()orerror.position
reached a caller's type checker asUnknown.walk(),find()andchildren()
yieldAny: which fields a node has depends on itskind. - The README is a page, not the manual. What the library does, how to install it, a
quick start and where to read on; the tour of every entry point and the command line
moved, nearly word for word, to a new Using the library
page. The two playground descriptions,docs/playground.mdandplayground/README.md,
said the same thing twice; the page keeps what the playground does and the folder's
README what its files are and how to run it. - Every
>>>example on every page is run.tests/test_docs.pyruns them with
doctest, page by page, where before only a hand-kept list of the README's outputs was
checked and the other pages' examples were only compiled.
Removed
- The October audit and performance-pass reports,
AUDIT.mdand
benchmarks/performance.md, with the paired before-and-after scripts and result files
they cited (benchmarks/audit_*.py,benchmarks/bench_playground_bridge.pyand
benchmarks/results/). Each compared against one fixed older revision, so none
measures anything today; what they found is in the 0.5.2 and later entries below.
bench.py,compare.py,end_to_end.pyandbench_playground_browser.pystay, and
CONTRIBUTING.md now says what the last two are for. - The second copy of the playground archive under
docs/assets/, and the worker's
fallback to it. The playground has loadedplayground/assets/demangle.zipsince it
became a page of its own.
Security
- CI and the release build install every tool by hash, from files in the repository.
The workflows ranpip install --upgrade pip uv, resolved the test, lint and docs
dependencies afresh on each run and, in the job that builds what is published, installed
the newestbuild,twineandhatchlingwith everything those depend on: a hijacked
release of any of them would have run there within the hour, and could have changed the
wheel before it was signed. uv is now pinned by hash intools/uv-requirements.txt,
everything else is installed fromuv.lockwith--require-hashes
(tools/ci-install.sh), hatchling is locked there too as abuilddependency group,
and distributions are built without isolation and without a network. The release job
no longer installs twine; CI runstwine checkon every commit instead. Dependabot
now updatesuv.lockand the files undertools/, and waits a week before proposing a
release.SECURITY.mdsays how a release is built and how to check one. - The documentation site and the playground load nothing from a third party. The
playground took its Pyodide runtime from jsDelivr, in a worker where a script cannot
carry an integrity hash, every page took a stylesheet from Google Fonts, and the home
page took badge images from shields.io. The site now serves Pyodide itself:
docs/hooks.pyfetches the five runtime files when the site is built and refuses any
whose SHA-256 is not the pinned one. The theme uses the system's fonts and the home
page leaves the badges out. A browser test starts the real runtime and fails if any
request leaves the site, and another reads every built page for a script, stylesheet,
image or frame from another host.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.7.0
Fixed
- The IDA, Binary Ninja and Ghidra scripts read Mach-O names without their leading
underscore. Mach-O puts one underscore in front of every symbol, and the tools keep
it, so Nim's_area__mymod_u10came out asmymod._area, JNI's_Java_...was not
read, and Free Pascal, Ada and GCC 2 names were read with the underscore as part of the
name. On a Mach-O file a name is now read without it, except where C++, Swift, Rust, D
or Objective-C reads it as it stands (__Z,_$s,__D, ...), which those schemes do
already and which keeps Apple's C++ rules.demangle_labels.Optionshas a
leading_underscorefield for it, and each script aLEADING_UNDERSCOREsetting that
overrides the file type. Checked in IDA 9.5, Binary Ninja 6.0 and Ghidra 12.2 on a
Mach-O arm64 dylib. - The Binary Ninja plugin leaves alone an address holding several user symbols.
Binary Ninja's DWARF import defines a user symbol for each function the linker
discarded, all at the image base beside__elf_header. With
ONLY_LEFT_MANGLED = Falseon a Rust program the plugin relabelled one of them, which
dropped__elf_header, and Undo did not bring it back. Such an address is now skipped
and counted in the summary line. Found running the plugin live in Binary Ninja 6.0 on
Linux; the IDA script was run live in IDA 9.5, through idalib andidat -S, with
nothing to fix. Both were then run from their windows, the Plugins menu of Binary Ninja
6.0.10905 and File > Script file in IDA 9.5, with Cancel, Undo and Redo behaving as
documented. - An MSVC name holding
_$$_or a/is no longer read as Free Pascal or Go.
?A_$$_B@@3HAread as a Free Pascal routineB@@3HAin a unit?A, where it is
MSVC'sint A_$$_B, and an MSVC string literal with a/in it was claimed by Go and
left as it was. Neither scheme writes a name opening?. - Swift follows upstream's renames (weekly drift report #70). The called-once
function conventions are@once(XO) and@callable(once)(XOo), where they were
@called(exactlyOnce)and@called(atMostOnce), andTwaafter a type metadata
accessor reads asback deployment copy of type metadata accessor for ..., where it
was refused. The Swift reference build moves to swiftlang/swiftmain@4f010677
(2026-11-12), which reproduces the corpora: 531 / 531, 217 / 217, 71 / 71. Rust's
#[rustc_splat]is not followed yet: it is on rustc-demangle'smainonly, and the
released 0.1.28 that the reference builds still prints#[splat]. - MSVC: a conversion operator used as an alias template's argument is declined
cleanly.?f@@YAXV?$A@$$Y?$?BH@@@@V?$A@$$Y?$?BH@@@@@Zfailed on an internal
ValueError, because the placeholder for a conversion operator's name and the mark
for a function type's calling convention shared a delimiter. They are now distinct,
and the name is refused asllvm-undnamerefuses it. - Swift reads a propagated
@differentiablefunction argument. A function
signature specialization parametera(...Tf1na_n) carries the original function
and its JVP and VJP, each as a name and a type, and prints as[Differentiable Function Propagated, Components : [...]]; it was refused. That was the last vector of
the drift report this library did not read.swift-upstream.txtnow holds it and the
threeTwarows: 535 / 535 against the reference build at4f010677. - Playground navigation, presets, and cards share centered page gutters and a bounded
content width. Inner padding, control sizing, and responsive option rows stay aligned
on desktop, narrow screens, and with enlarged text; overflow is contained locally. - Release recovery resumes publishing when a tag and release already exist. Active
or successful publishing runs are preserved; failed runs retry only failed jobs. - Playground theme settings no longer prevent startup when browser storage is blocked.
The theme toggle follows the system preference until the user selects a theme. - Automatic and manual release runs require successful push CI for the commit being tagged.
Added
- Playground batch results preserve line order and blank lines, show individual errors,
cache duplicate symbols, and support copying or downloading the selected output view. - Share links restore batch mode and validate options, with a size limit and explicit
clipboard feedback. Result states distinguish unrecognized, invalid, and unchanged
symbols; keyboard focus and live announcements cover batch controls and results. - A release-preparation command updates package and citation versions, release notes,
and comparison links together, with metadata checks and rollback on failure. - Browser checks for theme persistence, keyboard shortcuts, and stalled-worker recovery.
- IDA Pro, Binary Ninja and Ghidra scripts that label the symbols each tool leaves
mangled, inintegrations/, with a "Disassembler integrations" page. They stay out of
the wheel. benchmarks/compare.pyand a "Comparison with other demanglers" page that measure this
package against LLVM's demangler,cpp-demangle,itanium_demanglerand thec++filt
tools on the same names.- The weekly upstream drift job also reads every checked-in corpus with the newest LLVM,
throughllvm-demangle-fxtipinned by hash, in a job that holds no token
(tools/llvm_oracle.py;tools/upstream_drift.py --source llvm-*,--llvm-version,
--require-llvmand--no-llvm).
Changed
- An MSVC name nested deep enough to reach Python's own recursion limit before
max_depthcan now be read, where 0.6.0 reportedLimitExceeded.max_depthitself is
unchanged.
Performance
- MSVC names read about 7% faster cold, Swift names about 5% and Delphi names about
12%. Go, Nim and Free Pascal are asked about a name before these schemes, and the
$,__and/they look for are in most such names. Nim and Free Pascal names
open with a letter or_, which both now declare as their first characters, and Go's
detectturns away a name opening?or$before looking for a path: no import
path holds either, and Go's own$constants were never claimed. Output over every
corpus is unchanged. - Swift names read about 1.3 times as fast cold: identifiers are split into words only
when a substitution needs them, and the commonest parser and printer steps make about
40% fewer calls. - Template-heavy MSVC names read about 1.5 times as fast cold: each template
instantiation is read once per name, and the control-character scan runs once.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.6.0
Fixed
- Preserve playground input and selected settings while its runtime loads. Scheme
selectors and output controls stay inside their columns on narrow screens and with
enlarged text. AST references reveal collapsed ancestors and support keyboard use.
Added
- MSVC C++20 three-way comparison (
operator<=>) and ARM64e pointer authentication
qualifiers, including their structured AST representation. - Swift inverse conformance to
~Deinitable, with module-name display options respected. - A standalone browser playground with theme switching and keyboard shortcuts.
- Shareable playground links and the loaded library version, runtime retry controls,
and browser regression tests including a real Pyodide smoke test in CI. - Bounded Swift and cross-scheme signature benchmarks with successful-work checks.
Performance
- Run playground parsing in a worker and derive signature and AST data from one parse.
Output view changes reuse the result; AST expansion is lazy and paged with a display
budget while raw JSON remains complete. - Deliver a deterministic, zipimportable source archive instead of a synthetic wheel
and duplicate base64 bundle.
Install with python -m pip install --upgrade demangle.
See the changelog for details.
v0.5.2
Fixed
- Bounds enforcement on hostile and malformed inputs. Large invalid decimal
lengths in Rust legacy symbols (e.g. 60,000 digits) are checked and refused early,
preventing denial-of-service in integer parsing. Swift Unicode identifier lengths
correctly distinguish UTF-8 byte counts from scalar counts, preventing index
out-of-range errors on non-ASCII identifiers. Undersized ELF64 headers and symbol
table entries in Swift binaries are validated against minimum structure sizes. - Objective-C syntax and separator scanning. Selectors require complete colons
(-[Foo take:other]), and category and selector/type splitting matches components
in linear time, eliminating quadratic rescan loops across long underscore-separated
names. - Empty-name argument validation.
demangle("")validates configuration
parameters (language,style,limits) before returning, consistently raising
ValueErroron invalid options rather than silently returning an empty string. - CLI stream filter suppression. The stream filter preserves metadata annotations
(such as Java@Overrideand ELF symbol version markers like@@GLIBC) instead of
rewriting them when filtering text input. - Forced plugin error handling. A language plugin raising an unexpected error
when explicitly forced vialanguage=is chained as aParseErrorrather than
leaking internal operational errors. - AST structure and limit calculations. Normalized
__slots__handling preserves
payload attributes across custom AST node subclasses. Output bounds calculations
track template pack expansions and clone labels againstLimits.max_output.
Performance
- AST serialization is 46% faster. Serialization and dictionary export eliminate
redundant intermediate allocations, reducing serialization time on 5,913 libstdc++
ASTs from 120 ms to 89 ms. - Cold demangling call overhead reduced by 20%. Reduced 712,594 internal Python
calls across the cold benchmark suite by inlining hot reader checks, pre-caching
builtin type nodes inSpellingBuilder, and fast-pathing digit and single-character
token lookups. - Itanium and Rust parsing optimizations. Substitution lookup in the Itanium
parser is lazy, avoiding node cloning on unreferenced paths. Rust v0 and legacy
symbol traversal uses index cursors rather than repeated string slicing, running
up to 77% faster on deep paths. - Bounded CLI stream cache. CLI
--json-linesand stream filtering caches enforce
a 16 MB memory weight bound (_REMEMBERED_BYTES), preventing long-running stream
filters from exhausting memory.
Install with python -m pip install --upgrade demangle.
See the changelog for details.