At the very end of 2019, we finally reached one of our short-term goals: CPython
unittest support which makes finding CPython compatibility errors easier than ever.
This will probably be the major source of contributions for new contributors this year. Here is a simple guideline.
Fix known compatibility bugs
Let’s find an incompatibility issue and fix it.
- Look at the
Lib/testdirectory of the project. There are many
test_prefixed files like
- Try to open one of them. It might look just fine at a glance - but search for
TODO: RUSTPYTHONin the files. There are tons of skipped, marked as an expected failure or commented out tests.
- Alternatively, try looking at the regression test results to find skipped or expected failure tests; some of them have notes for a way to resolve the issue.
- Choose one or two interesting bugs. Remove the test blocker -
- Try to fix them.
Here’s how you run a single unittest file:
$ RUSTPYTHONPATH=Lib cargo run --release Lib/test/test_unicode.py
Add a new unittest file
Because CPython unittest doesn’t work perfectly in RustPython, we are adding test files one by one. Here’s how:
- Download the CPython source code with
git clone https://github.com/python/cpython.git.
- Check out a specific version of CPython. We test against CPython 3.8, so the most recent release of 3.8 (currently 3.8.7) is recommended.
- Copy a file from CPython’s
- Commit the file without editing it. Specify the CPython version you copied from in the commit message.
- Try to edit it until it runs without a crash or failure.
- Commit the changes to make it run. This is the core contribution.
Because RustPython is not perfect, “try to edit it until it runs” doesn’t mean to make it run 100% of the tests successfully. The common methods to make the test file pass are:
- It must at least be able to start to run the tests. Fix the test code or bug until it runs at least a single unit of the test. Typically, unimplemented stdlib or missing files in
unittestcan cause issues. Sometimes RustPython bugs cause issues too.
- If any test can’t be loaded because of a
SyntaxError, you’ll have to comment that part out.
- If any test leads to a crash of RustPython, this code can’t be run. Mark the test with
@unittest.skip('TODO: RUSTPYTHON')to skip it.
- If any test runs but fails, this is an incompatibility issue. Mark the test as an expected failure with
We prefer the reversed order of above methods. The later, the more strict, so it’s easier to detect any progress or regression.
When we temporarily disable parts of
unittest due to RustPython caveats, we mark them to make it easier to find (and re-enable!) them later. Please see the examples below or search for
TODO: RUSTPYTHON in the
Lib/test directory to check actual usage.
# TODO: RUSTPYTHON # # def ... # commented out tests
@unittest.skip("TODO: RUSTPYTHON") def ... # skipped tests
# TODO: RUSTPYTHON @unittest.expectedFailure def ... # failed tests
For a general introduction to RustPython development, please visit the RustPython development guide