libcst

A Concrete Syntax Tree (CST) parser and serializer library for Python

LibCST parses Python 3.5, 3.6 or 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.

You can learn more about the value that LibCST provides and our motivations for the project in our documentation. Try it out with notebook examples.

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(),
  ],
)

For a more detailed usage example, see our documentation.

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 libcst

Development

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:
deactivate

We use isort and black to format code. To format changes to be conformant, run the following in the root:

tox -e autofix

To run all tests, you’ll need to install tox and do the following in the root:

tox -e py37

You can also run individual tests by using unittest and specifying a module like this:

python -m unitttest libcst.tests.test_batched_visitor

See 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 check

To generate documents, do the following in the root:

tox -e docs

License

LibCST is MIT licensed, as found in the LICENSE file.

Release files for libcst 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for libcst 0.1.3
File	Size	Uploaded
libcst-0.1.3.tar.gz	219.2 kB	Sep 19, 2019	Details

Built distribution (wheel)

Table of built distributions (wheels) for libcst 0.1.3
File	Interpreter	ABI	Platform	Reset
libcst-0.1.3-py3-none-any.whl 277.7 kB Sep 19, 2019	Python 3	none	any	Details

Total release size: 496.9 kB

Release files / libcst-0.1.3.tar.gz

Download URL	libcst-0.1.3.tar.gz
Size	219.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`0708e39c47f2818f1cc772af28ab74a3f0f0048838c98ecd39b63f36f13c3694`
BLAKE2b-256 checksum How to use checksums	`b6934b61b66ba1e21eb1c5fff6f9e482b050c4c6c971546c9154f86365d14f2b`
Upload date	Sep 19, 2019
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.7.3`

Release files / libcst-0.1.3-py3-none-any.whl

Download URL	libcst-0.1.3-py3-none-any.whl
Size	277.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b3ae681f9f866b308480918d87f8a86f0a726a99dd5432b328a8b8322341d2e7`
BLAKE2b-256 checksum How to use checksums	`8790d1860958aa868ba7c0f581ff51552c0c049591fc806600642c00f5677406`
Upload date	Sep 19, 2019
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.7.3`