A maintained, close-to-spec implementation of ECMA-426: Source Maps in pure Python. Supports both decoding and encoding, including index maps with sections.
Source Maps are a way to map positions in minified/transformed JavaScript code back to the original source code, which is essential for debugging and error reporting.
- Up to date — tracks the current ECMA-426 spec.
- Close to spec — code is organized around spec sections, making it easy to verify correctness.
- Pure Python — no C extensions, no dependencies.
- Both directions — decode JSON maps into Python structures, encode tokens back to valid sourcemaps.
- Sections supported — index maps (
sections) are handled according to the specification.
pip install ecma426
Top-level decode:
import json
import ecma426
with open("app.min.js.map") as f:
data = json.load(f)
smap = ecma426.loads(data)
print(smap.tokens[0])
Low-level encode / decode:
from ecma426 import codec
from ecma426.model import Mapping
tokens = [
Mapping(generated_line=0, generated_column=0, source="app.js", original_line=0, original_column=0, name=None)
]
# Encode into a sourcemap dict
smap = codec.encode(tokens)
# Decode back into a MappingIndex
decoded = codec.decode(smap)
Lookups:
# Strict lookup (exact match only, KeyError if absent)
mapping = smap[(10, 42)]
# Nearest-left lookup (will give you "something" at least for slight mismatches)
# returns the mapping at or immediately before (line, column) on the same line
mapping = smap.lookup_left(line=10, column=42)
Mapping back into original text:
source_text = smap.raw["sourcesContent"][0].splitlines()
mapping = smap.lookup_left(line=10, column=42)
line = source_text[mapping.original_line]
print(line)
print(" " * mapping.original_column + "^ here")
We are closely watching the spec for any proposed changes.
Support for DebugIds (pass-through) is already included.
- python-sourcemap -- only supports decoding, no sections.
- evmar's python-sourcemap -- unmaintained (13 years old).
- Sentry's symbolic -- much more than sourcemaps; Rust dependency.
3-clause BSD, see LICENSE.