ruff/crates/ruff_python_parser/CONTRIBUTING.md
Alex Waygood f1b2e85339
Some checks are pending
CI / Determine changes (push) Waiting to run
CI / cargo fmt (push) Waiting to run
CI / cargo clippy (push) Blocked by required conditions
CI / cargo test (linux) (push) Blocked by required conditions
CI / cargo test (linux, release) (push) Blocked by required conditions
CI / cargo test (windows) (push) Blocked by required conditions
CI / cargo test (wasm) (push) Blocked by required conditions
CI / cargo build (release) (push) Waiting to run
CI / cargo build (msrv) (push) Blocked by required conditions
CI / cargo fuzz build (push) Blocked by required conditions
CI / fuzz parser (push) Blocked by required conditions
CI / test scripts (push) Blocked by required conditions
CI / ecosystem (push) Blocked by required conditions
CI / cargo shear (push) Blocked by required conditions
CI / python package (push) Waiting to run
CI / pre-commit (push) Waiting to run
CI / mkdocs (push) Waiting to run
CI / formatter instabilities and black similarity (push) Blocked by required conditions
CI / test ruff-lsp (push) Blocked by required conditions
CI / benchmarks (push) Blocked by required conditions
py-fuzzer: recommend using uvx rather than uv run to run the fuzzer (#14645)
2024-11-27 22:19:52 +00:00

95 lines
2.6 KiB
Markdown

# 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:
```rs
// 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:
```rs
// 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:
```rs
// 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:
```sh
cargo test --package ruff_python_parser --test generate_inline_tests
```
Then, run the Parser test suite with the following command:
```sh
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`](https://github.com/astral-sh/uv) to be installed):
```sh
uvx --from ./python/py-fuzzer fuzz
```
Refer to the [py-fuzzer](https://github.com/astral-sh/ruff/blob/main/python/py-fuzzer/fuzz.py)
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:
```sh
cargo bench --package ruff_benchmark --bench lexer
```
And to run the parser benchmarks, use the following command:
```sh
cargo bench --package ruff_benchmark --bench parser
```
Refer to the [Benchmarking and
Profiling](https://docs.astral.sh/ruff/contributing/#benchmark-driven-development) section in the
contributing guide for more information.