lkml

lkml is a pure-Python library for parsing and serializing LookML, the modeling language that powers Looker. Its load function turns LookML source into plain Python dictionaries (or JSON), while dump regenerates well-formatted LookML from Python objects, making it straightforward to inspect, transform, lint, or programmatically generate Looker models.

Built around a hand-written lexer, parser, and visitor-based syntax tree, lkml has no external dependencies and has been battle-tested on over 160,000 lines of real-world LookML from public repositories. It parses a typical view or model file in well under ten milliseconds, making it fast enough for CI checks and bulk tooling.

What You Get

• A load() function that parses LookML strings or file objects into Python dictionaries or JSON
• A dump() function that serializes Python objects back into cleanly formatted LookML
• A visitor-based syntax tree for fine-grained inspection and transformation of LookML constructs
• A command-line entry point for converting LookML files to JSON
• Pure Python with zero runtime dependencies and bundled type hints

Common Use Cases

• Linting and validating LookML in continuous integration pipelines
• Programmatically generating or refactoring Looker views and models at scale
• Migrating or transforming existing LookML projects with scripted edits
• Extracting metadata from LookML for documentation or governance tooling

Under The Hood

Architecture - lkml is organized as a classic compiler front-end pipeline in the lkml/ package: lexer.py tokenizes raw LookML into a stream of tokens (tokens.py), parser.py implements a recursive-descent parser that builds a syntax tree (tree.py), and visitors.py plus simple.py walk that tree to emit either plain Python dictionaries or serialized LookML. The public load, dump, and parse functions in __init__.py tie these stages together, and keys.py encodes LookML’s grammar of block, pair, and list keys.

Tech Stack - The library is written in modern, pure Python (3.7+) with no runtime dependencies, keeping installation lightweight and portable. Development tooling includes black, isort, flake8, mypy, bandit, and pytest with coverage, configured through setup.cfg, tox.ini, and pyproject.toml, and CI runs on CircleCI.

Code Quality - Code quality is strong: the tests/ directory holds a full suite spanning the lexer, parser, tree, simple serializer, CLI, and functional round-trip tests, including a test_github.py that exercises the parser against real repositories. The codebase is fully type-hinted (shipping a py.typed marker), statically checked with mypy, and security-scanned with bandit.

API Design - The public API mirrors Python’s own json module — load and dump — which makes it immediately familiar and requires almost no boilerplate to start converting LookML to data and back. The visitor pattern provides an escape hatch for advanced transformations, and bundled type hints give editors and type checkers full visibility into return shapes.