{"id":13460282,"url":"https://github.com/Instagram/LibCST","last_synced_at":"2025-03-24T18:33:29.063Z","repository":{"id":37811872,"uuid":"200896124","full_name":"Instagram/LibCST","owner":"Instagram","description":"A concrete syntax tree parser and serializer library for Python that preserves many aspects of Python's abstract syntax tree","archived":false,"fork":false,"pushed_at":"2024-10-28T02:55:19.000Z","size":3456,"stargazers_count":1544,"open_issues_count":143,"forks_count":191,"subscribers_count":43,"default_branch":"main","last_synced_at":"2024-10-29T15:10:00.999Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://libcst.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Instagram.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-06T17:30:33.000Z","updated_at":"2024-10-28T16:36:16.000Z","dependencies_parsed_at":"2024-01-08T15:31:46.677Z","dependency_job_id":"484d7946-97aa-499a-a0ab-5daa695d64f9","html_url":"https://github.com/Instagram/LibCST","commit_stats":{"total_commits":1046,"total_committers":94,"mean_commits":"11.127659574468085","dds":0.8001912045889101,"last_synced_commit":"7bb00179d9d8a5d66d854e7c1e474ec546a0db86"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Instagram%2FLibCST","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Instagram%2FLibCST/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Instagram%2FLibCST/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Instagram%2FLibCST/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Instagram","download_url":"https://codeload.github.com/Instagram/LibCST/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245328530,"owners_count":20597441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T10:00:38.646Z","updated_at":"2025-03-24T18:33:29.054Z","avatar_url":"https://github.com/Instagram.png","language":"Python","readme":".. image:: docs/source/_static/logo/horizontal.svg\n   :width: 600 px\n   :alt: LibCST\n\nA Concrete Syntax Tree (CST) parser and serializer library for Python\n\n|support-ukraine| |readthedocs-badge| |ci-badge| |pypi-badge| |pypi-download| |notebook-badge| |types-badge|\n\n.. |support-ukraine| image:: https://img.shields.io/badge/Support-Ukraine-FFD500?style=flat\u0026labelColor=005BBB\n   :alt: Support Ukraine - Help Provide Humanitarian Aid to Ukraine.\n   :target: https://opensource.fb.com/support-ukraine\n\n.. |readthedocs-badge| image:: https://readthedocs.org/projects/libcst/badge/?version=latest\u0026style=flat\n   :target: https://libcst.readthedocs.io/en/latest/\n   :alt: Documentation\n\n.. |ci-badge| image:: https://github.com/Instagram/LibCST/actions/workflows/build.yml/badge.svg\n   :target: https://github.com/Instagram/LibCST/actions/workflows/build.yml?query=branch%3Amain\n   :alt: Github Actions\n\n.. |pypi-badge| image:: https://img.shields.io/pypi/v/libcst.svg\n   :target: https://pypi.org/project/libcst\n   :alt: PYPI\n\n.. |pypi-download| image:: https://pepy.tech/badge/libcst/month\n   :target: https://pepy.tech/project/libcst/month\n   :alt: PYPI Download\n\n\n.. |notebook-badge| image:: https://img.shields.io/badge/notebook-run-579ACA.svg?logo=data:image/png;base64,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\n   :target: https://mybinder.org/v2/gh/Instagram/LibCST/main?filepath=docs%2Fsource%2Ftutorial.ipynb\n   :alt: Notebook\n\n.. |types-badge| image:: https://img.shields.io/pypi/types/libcst\n   :target: https://pypi.org/project/libcst\n   :alt: PYPI - Types\n\n.. intro-start\n\nLibCST parses Python 3.0 -\u003e 3.13 source code as a CST tree that keeps\nall formatting details (comments, whitespaces, parentheses, etc). It's useful for\nbuilding automated refactoring (codemod) applications and linters.\n\n.. intro-end\n\n.. why-libcst-intro-start\n\nLibCST creates a compromise between an Abstract Syntax Tree (AST) and a traditional\nConcrete Syntax Tree (CST). By carefully reorganizing and naming node types and\nfields, we've created a lossless CST that looks and feels like an AST.\n\n.. why-libcst-intro-end\n\nYou can learn more about `the value that LibCST provides\n\u003chttps://libcst.readthedocs.io/en/latest/why_libcst.html\u003e`__ and `our\nmotivations for the project\n\u003chttps://libcst.readthedocs.io/en/latest/motivation.html\u003e`__\nin `our documentation \u003chttps://libcst.readthedocs.io/en/latest/index.html\u003e`__.\nTry it out with `notebook examples \u003chttps://mybinder.org/v2/gh/Instagram/LibCST/main?filepath=docs%2Fsource%2Ftutorial.ipynb\u003e`__.\n\nExample expression::\n\n    1 + 2\n\nCST representation:\n\n.. code-block:: python\n\n    BinaryOperation(\n        left=Integer(\n            value='1',\n            lpar=[],\n            rpar=[],\n        ),\n        operator=Add(\n            whitespace_before=SimpleWhitespace(\n                value=' ',\n            ),\n            whitespace_after=SimpleWhitespace(\n                value=' ',\n            ),\n        ),\n        right=Integer(\n            value='2',\n            lpar=[],\n            rpar=[],\n        ),\n        lpar=[],\n        rpar=[],\n    )\n\nGetting Started\n===============\n\nExamining a sample tree\n-----------------------\n\nTo examine the tree that is parsed from a particular file, do the following::\n\n    python -m libcst.tool print \u003csome_py_file.py\u003e\n\nAlternatively, you can import LibCST into a Python REPL and use the included parser\nand pretty printing functions:\n\n\u003e\u003e\u003e import libcst as cst\n\u003e\u003e\u003e from libcst.tool import dump\n\u003e\u003e\u003e print(dump(cst.parse_expression(\"(1 + 2)\")))\nBinaryOperation(\n  left=Integer(\n    value='1',\n  ),\n  operator=Add(),\n  right=Integer(\n    value='2',\n  ),\n  lpar=[\n    LeftParen(),\n  ],\n  rpar=[\n    RightParen(),\n  ],\n)\n\nFor a more detailed usage example, `see our documentation\n\u003chttps://libcst.readthedocs.io/en/latest/tutorial.html\u003e`__.\n\nInstallation\n------------\n\nLibCST requires Python 3.9+ and can be easily installed using most common Python\npackaging tools. We recommend installing the latest stable release from\n`PyPI \u003chttps://pypi.org/project/libcst/\u003e`_ with pip:\n\n.. code-block:: shell\n\n    pip install libcst\n\nFor parsing, LibCST ships with a native extension, so releases are distributed as binary\nwheels as well as the source code. If a binary wheel is not available for your system\n(Linux/Windows x86/x64 and Mac x64/arm are covered), you'll need a recent\n`Rust toolchain \u003chttps://rustup.rs\u003e`_ for installing.\n\nFurther Reading\n---------------\n- `Static Analysis at Scale: An Instagram Story. \u003chttps://instagram-engineering.com/static-analysis-at-scale-an-instagram-story-8f498ab71a0c\u003e`_\n- `Refactoring Python with LibCST. \u003chttps://chairnerd.seatgeek.com/refactoring-python-with-libcst/\u003e`_\n\nDevelopment\n-----------\n\nYou'll need a recent `Rust toolchain \u003chttps://rustup.rs\u003e`_ for developing.\n\nWe recommend using `hatch \u003chttps://hatch.pypa.io/\u003e` for running tests, linters,\netc.\n\nThen, start by setting up and building the project:\n\n.. code-block:: shell\n\n    git clone git@github.com:Instagram/LibCST.git libcst\n    cd libcst\n    hatch env create\n\nTo run the project's test suite, you can:\n\n.. code-block:: shell\n\n    hatch run test\n\nYou can also run individual tests by using unittest and specifying a module like\nthis:\n\n.. code-block:: shell\n\n    hatch run python -m unittest libcst.tests.test_batched_visitor\n\nSee the `unittest documentation \u003chttps://docs.python.org/3/library/unittest.html\u003e`_\nfor more examples of how to run tests.\n\nWe have multiple linters, including copyright checks and\n`slotscheck \u003chttps://slotscheck.rtfd.io\u003e`_ to check the correctness of class\n``__slots__``. To run all of the linters:\n\n.. code-block:: shell\n\n    hatch run lint\n\nWe use `ufmt \u003chttps://ufmt.omnilib.dev/en/stable/\u003e`_ to format code. To format\nchanges to be conformant, run the following in the root:\n\n.. code-block:: shell\n\n    hatch run format\n\nBuilding\n~~~~~~~~\n\nIn order to build LibCST, which includes a native parser module, you\nwill need to have the Rust build tool ``cargo`` on your path. You can\nusually install ``cargo`` using your system package manager, but the\nmost popular way to install cargo is using\n`rustup \u003chttps://rustup.rs/\u003e`_.\n\nTo build just the native parser, do the following from the ``native``\ndirectory:\n\n.. code-block:: shell\n\n    cargo build\n\nTo rebuild the ``libcst.native`` module, from the repo root:\n\n.. code-block:: shell\n\n    hatch env prune \u0026\u0026 hatch env create\n\nType Checking\n~~~~~~~~~~~~~\n\nWe use `Pyre \u003chttps://github.com/facebook/pyre-check\u003e`_ for type-checking.\n\nTo verify types for the library, do the following in the root:\n\n.. code-block:: shell\n\n    hatch run typecheck\n\nGenerating Documents\n~~~~~~~~~~~~~~~~~~~~\n\nTo generate documents, do the following in the root:\n\n.. code-block:: shell\n\n    hatch run docs\n\nFuture\n======\n\n- Advanced full repository facts providers like fully qualified name and call graph.\n\nLicense\n=======\n\nLibCST is `MIT licensed \u003cLICENSE\u003e`_, as found in the LICENSE file.\n\n.. fb-docs-start\n\nPrivacy Policy and Terms of Use\n===============================\n\n- `Privacy Policy \u003chttps://opensource.facebook.com/legal/privacy\u003e`_\n- `Terms of Use \u003chttps://opensource.facebook.com/legal/terms\u003e`_\n\n.. fb-docs-end\n\nAcknowledgements\n================\n\n- Guido van Rossum for creating the parser generator pgen2 (originally used in lib2to3 and forked into parso).\n- David Halter for parso which provides the parser and tokenizer that LibCST sits on top of.\n- Zac Hatfield-Dodds for hypothesis integration which continues to help us find bugs.\n- Zach Hammer improved type annotation for Mypy compatibility.\n","funding_links":[],"categories":["Python","Write code to change code","语言资源库","Libraries and refactoring"],"sub_categories":["python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInstagram%2FLibCST","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FInstagram%2FLibCST","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInstagram%2FLibCST/lists"}