libcst

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

These details have been verified by PyPI

Maintainers

7imbrook amyreese bgw-ig zsolzsol

These details have not been verified by PyPI

Project links

Project description

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

LibCST parses Python 3.0 -> 3.11 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.7+ 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.

Development

You’ll need a recent Rust toolchain for developing.

Then, 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 ufmt to format code. To format changes to be conformant, run the following in the root:

ufmt format && python -m fixit.cli.apply_fix

We use slotscheck to check the correctness of class __slots__. To check that slots are defined properly, run:

python -m slotscheck libcst

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

python -m unittest

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

python -m unittest libcst.tests.test_batched_visitor

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

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 build the libcst.native module and install libcst, run this from the root:

pip uninstall -y libcst
pip install -e .

Type Checking

We use Pyre for type-checking.

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

pyre check

Note: You may need to run the pip install -e . command prior to type checking, see the section above on building.

Generating Documents

To generate documents, do the following in the root:

sphinx-build docs/source/ docs/build/

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

These details have been verified by PyPI

Maintainers

7imbrook amyreese bgw-ig zsolzsol

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

1.5.0

Oct 10, 2024

1.4.0

May 22, 2024

1.3.1

Apr 3, 2024

1.3.0

Apr 3, 2024

1.2.0

Feb 19, 2024

1.1.0

Oct 6, 2023

1.0.1

Jun 7, 2023

1.0.0

May 25, 2023

0.4.10

May 23, 2023

0.4.9

Nov 10, 2022

0.4.8 yanked

Nov 10, 2022

Reason this release was yanked:

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

0.4.7

Jul 12, 2022

0.4.6

Jul 4, 2022

0.4.5

Jun 17, 2022

This version

0.4.4

Jun 13, 2022

0.4.3

May 11, 2022

0.4.2

May 4, 2022

0.4.1

Jan 28, 2022

0.4.0

Jan 12, 2022

0.4.0a1 pre-release

Jan 1, 2022

0.3.23

Nov 23, 2021

0.3.22

Nov 22, 2021

0.3.21

Sep 21, 2021

0.3.20

Aug 10, 2021

0.3.19

May 13, 2021

0.3.18

Mar 30, 2021

0.3.17

Feb 9, 2021

0.3.16

Dec 16, 2020

0.3.15

Dec 1, 2020

0.3.14

Nov 18, 2020

0.3.13

Oct 12, 2020

0.3.12

Oct 1, 2020

0.3.11

Sep 28, 2020

0.3.10

Aug 17, 2020

0.3.9

Aug 7, 2020

0.3.8

Jul 23, 2020

0.3.7

Jun 25, 2020

0.3.6

May 29, 2020

0.3.5

May 13, 2020

0.3.4

Mar 27, 2020

0.3.3

Mar 5, 2020

0.3.2

Feb 26, 2020

0.3.1

Feb 6, 2020

0.3.0

Jan 17, 2020

0.2.7

Jan 7, 2020

0.2.6

Jan 2, 2020

0.2.5

Dec 6, 2019

0.2.4

Nov 14, 2019

0.2.3

Nov 12, 2019

0.2.2

Oct 24, 2019

0.2.1

Oct 14, 2019

0.2.0

Oct 4, 2019

0.1.3

Sep 19, 2019

0.1.2

Aug 29, 2019

0.1.1

Aug 20, 2019

0.1

Aug 7, 2019

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.4.4.tar.gz (738.0 kB view details)

Uploaded Jun 13, 2022 Source

Built Distributions

libcst-0.4.4-cp310-cp310-win_amd64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.10 Windows x86-64

libcst-0.4.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.10 manylinux: glibc 2.17+ x86-64

libcst-0.4.4-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.10 manylinux: glibc 2.17+ ARM64

libcst-0.4.4-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.10 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-0.4.4-cp310-cp310-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.10 macOS 11.0+ ARM64

libcst-0.4.4-cp310-cp310-macosx_10_9_x86_64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.10 macOS 10.9+ x86-64

libcst-0.4.4-cp39-cp39-win_amd64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.9 Windows x86-64

libcst-0.4.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.9 manylinux: glibc 2.17+ x86-64

libcst-0.4.4-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.9 manylinux: glibc 2.17+ ARM64

libcst-0.4.4-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.9 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-0.4.4-cp39-cp39-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.9 macOS 11.0+ ARM64

libcst-0.4.4-cp39-cp39-macosx_10_9_x86_64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.9 macOS 10.9+ x86-64

libcst-0.4.4-cp38-cp38-win_amd64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.8 Windows x86-64

libcst-0.4.4-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.8 manylinux: glibc 2.17+ x86-64

libcst-0.4.4-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.8 manylinux: glibc 2.17+ ARM64

libcst-0.4.4-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.8 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-0.4.4-cp38-cp38-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.8 macOS 11.0+ ARM64

libcst-0.4.4-cp38-cp38-macosx_10_9_x86_64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.8 macOS 10.9+ x86-64

