Skip to content
A concrete syntax tree parser and serializer library for Python that preserves many aspects of Python's abstract syntax tree
Python
Branch: master
Clone or download
DragonMinded Add support for Python 3.5
There were only grammar changes between 3.5 and 3.6, which are pretty trivial to put in. So, do that trivial bit and get us completely covered for production Python 3 versions. This could use better testing, but it is good enough as-is and we can address issues with GitHub's issue tracker.
Latest commit dcf2764 Sep 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci [CI] move test coverage job as a separate job (#48) Aug 27, 2019
.github add initial PULL_REQUEST_TEMPLATE.md Jul 23, 2019
docs/source Fix some typos and add watchman config for pyre incremental check Sep 16, 2019
libcst Add support for Python 3.5 Sep 16, 2019
stubs Remove parso as a dependency. Sep 12, 2019
.editorconfig Add config files to make tools easier to use Jul 23, 2019
.flake8 Remove Instagram-specific bits from flake8 config Jul 23, 2019
.gitattributes Add the logo to the docs/source/_static/ directory Aug 5, 2019
.gitignore Fuzz with Hypothesmith Aug 22, 2019
.pyre_configuration add pyre CI job Jul 23, 2019
.readthedocs.yml [readthedoc] install libcst Aug 7, 2019
.watchmanconfig Fix some typos and add watchman config for pyre incremental check Sep 16, 2019
CHANGELOG.md Bump version number to 0.1.2. Aug 29, 2019
CODE_OF_CONDUCT.md add Code Of Conduct file Jul 23, 2019
CONTRIBUTING.md add test command and rephrase coding style. Jul 23, 2019
LICENSE first commit May 29, 2019
MANIFEST.in support mypy using py.typed Sep 16, 2019
README.rst Add support for Python 3.5 Sep 16, 2019
codecov.yml [CI] move test coverage job as a separate job (#48) Aug 27, 2019
pyproject.toml Add config files to make tools easier to use Jul 23, 2019
requirements-dev.txt Bump hypothesis/hypothesmith version now that Zac-HD/hypothesmith#3 i… Sep 10, 2019
requirements.txt Remove parso as a dependency. Sep 12, 2019
setup.py support mypy using py.typed Sep 16, 2019
tox.ini Add a tox environment for running codegen. Aug 28, 2019

README.rst

LibCST

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

Documentation CircleCI CodeCov PYPI Notebook

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.

You can’t perform that action at this time.