Skip to main content
ⓘ

Downloads Downloads Coverage Status Lines of code Hits-of-Code Test-Package Python versions PyPI version Checked with mypy Ruff DeepWiki

logo

Many source code tools, such as linters and formatters, work with CST, a tree-structured representation of source code (like AST, but it also retains nodes such as whitespace and comments). This library is a wrapper around these trees, designed for convenient iterative traversal and node replacement.

It is built on top of libcst.

Table of Contents

Installation

You can install cstvis with pip:

pip install cstvis

You can also use instld to quickly try this package and others without installing them.

Changing nodes

The basic workflow is very simple:

  • Create a Changer instance.
  • Register converter functions with the @<changer object>.converter decorator. Each function takes a CST node as its first argument and returns a replacement node.
  • If needed, register filters to prevent changes to certain nodes.
  • Iterate over individual changes and apply them as needed.

Let me show you a simple example:

from libcst import Subtract, Add
from cstvis import Changer
from pathlib import Path

# Content of the file:
# a = 4 + 5
# b = 15 - a
# c = b + a # kek
changer = Changer(Path('tests/some_code/simple_sum.py').read_text())

@changer.converter
def change_add(node: Add):
    return Subtract(
        whitespace_before=node.whitespace_before,
        whitespace_after=node.whitespace_after,
    )

for x in changer.iterate_coordinates():
    print(x)
    print(changer.apply_coordinate(x))

#> Coordinate(file=None, class_name='Add', start_line=1, start_column=6, end_line=1, end_column=7, converter_id='__main__:change_add:11')
#> a = 4 - 5
#> b = 15 - a
#> c = b + a # kek
#>
#> Coordinate(file=None, class_name='Add', start_line=3, start_column=6, end_line=3, end_column=7, converter_id='__main__:change_add:11')
#> a = 4 + 5
#> b = 15 - a
#> c = b - a # kek

As you can see in the example, the converter function takes an argument with a type hint. You don’t need to write type-checking if statements because the system determines which node types to convert based on this hint. You can omit the annotation entirely, specify Any, or specify libcst.CSTNode, in which case the converter will be applied to all nodes. If you specify a more specific type, such as libcst.Add, the converter will be applied only to those nodes. You can also specify multiple node types using the | syntax or Union. Finally, several shortcuts are supported: str -> libcst.SimpleString, int -> libcst.Integer, and float -> libcst.Float.

The key part of this example is the last two lines, where we iterate over the coordinates. What does that mean? This library performs each code change in two stages: identifying the coordinates of the change and then applying it. This separation makes it possible to distribute the work across multiple threads or even multiple machines. However, this design also has limitations. If you apply one coordinate change, the resulting code will differ from the original and the remaining coordinates will no longer be valid. You can only apply one change at a time.

Filters

A filter is a predicate that controls which coordinates iterate_coordinates() yields: a coordinate is yielded only if every filter applicable to it returns a truthy value. Filtering happens during a single up-front discovery pass; no coordinate is yielded until that pass finishes, and apply_coordinate() never re-evaluates filters. A node-type filter can suppress every coordinate for a node; a converter-bound filter can suppress only that converter’s coordinate for that node.

Node-type filters

A node-type filter is registered with @<changer object>.filter or, when using a collector, with @<collector object>.filter. As with converters, its first-argument annotation determines which node types it is evaluated for. Specifying libcst.CSTNode or Any, or omitting the annotation, makes the filter apply to every node matched by a converter.

Node-type filters are evaluated before converter-bound filters. Each node-type filter runs at most once per node matched by a converter during a single iterate_coordinates() pass. If any node-type filter returns a falsy value, all coordinates for that node are suppressed; the remaining node-type filters and all converter-bound filters are skipped, and traversal continues into the node’s children.

Continuing the previous example, here is a node-type filter (part of the code is omitted):

count_adds = 0

@changer.filter
def only_first(node: Add) -> bool:
    global count_adds
    
    count_adds += 1
    
    return True if count_adds <= 1 else False

for x in changer.iterate_coordinates():
    print(x)
    print(changer.apply_coordinate(x))

#> Coordinate(file=None, class_name='Add', start_line=1, start_column=6, end_line=1, end_column=7, converter_id='__main__:change_add:11')
#> a = 4 - 5
#> b = 15 - a
#> c = b + a # kek

As you can see, the iteration now yields only the first possible change; the rest are filtered out automatically because the filter returns False for them.

Converter-bound filters

The @<changer object>.converter and @<collector object>.converter decorators return a Converter. Attach a bound filter to that object with @<converter object>.filter. A converter’s bound filters run in registration order. The first falsy result stops evaluating the rest of that converter’s filters and suppresses only that converter’s coordinate for the node. Calling a Converter directly bypasses coordinate discovery and therefore all filters.

As with a node-type filter, a bound filter may take the node alone or the node and a Context. Unlike a node-type filter, however, a bound filter’s first-argument annotation is ignored: its converter’s annotation determines which nodes the filter receives, so it must handle every node type the converter matches.

The following example has two converters for Add and attaches a bound filter to only one of them:

from libcst import Add, Multiply, Subtract
from cstvis import Changer

changer = Changer('1 + 2 + 3')

@changer.converter
def change_add(node: Add):
    return Subtract(
        whitespace_before=node.whitespace_before,
        whitespace_after=node.whitespace_after,
    )

@changer.converter
def change_add_to_multiply(node: Add):
    return Multiply(
        whitespace_before=node.whitespace_before,
        whitespace_after=node.whitespace_after,
    )