libcst-0.4.4-cp37-cp37m-win_amd64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.7m Windows x86-64

libcst-0.4.4-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.7m manylinux: glibc 2.17+ x86-64

libcst-0.4.4-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.7 MB view details)

Uploaded Jun 13, 2022 CPython 3.7m manylinux: glibc 2.17+ ARM64

libcst-0.4.4-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.7m manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

libcst-0.4.4-cp37-cp37m-macosx_10_9_x86_64.whl (1.8 MB view details)

Uploaded Jun 13, 2022 CPython 3.7m macOS 10.9+ x86-64

File details

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

File metadata

Download URL: libcst-0.4.4.tar.gz
Upload date: Jun 13, 2022
Size: 738.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/4.0.0 CPython/3.10.0

File hashes

Hashes for libcst-0.4.4.tar.gz
Algorithm	Hash digest
SHA256	`0326fd7915bade33e5794a07c46fa1822cb1eabc3af4c2d821127102bdefbe04`
MD5	`228be8e0429bac9a8b943363ab47d562`
BLAKE2b-256	`f472204d4690d99abb0a8b1e700d85a929cbfa4a44c6f81b1d60f2308af39abb`

Algorithm	Hash digest
SHA256	`0a7502575cd8b8aaba215c865c18b49fc4ad4ce0550dadb4091e4b20146a0995`
MD5	`97d68a13175da7d0d7d64f9a9a9686a9`
BLAKE2b-256	`92761c67e4d313d169c45917f85196a27c0208571bbcfc3eed4fe7b9cff73a13`

Algorithm	Hash digest
SHA256	`32f1fe6ca6a280e414975d9416e5af1361a6c1fe0f64c663b4aec19c26e80fde`
MD5	`d7436c7e54eaac8fc8353e08f62ebb3f`
BLAKE2b-256	`5b181ac5cce090baedcca00c4831317ad2de1cd57ee643dce10850c153f44f6b`

Algorithm	Hash digest
SHA256	`ca12c433c656ae8ce25ae054b754c0efa27d53f97692b11a0e46f0f33cade917`
MD5	`27bb41d68b14758c9e48bfb915ee66d0`
BLAKE2b-256	`7b49f5ede292e61ac5e286aee4f04538aea54cc64013d65f4f1498f713b25472`

Algorithm	Hash digest
SHA256	`815103ea4c872de482cbf5ad86f6e7b14973add586eedf221986e57a919be866`
MD5	`fab2c6ed53cc74675ce380ca669be27e`
BLAKE2b-256	`a0919ca842f55bfac2d42ff74487496211c23d44f43f1f6b4184e05a2c206fb1`

Algorithm	Hash digest
SHA256	`41cd5cc5fc66b49e5ec5893d4fec65621b5bbbdc38d9ab2166708de4584eb97a`
MD5	`16fa3c26a1da3f45035226860d6da434`
BLAKE2b-256	`113f17863573e6a7e0c8291c27333c56d92626d37468cfbe58dd12488bba5237`

Algorithm	Hash digest
SHA256	`6d15f7260abe8cc1becf9b43c734cc4e478ba9dbb26611b3c7720f3da4a25320`
MD5	`55c5f14fa299ad19b11b5171ed8f829a`
BLAKE2b-256	`454747a13b036fe155ff937e925ea376ee5ccb0b7fcfa36aeb8af9ba2dcf3f67`

Algorithm	Hash digest
SHA256	`01b42d2748bdc28b9477ae4a39ca8b1689c1dfce8e6a1054086d5c51a61be150`
MD5	`d143fd19e51f591bc3035cddd31c1365`
BLAKE2b-256	`50b782d58da546e3d0fa099ab33ccbf82d9d62e8b5104bfdd06360405c87bd42`

Algorithm	Hash digest
SHA256	`fc5e6d74171a05e0e4aa939802cdea719ac105c534009e5922795e736d9c7d4a`
MD5	`f7b4bae3714d15ba1e36d884201f96a8`
BLAKE2b-256	`31a18849302fdee27ea5af4ca284dbd1e16f636e14d4c6fb46c7cf2a24cb41c4`

Algorithm	Hash digest
SHA256	`76cacc13466010454a3af9f81cd44e85565faf82241cb9a97a3bc6c559fca612`
MD5	`23e71adbafd5467a6b2eb0c707c9096c`
BLAKE2b-256	`141b922fb08d0eb0111057f68a7be8d3253259859da62c9571df00cfe5859838`

Algorithm	Hash digest
SHA256	`33e61c37d17a680692b11b92045e5cb5edc091b16426d18db2331b6c31991538`
MD5	`3e5fdffc6c5e8428eb3e6f7af0de9bb6`
BLAKE2b-256	`eb80dd8fd58d472d35013945f5be8e0e7b1a9fb0da02a00d01016fbeadc35950`

