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
Changerinstance. - Register converter functions with the
@<changer object>.converterdecorator. Each function takes aCSTnode 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:coordinatewith fieldsstart_line: int,start_column: int,end_line: int,end_column: intand some others — identifies the current syntactic location in the code;source— the complete original source passed toChanger;node_range— the node’sWhitespaceInclusivePositionProviderrange, including whitespace owned by that node;start_offset: intandend_offset: int— the lazily computed inclusive start and exclusive end indices of that range in Python characters;code_beforeandcode_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#, orNoneif 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.