A concrete syntax tree with AST-like properties for Python 3.7 programs.
Project description
A Concrete Syntax Tree (CST) parser and serializer library for Python
LibCST parses Python 3.7 source code as a CST tree that keeps all formatting details (comments, whitespaces, parentheses, etc). It’s useful for building automated refactoring (codemod) applications and linters.
LibCST creates a compromise between an Abstract Syntax Tree (AST) and a traditional Concrete Syntax Tree (CST). By carefully reorganizing and naming node types and fields, we’ve created a lossless CST that looks and feels like an AST.
1 + 2
BinaryOperation(
left=Integer(
value='1',
lpar=[],
rpar=[],
),
operator=Add(
whitespace_before=SimpleWhitespace(
value=' ',
),
whitespace_after=SimpleWhitespace(
value=' ',
),
),
right=Integer(
value='2',
lpar=[],
rpar=[],
),
lpar=[],
rpar=[],
)
Getting Started
Examining a sample tree
To examine the tree that is parsed from a particular file, do the following:
python -m libcst.tool print <some_py_file.py>
Alternatively you can import LibCST into a Python REPL and use the included parser and pretty printing functions:
>>> import libcst as cst
>>> from libcst.tool import dump
>>> print(dump(cst.parse_expression("(1 + 2)")))
BinaryOperation(
left=Integer(
value='1',
),
operator=Add(),
right=Integer(
value='2',
),
lpar=[
LeftParen(),
],
rpar=[
RightParen(),
],
)
Installation
LibCST requires Python 3.6+ and can be easily installed using most common Python packaging tools. We recommend installing the latest stable release from PyPI with pip:
pip install libcstDevelopment
Start by setting up and activating a virtualenv:
git clone git@github.com:Instagram/LibCST.git libcst
cd libcst
python3 -m venv ../libcst-env/ # just an example, put this wherever you want
source ../libcst-env/bin/activate
pip install --upgrade pip # optional, if you have an old system version of pip
pip install -r requirements.txt -r requirements-dev.txt
# If you're done with the virtualenv, you can leave it by running:
deactivateWe use isort and black to format code. To format changes to be conformant, run the following in the root:
isort -q -y && black libcst/To run all tests, you’ll need to install tox and do the following in the root:
tox -e py37You can also run individual tests by using unittest and specifying a module like this:
python -m unitttest libcst.tests.test_batched_visitorSee the unittest documentation for more examples of how to run tests.
We use Pyre for type-checking. To verify types for the library, do the following in the root:
pyre checkTo generate documents, do the following in the root:
tox -e docsLicense
LibCST is MIT licensed, as found in the LICENSE file.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
