Package: libcst
A Concrete Syntax Tree (CST) parser and serializer library for PythonLibCST parses Python 3.0 -> 3.12 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 aboutthe value that LibCST providesandour
motivations for the projectinour documentation.
Try it out withnotebook examples.Example expression:1 + 2CST representation: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 StartedExamining a sample treeTo 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.InstallationLibCST requires Python 3.9+ and can be easily installed using most common Python
packaging tools. We recommend installing the latest stable release fromPyPIwith pip:pipinstalllibcstFor parsing, LibCST ships with a native extension, so releases are distributed as binary
wheels as well as the source code. If a binary wheel is not available for your system
(Linux/Windows x86/x64 and Mac x64/arm are covered), you’ll need a recentRust toolchainfor installing.Further ReadingStatic Analysis at Scale: An Instagram Story.Refactoring Python with LibCST.DevelopmentYou’ll need a recentRust toolchainfor developing.We recommend usinghatch <https://hatch.pypa.io/>for running tests, linters,
etc.Then, start by setting up and building the project:gitclonegit@github.com:Instagram/LibCST.gitlibcstcdlibcsthatchenvcreateTo run the project’s test suite, you can:hatchruntestYou can also run individual tests by using unittest and specifying a module like
this:hatchrunpython-munittestlibcst.tests.test_batched_visitorSee theunittest documentationfor more examples of how to run tests.We have multiple linters, including copyright checks andslotscheckto check the correctness of class__slots__. To run all of the linters:hatchrunlintWe useufmtto format code. To format
changes to be conformant, run the following in the root:hatchrunformatBuildingIn order to build LibCST, which includes a native parser module, you
will need to have the Rust build toolcargoon your path. You can
usually installcargousing your system package manager, but the
most popular way to install cargo is usingrustup.To build just the native parser, do the following from thenativedirectory:cargobuildTo rebuild thelibcst.nativemodule, from the repo root:hatchenvprune&&hatchenvcreateType CheckingWe usePyrefor type-checking.To verify types for the library, do the following in the root:hatchruntypecheckGenerating DocumentsTo generate documents, do the following in the root:hatchrundocsFutureAdvanced full repository facts providers like fully qualified name and call graph.LicenseLibCST isMIT licensed, as found in the LICENSE file.Privacy Policy and Terms of UsePrivacy PolicyTerms of UseAcknowledgementsGuido 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.Zach Hammer improved type annotation for Mypy compatibility.