Skip to main content

A concrete syntax tree with AST-like properties for Python 3.5, 3.6 and 3.7 programs.

Project description

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

Future

  • Python 3.8 support, both in running on Python 3.8 and parsing 3.8 code.

  • Addition to Matchers API which allows for operations such as extract/find/replaceall, similar to the RE module.

  • Additional layer providing command-line frontend for executing refactors.

  • More metadata providers from deep static analysis including variable type annotation, etc.

License

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

Acknowledgements

  • Guido van Rossum for creating the parser generator pgen2 (originally used in lib2to3 and forked into parso).

  • David Halter for parso which provides the parser and tokenizer that LibCST sits on top of.

  • Zac Hatfield-Dodds for hypothesis integration which continues to help us find bugs.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

libcst-0.2.2.tar.gz (294.2 kB view details)

Uploaded Source

Built Distribution

libcst-0.2.2-py3-none-any.whl (360.7 kB view details)

Uploaded Python 3

File details

Details for the file libcst-0.2.2.tar.gz.

File metadata

  • Download URL: libcst-0.2.2.tar.gz
  • Upload date:
  • Size: 294.2 kB
  • Tags: Source
  • Uploaded using 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

File hashes

Hashes for libcst-0.2.2.tar.gz
Algorithm Hash digest
SHA256 7f21fb62d52b5d592045cf874d079a4f9d6dc7573ba4aebc0c41678dc95d114e
MD5 321fb0c341a0882d438401c6b7c87a1e
BLAKE2b-256 f17b15e41becdfeeac672f81c1ee598cdc4081a1d6dd22d6ea6d6354b9962c6c

See more details on using hashes here.

Provenance

File details

Details for the file libcst-0.2.2-py3-none-any.whl.

File metadata

  • Download URL: libcst-0.2.2-py3-none-any.whl
  • Upload date:
  • Size: 360.7 kB
  • Tags: Python 3
  • Uploaded using 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

File hashes

Hashes for libcst-0.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 f661d9af161de72c951c1b1a997969e0ef67e920df94ed0004d760067d548ff9
MD5 f17821a33de33e91854dc76e507e8c6d
BLAKE2b-256 8bd9eaf623f038b5a13a1322b5fd6e047e7bcc74605064ef2213d9fb7812bf4f

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page