A concrete syntax tree with AST-like properties for Python 3.0 through 3.12 programs.

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for 7imbrook from gravatar.com 7imbrook Avatar for amyreese from gravatar.com amyreese Avatar for bgw-ig from gravatar.com bgw-ig Avatar for zsolzsol from gravatar.com zsolzsol

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (All contributions towards LibCST are MIT licensed. Some Python files have been derived from the sta...)
  • Requires: Python >=3.9
Classifiers

Project description

LibCST

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

Support Ukraine - Help Provide Humanitarian Aid to Ukraine. Documentation Github Actions CodeCov PYPI PYPI Download Notebook

LibCST 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 about the value that LibCST provides and our motivations for the project in our documentation. Try it out with notebook examples.

Example expression:

1 + 2

CST 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 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.9+ 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

For 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 recent Rust toolchain for installing.

Further Reading

Development

You’ll need a recent Rust toolchain for developing.

We recommend using hatch <https://hatch.pypa.io/> for running tests, linters, etc.

Then, start by setting up and building the project:

git clone git@github.com:Instagram/LibCST.git libcst
cd libcst
hatch env create

To run the project’s test suite, you can:

hatch run test

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

hatch run python -m unittest libcst.tests.test_batched_visitor

See the unittest documentation for more examples of how to run tests.

We have multiple linters, including copyright checks and slotscheck to check the correctness of class __slots__. To run all of the linters:

hatch run lint

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

hatch run format

Building

In order to build LibCST, which includes a native parser module, you will need to have the Rust build tool cargo on your path. You can usually install cargo using your system package manager, but the most popular way to install cargo is using rustup.

To build just the native parser, do the following from the native directory:

cargo build

To rebuild the libcst.native module, from the repo root:

hatch env prune && hatch env create

Type Checking

We use Pyre for type-checking.

To verify types for the library, do the following in the root:

hatch run typecheck

Generating Documents

To generate documents, do the following in the root:

hatch run docs

Future

  • Advanced full repository facts providers like fully qualified name and call graph.

License

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

Privacy Policy and Terms of Use

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.

  • Zach Hammer improved type annotation for Mypy compatibility.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for 7imbrook from gravatar.com 7imbrook Avatar for amyreese from gravatar.com amyreese Avatar for bgw-ig from gravatar.com bgw-ig Avatar for zsolzsol from gravatar.com zsolzsol

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (All contributions towards LibCST are MIT licensed. Some Python files have been derived from the sta...)
  • Requires: Python >=3.9
Classifiers

Release history Release notifications | RSS feed

1.5.0

1.4.0

1.3.1

This version

1.3.0

1.2.0

1.1.0

1.0.1

1.0.0

0.4.10

0.4.9

0.4.8 yanked

Reason this release was yanked:

broken M1 wheel: https://github.com/Instagram/LibCST/issues/817

0.4.7

0.4.6

0.4.5

0.4.4

0.4.3

0.4.2

0.4.1

0.4.0

0.4.0a1 pre-release

0.3.23

0.3.22

0.3.21

0.3.20

0.3.19

0.3.18

0.3.17

0.3.16

0.3.15

0.3.14

0.3.13

0.3.12

0.3.11

0.3.10

0.3.9

0.3.8

0.3.7

0.3.6

0.3.5

0.3.4

0.3.3

0.3.2

0.3.1

0.3.0

0.2.7

0.2.6

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2.0

0.1.3

0.1.2

0.1.1

0.1

Download files

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

Source Distribution

libcst-1.3.0.tar.gz (765.0 kB view hashes)

Uploaded Source

Built Distributions

libcst-1.3.0-cp312-cp312-win_amd64.whl (2.0 MB view hashes)

Uploaded CPython 3.12 Windows x86-64

libcst-1.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view hashes)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

libcst-1.3.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view hashes)

Uploaded CPython 3.12 manylinux: glibc 2.17+ ARM64

libcst-1.3.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.3 MB view hashes)

Uploaded CPython 3.12 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-1.3.0-cp312-cp312-macosx_11_0_arm64.whl (2.0 MB view hashes)

Uploaded CPython 3.12 macOS 11.0+ ARM64

libcst-1.3.0-cp312-cp312-macosx_10_9_x86_64.whl (2.1 MB view hashes)

Uploaded CPython 3.12 macOS 10.9+ x86-64

libcst-1.3.0-cp311-cp311-win_amd64.whl (2.0 MB view hashes)

Uploaded CPython 3.11 Windows x86-64

libcst-1.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view hashes)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

libcst-1.3.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view hashes)

Uploaded CPython 3.11 manylinux: glibc 2.17+ ARM64

libcst-1.3.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.3 MB view hashes)

Uploaded CPython 3.11 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-1.3.0-cp311-cp311-macosx_11_0_arm64.whl (2.0 MB view hashes)

Uploaded CPython 3.11 macOS 11.0+ ARM64

libcst-1.3.0-cp311-cp311-macosx_10_9_x86_64.whl (2.1 MB view hashes)

Uploaded CPython 3.11 macOS 10.9+ x86-64

libcst-1.3.0-cp310-cp310-win_amd64.whl (2.0 MB view hashes)

Uploaded CPython 3.10 Windows x86-64

libcst-1.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

libcst-1.3.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.17+ ARM64

libcst-1.3.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.3 MB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-1.3.0-cp310-cp310-macosx_11_0_arm64.whl (2.0 MB view hashes)

Uploaded CPython 3.10 macOS 11.0+ ARM64

libcst-1.3.0-cp310-cp310-macosx_10_9_x86_64.whl (2.1 MB view hashes)

Uploaded CPython 3.10 macOS 10.9+ x86-64

libcst-1.3.0-cp39-cp39-win_amd64.whl (2.0 MB view hashes)

Uploaded CPython 3.9 Windows x86-64

libcst-1.3.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64

libcst-1.3.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.17+ ARM64

libcst-1.3.0-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.3 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-1.3.0-cp39-cp39-macosx_11_0_arm64.whl (2.0 MB view hashes)

Uploaded CPython 3.9 macOS 11.0+ ARM64

libcst-1.3.0-cp39-cp39-macosx_10_9_x86_64.whl (2.1 MB view hashes)

Uploaded CPython 3.9 macOS 10.9+ x86-64

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