Algorithm	Hash digest
SHA256	`0c78f911763d47759d221ec0a527a7fa42dc3117c6218b1a0c655a1d43135553`
MD5	`b4dc5e79008b5ba7e479b5e75a43521c`
BLAKE2b-256	`1f00fe072fca89ca8e79d6fd31f961944f2ab5e2c1f8b7dd7425d71561bc9a64`

Algorithm	Hash digest
SHA256	`7b39eb51c627dd0dfdb88257baa34084b58c656966c1f16a94b85918551d05fd`
MD5	`bd95e227afc0be57c35986e16fe6f91d`
BLAKE2b-256	`66b7c2f2b5c1e7e48173ae0cb98edee2a811b8f80cd02de9cfb86bedf691d016`

Algorithm	Hash digest
SHA256	`1e1565873cbf13eb883f9264407c1d7b9b4202ae3cfc1fcb95d0fd3755269915`
MD5	`26c53e31d184dc0e86154a04aabf37a9`
BLAKE2b-256	`53f268ae2601b9705e6dbc17761327e9022be384162bcee183f6e05b9343d3ef`

Algorithm	Hash digest
SHA256	`642231fcf88886460e07048ccfaa59064e601b49d55b1384081cfda9544e642c`
MD5	`52f8aed49d207019f786592c71c100a9`
BLAKE2b-256	`d79e69d924210c365e48a648f1bcb43afc66deab08a6e57fc5f6fceef2cda8d2`

Algorithm	Hash digest
SHA256	`14843f619dac08e84255f0bbf82c2b33e3339e0fb4d302dc359a9b9fa3c7a10b`
MD5	`3ead301f06dc3f29e61d8700f8f2c8ad`
BLAKE2b-256	`101e8c1616d7eb8e51ab4fb31e645d4da8dd2734ae2148fad4b825a9e9a927fd`

Algorithm	Hash digest
SHA256	`0bb6146400d5c7be327a6a393462258aa0b71aa112fe8f32613467573c02622c`
MD5	`25342712a8d3464c2f2ee92340f0ffe9`
BLAKE2b-256	`144ab2f832872387b4be856f3ddaf20d7b40ac587ca441e223c690e00ed2da6e`

Algorithm	Hash digest
SHA256	`501f331c6ef0897e23aa2771f3e21f40317985fb5134fc08be67c33e38f29786`
MD5	`293922d95655a33ff79e36a06a397d2e`
BLAKE2b-256	`428bf92527821c7f70dc920791ca937d8178670a02ed30570ef982d45213866d`

Algorithm	Hash digest
SHA256	`d3f5d0cf993e7bc6a705d6f06c661f11dcf56a701634ef1c903823c1bd2864c1`
MD5	`de8899e46a6b0214d43c5496b9b4512a`
BLAKE2b-256	`27281c5755a0632d2643b8961b28497460df8a16594521b4096dea5e1dafa62d`

Algorithm	Hash digest
SHA256	`762df9c4e0918a7a9a54a8b92337239b5459d97832a77789eaa05cd48898daef`
MD5	`9972800570d0cd6aaf4bcad1a391ca9f`
BLAKE2b-256	`ca7564e38843b6b0831e1821c9ae4934bc0f3970f8f31d1dc21ccf96f48c58b6`

Algorithm	Hash digest
SHA256	`0348e7cee1a46b5172a9cd7cb127ec2d8e7c0cfd80f3269ccc9f91c46d7b9542`
MD5	`892c2b7bb4a095129eb20e93cbcb1f6d`
BLAKE2b-256	`86c019a75fe526e093dcc41a7c980507a73f7f7723c99eb3ec37e31f843ffabd`

libcst 0.4.4

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Getting Started

Examining a sample tree

Installation

Further Reading

Development

Building

Type Checking

Generating Documents

Future

License

Privacy Policy and Terms of Use

Acknowledgements

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Algorithm	Hash digest
SHA256	`76fbacca5724afa6235936fad81b61ecd46cd952573ba7b05a3128b84b8c60f1`
MD5	`12b37248104f131d751d4604edccc215`
BLAKE2b-256	`d5bd8b91d1b83b27d6933bf8ed420e4cbd7430a5458975629a5247f4a0ec5c6a`

Algorithm	Hash digest
SHA256	`bd6807c93e5836b1948765d3d717abea8f7a6483a4461ae1824c1dce1ce5fcd7`
MD5	`7612951b7f0285f3183a279eb3e6ec0c`
BLAKE2b-256	`6cdee3b8c566431ab2b43472d5d855436588a01c5e4153bbd35d50ed295e8d4d`

Algorithm	Hash digest
SHA256	`fc47440a45b5d359fd68db95845fa2a99d7b27e30f68ea96c7bb971d9e5e4193`
MD5	`d8c866be2d78cbea7b17d78251903905`
BLAKE2b-256	`5ca0e3ceee937b3fc2bd4536d54ba3a1a3c761f43ac7ae0890dc22ce1acfb9bf`