bound_calls = 0

@change_add.filter
def only_first_bound(node: Add) -> bool:
    global bound_calls

    bound_calls += 1

    return bound_calls <= 1

for coordinate in changer.iterate_coordinates():
    print(changer.apply_coordinate(coordinate))

#> 1 - 2 + 3
#> 1 * 2 + 3
#> 1 + 2 * 3

only_first_bound lets change_add produce a coordinate only for the first Add operator visited — the one inside 1 + 2. Both converters produce a coordinate for it; for the second Add operator, only change_add_to_multiply produces one.

Separating registration from execution

In some cases, you may want to separate converter and filter registration from execution. For this purpose, a special object type — Collector — can help you. A collector object has the same decorators as Changer objects, and it can be used in the same way. When creating a Changer, you can pass a Collector instance:

from cstvis import Collector, Context

collector = Collector()

@collector.converter
def change_add(node: Add):
    return Subtract(
        whitespace_before=node.whitespace_before,
        whitespace_after=node.whitespace_after,
    )

# Bound to change_add, so it affects only that converter's coordinates.
@change_add.filter
def skip_commented(node: Add, context: Context) -> bool:
    return context.comment is None

changer = Changer(Path('tests/some_code/simple_sum.py').read_text(), collector=collector)

If you need to combine collectors defined in different parts of your program, you can do so using the + operator:

collector_1 = Collector()
collector_2 = Collector()

...

collector_3 = collector_1 + collector_2

↑ Combining collectors preserves all their filters and converters; a bound filter stays with its converter and does not become a node-type filter.

Context

By default, each converter or filter takes a single argument: the node to which it is applied. However, you can also specify a second argument: the context. The system analyzes your function signatures, detects that a function expects a second argument, and passes the context to it:

from cstvis import Context

@changer.converter
def change_add(node: Add, context: Context):  # <- The function takes a second argument.
    return Subtract(
        whitespace_before=node.whitespace_before,
        whitespace_after=node.whitespace_after,
    )

The frozen Context dataclass provides the following attributes and method:

  • position: SourcePosition — the node’s position in the original source. It provides:
    • coordinate with fields start_line: int, start_column: int, end_line: int, end_column: int and some others — identifies the current syntactic location in the code;
    • source — the complete original source passed to Changer;
    • node_range — the node’s WhitespaceInclusivePositionProvider range, including whitespace owned by that node;
    • start_offset: int and end_offset: int — the lazily computed inclusive start and exclusive end indices of that range in Python characters;
    • code_before and code_after — the lazily computed source text before and after that range.
  • comment — the comment on the node’s first line, if there is one, without the leading #, or None if there is no comment.
  • get_metacodes(key: Union[str, List[str]]) -> List[ParsedComment] — a method that returns a list of parsed comments in metacode format associated with the current line of code.

You can also pass an arbitrary dictionary to any decorator in this library; a copy of that dictionary will be passed as a meta attribute of the context object:

from libcst import SimpleString
from cstvis import Changer, Context
from pathlib import Path

# Content of the file:
# a = "old string"

changer = Changer(Path('tests/some_code/simple_string.py').read_text())

@changer.converter(meta={'new_value': '"new string"'})
def change_string(node: SimpleString, context: Context):
    return SimpleString(value=context.meta['new_value'])

for x in changer.iterate_coordinates():
    print(x)
    print(changer.apply_coordinate(x))

#> Coordinate(file=None, class_name='SimpleString', start_line=1, start_column=4, end_line=1, end_column=16, converter_id='__main__:change_string:10')
#> a = "new string"

You can also pass a meta dictionary to the Collector class constructor. If you do this but also pass another dictionary to the @<collector object>.converter or @<collector object>.filter decorators, the dictionaries will be merged before being passed to the wrapped functions (if keys match, the values passed to the decorator will take precedence):

collector = Collector(meta={'key 1': 'value 1'})

@collector.converter(meta={'key 2': 'value 2'})
def change_add(node: Add, context: Context):
    print(context.meta)
    #> {'key 1': 'value 1', 'key 2': 'value 2'}
    ...

Metadata

Release files for cstvis 0.0.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cstvis 0.0.12
File Size Uploaded Provenance Actions
cstvis-0.0.12.tar.gz 59.1 kB With provenance Details for cstvis-0.0.12.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cstvis 0.0.12
File Interpreter ABI Platform Actions
cstvis-0.0.12-py3-none-any.whl Python 3 none any Details for cstvis-0.0.12-py3-none-any.whl

Total release size: 79.2 kB

Release files / cstvis-0.0.12.tar.gz

Download URL cstvis-0.0.12.tar.gz
Size 59.1 kB
Tags Source
SHA-256 checksum
How to use checksums
f580405cb879743113cffb3cd8ada5ea2411e4380601019b9f324abc6747d5b5
BLAKE2b-256 checksum
How to use checksums
dc1688af79816d75f955ebd864dbdc83819ea351dfb80b41cc6348ac25754780
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / cstvis-0.0.12-py3-none-any.whl

Download URL cstvis-0.0.12-py3-none-any.whl
Size 20.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
48d310337271fd2b012a5ccd859acb60a310e00716db9a6ccc19bef5a7d5247d
BLAKE2b-256 checksum
How to use checksums
fe1b15508c314968e5ebae4a853ea5bd45f0079bfcbfa2f049c07e7ff0bb8067
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for cstvis 0.0.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cstvis-0.0.12.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page