ruff/crates/ruff_python_parser/CONTRIBUTING.md

Contributing to the Python Parser

Development

Inline tests

The parser crate supports writing inline tests. These are tests that are written in the source code itself, and are extracted to a separate file and run with the test suite. They are written in the form of comments with a specific format. There are two forms of inline tests:

Test that the parser successfully parses the input with no syntax errors. They're written in the following format:

// test_ok this_is_the_test_name
// def foo():
//     pass
println!("some rust code");

Test that the parser fails to parse the input with a syntax error. They're written in the following format:

// test_err this_is_the_test_name
// [1, 2
println!("some rust code");

Note that the difference between the two is the test_ok and test_err keywords. The comment block must be independent of any other comment blocks. For example, the following is not extracted:

// Some random comment
//
// test_ok this_is_the_test_name
// def foo():
//     pass
println!("some rust code");

To generate the corresponding Python files for the inline tests, run the following command:

cargo test --package ruff_python_parser --test generate_inline_tests

Then, run the Parser test suite with the following command:

cargo test --package ruff_python_parser

Python-based fuzzer

The Ruff project includes a Python-based fuzzer that can be used to run the parser on randomly generated (but syntactically valid) Python source code files.

To run the fuzzer, execute the following command (requires uv to be installed):

uvx --from ./python/py-fuzzer fuzz

Refer to the py-fuzzer script for more information or use the --help flag to see the available options.

CI

The fuzzer is run as part of the CI pipeline. The purpose of running the fuzzer in the CI is to catch any regresssions introduced by any new changes to the parser. This is why the fuzzer is run on the same set of seeds on every run.

Benchmarks

The ruff_benchmark crate can benchmark both the lexer and the parser.

To run the lexer benchmarks, use the following command:

cargo bench --package ruff_benchmark --bench lexer

And to run the parser benchmarks, use the following command:

cargo bench --package ruff_benchmark --bench parser

Refer to the Benchmarking and Profiling section in the contributing guide for more information.