You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
contributor_excerpt: ""# TODO: write something here, goes right under "Contributors" heading
32
-
blog-intro: Create an issue if you read something wrong. Edit posts or create new ones via PR on <a target="_blank" href="https://github.com/RustPython/rustpython.github.io">github.com/RustPython/rustpython.github.io</a>
32
+
blog-intro: Create an issue if you see something wrong. Edit posts or create new ones via PR on <a target="_blank" href="https://github.com/RustPython/rustpython.github.io">github.com/RustPython/rustpython.github.io</a>
Copy file name to clipboardexpand all lines: _posts/2020-03-12-thing-explainer-parser.markdown
+13-13
Original file line number
Diff line number
Diff line change
@@ -6,21 +6,21 @@ date: 2020-04-02 11:34:01 -0400
6
6
7
7
This post goes over the RustPython parser. You can see the source code at [RustPython/parser/](https://github.com/RustPython/RustPython/tree/master/parser).
8
8
9
-
When you write code in python and run it, an interpreter, such as the RustPython interpreter, acts as the translator between you and your machine.
9
+
When you write code in Python and run it, an interpreter, such as the RustPython interpreter, acts as the translator between you and your machine.
10
10
11
-
The interpreter has the job of turning your human code into byte code that a python virtual machine can run. Bytecode is an intermediate code between source code and machine code. This makes it portable across multiple hardware and operating systems. Bytecode "works" as long as you implement a virtual machine(vm) that can run it. There is a performance penalty for this flexibility. RustPython has a vm under [RustPython/vm/](https://github.com/RustPython/RustPython/tree/master/vm). Other posts, will go into the details of that vm but now let's figure out how to turn code into bytecode.
11
+
The interpreter has the job of turning your human code into bytecode that a Python virtual machine can run. Bytecode is an intermediate code between source code and machine code. This makes it portable across multiple hardware and operating systems. Bytecode "works" as long as you implement a virtual machine(vm) that can run it. There is a performance penalty for this flexibility. RustPython has a vm under [RustPython/vm/](https://github.com/RustPython/RustPython/tree/master/vm). Other posts will go into the details of that vm but now let's figure out how to turn code into bytecode.
12
12
13
13
14
-
## How does bytecode look like
14
+
## What bytecode looks like
15
15
16
-
Seeing is believing. To see what bytecode looks like, you can use a Python module called [`dis`](https://docs.python.org/3/library/dis.html). dis stands for disassembler. You can write source code then see how its bytecode looks like. Here is an example:
16
+
Seeing is believing. To see what bytecode looks like, you can use a Python module called [`dis`](https://docs.python.org/3/library/dis.html). "dis" is short of for _dis_assembler. You can write source code then see how its bytecode looks like. Here is an example:
17
17
18
18
19
19
20
20
21
-
## How RustPython turns your code to bytecode
21
+
## How RustPython turns your code into bytecode
22
22
23
-
Here are the main steps that RustPython currently does:
23
+
Here are the main steps that RustPython currently goes through:
24
24
- parse the line of source code into tokens
25
25
- determine if the tokens have a valid syntax
26
26
- create an Abstract Syntax Tree (AST)
@@ -31,7 +31,7 @@ This list of steps introduces some new concepts like: tokens and abstract syntax
31
31
32
32
### Step 1: parsing source code into tokens
33
33
34
-
The fastest way to understand what tokens are, is to see them. Conveniently, Python comes with a [tokenizer](https://docs.python.org/3/library/tokenize.html). Here is what happen if I run the tokenizer on the function that I created earlier.
34
+
The fastest way to understand what tokens are, is to see them. Conveniently, Python comes with a [tokenizer](https://docs.python.org/3/library/tokenize.html). Here is what happens if I run the tokenizer on the function that I created above.
35
35
36
36
`$ python -m tokenize file.py`
37
37
@@ -46,20 +46,20 @@ def add(x,y):
46
46
47
47
48
48
49
-
A picture IS worth a thousand word 😛 Those are the tokens. They are the basic "units" in the programming language. They are the keywords and operators that you typed. Even new lines and identations count.
49
+
A picture IS worth a thousand words 😛 Those are the tokens. They are the basic "units" of the programming language. They are the keywords and operators that you typed. Even new lines and identation count.
50
50
51
51
If you want to sound fancy:
52
52
- The tokens are the basic "lexical components"
53
53
- The parsing process is called "lexical analysis"
If you want dive into the details of lexical analysis, check out [Python in a nutshell / Lexical structure](https://learning.oreilly.com/library/view/python-in-a/9781491913833/ch03.html#python_language-id00003)
62
+
If you want to dive into the details of lexical analysis, check out [Python in a nutshell / Lexical structure](https://learning.oreilly.com/library/view/python-in-a/9781491913833/ch03.html#python_language-id00003)
63
63
64
64
65
65
### Step 2 : determine if the tokens are valid syntax
@@ -70,8 +70,8 @@ In the previous step, if you add random stuff to your function and tokenize it,
70
70
71
71
So don't hate on the whole interpreter when you get error messages! or at least don't hate on the tokenizer!
72
72
73
-
To determine if the tokens are valid syntax, first you need a definition of what a valid syntax is. Python has a defined "grammar" or set of rules. The official reference is on [this link](https://docs.python.org/3/reference/grammar.html). There, you will find a machine readable file. You may read a book to know the rules of python, but words are too "fluffy", an algorithm that verifies if rules are followed needs a very strict set of rules encoded in a file. [This video](https://www.youtube.com/watch?v=KGMFvy2d5OI) explains the Python grammar and the file's notation.
74
-
As the presenter puts it, this is the spirit of the beast (python) and it is only ~10KB 😭 (compare that to the size of python books you had to read!)
73
+
To determine if the tokens are valid syntax, first you need a definition of what a valid syntax is. Python has a defined "grammar" or set of rules. The official reference is on [this link](https://docs.python.org/3/reference/grammar.html). There, you will find a machine readable file. You may read a book to know the rules of Python, but words are too "fluffy", an algorithm that verifies if the rules are followed needs a very strict set of rules encoded in a file. [This video](https://www.youtube.com/watch?v=KGMFvy2d5OI) explains the Python grammar and the file's notation.
74
+
As the presenter puts it, this is the spirit of the beast (Python) and it is only ~10KB 😭 (compare that to the size of the Python books you had to read!)
75
75
76
76
So, we have the rules or grammar of a programming language in a machine encoded format... now we need to write something that verifies that those rules were followed... This sounds like something that other people could use and like something that should exist as an open source project! 🤔
77
77
@@ -91,7 +91,7 @@ You can do:
91
91
92
92
## Recap 🥴 🥵
93
93
94
-
As a recap, when you write a line of python code and "run it", here is what the RustPython interpreter does:
94
+
As a recap, when you write a line of Python code and "run it", here is what the RustPython interpreter does:
95
95
96
96
**INPUT: your code** (in `file.py` or interactive shell)
At the very end of 2019, we finally reached one of the short-term goals: CPython unittest support. Due to this enhancement, finding CPython compatibility is easier than before.
10
-
Probably this will be the major source of contribution spots for the new contributors this year. Here is a simple guideline.
9
+
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.
10
+
This will probably be the major source of contributions for new contributors this year. Here is a simple guideline.
11
11
12
12
## Fix known compatibility bugs
13
13
Let's find an incompatibility issue and fix it.
14
-
15
-
1. See `Lib/test` directory of the project. There are many `test_` prefixed files like `test_unicode.py`.
14
+
1. Look at the `Lib/test` directory of the project. There are many `test_` prefixed files like `test_unicode.py`.
16
15
2. Try to open one of them. It might look just fine at a glance - but search for `TODO: RUSTPYTHON` in the files. There are tons of skipped, marked as an expected failure or commented out tests.
17
-
1. Alternatively, try looking at the [regression tests results]({% link pages/regression-tests-results.markdown %}) to find skipped or expected failure tests; some of them have
16
+
1. Alternatively, try looking at the [regression test results]({% link pages/regression-tests-results.markdown %}) to find skipped or expected failure tests; some of them have
18
17
notes for a way to resolve the issue.
19
-
3. Choose one or two interesting bugs. Remove the test blocker - skip, expectedFailure or comments.
18
+
3. Choose one or two interesting bugs. Remove the test blocker - `skip`, `expectedFailure` or comments.
20
19
4. Try to fix them.
21
20
22
-
Here is a quick tip to run single unittest file.
21
+
Here's how you run a single unittest file:
23
22
24
-
`$ RUSTPYTHONPATH=Lib cargo run --release Lib/test/test_unicode.py`
23
+
`$ RUSTPYTHONPATH=Lib cargo run --release Lib/test/test_unicode.py`
25
24
26
25
## Add a new unittest file
27
-
Because CPython unittest is not perfectly working in RustPython, we are doing this one by one with editings.
28
-
1. Download CPython source code.
29
-
2. Check out a specific version of CPython. For now, 3.8.2 is recommended. (We are testing against CPython 3.8 and 3.8.2 is the most recent version for now)
30
-
3. Copy a file from CPython `Lib/test`
31
-
4. Commit the file without editing. Specify copied CPython version to commit message.
26
+
Because CPython unittest doesn't work work perfectly in RustPython, we are adding test files one by one. Here's how:
27
+
1. Download the CPython source code with `git clone https://github.com/python/cpython.git`.
28
+
2. 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](https://www.python.org/doc/versions/)) is recommended.
29
+
3. Copy a file from CPython's`Lib/test`
30
+
4. Commit the file without editing it. Specify the CPython version you copied from in the commit message.
32
31
5. Try to edit it until it runs without a crash or failure.
33
32
6. Commit the changes to make it run. This is the core contribution.
34
33
35
-
Because RustPython is not perfect, "try to edit it until it runs" doesn't mean to make 100% successful running. The common editing methods here:
36
-
1.At least it must be able to start to run the test. Fix the test code or bug until it runs at least a single unit of the test. Typically, unimplemented stdlib or missing files of unittest can make issues. Sometimes RustPython bugs make issues too.
37
-
2. If any test is not loadable by `SyntaxError`, that part is required to be commented out.
38
-
3. If any test leads to a crash of RustPython, this code is not possible to run. Mark the test to skip.
39
-
4. If any test is run but fails, this is an incompatibility issue. Mark the test as an expected failure.
34
+
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:
35
+
1.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 `unittest` can cause issues. Sometimes RustPython bugs cause issues too.
36
+
2. If any test can't be loaded because of a `SyntaxError`, you'll have to comment that part out.
37
+
3. 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.
38
+
4. If any test runs but fails, this is an incompatibility issue. Mark the test as an expected failure with `@unittest.expectedFailure`.
40
39
41
-
We prefer the reversed order of upper methods. The later the more strict so easy to detect any progress or regression.
42
-
When we temporarily disable parts of unittest due to RustPython caveats, we mark them to find it out easily later. Please check the examples below or search for `TODO: RUSTPYTHON` in `Lib/test` directory to check actual usage.
40
+
We prefer the reversed order of above methods. The later, the more strict, so it's easier to detect any progress or regression.
41
+
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.
43
42
44
43
Comment out:
45
44
```python
@@ -48,18 +47,18 @@ Comment out:
48
47
# def ... # commented out tests
49
48
```
50
49
51
-
skip:
50
+
`skip`:
52
51
```python
53
52
@unittest.skip("TODO: RUSTPYTHON")
54
53
def...# skipped tests
55
54
```
56
55
57
-
expectedFailure:
56
+
`expectedFailure`:
58
57
```python
59
58
#TODO: RUSTPYTHON
60
59
@unittest.expectedFailure
61
60
def...# failed tests
62
61
```
63
62
64
63
## Development guide
65
-
For the general source of the development, please visit the [RustPython development guide](https://github.com/RustPython/RustPython/blob/master/DEVELOPMENT.md)
64
+
For a general introduction to RustPython development, please visit the [RustPython development guide](https://github.com/RustPython/RustPython/blob/master/DEVELOPMENT.md)
Copy file name to clipboardexpand all lines: index.markdown
+3-3
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ installation:
26
26
27
27
goals:
28
28
- goal:
29
-
Full Python-3 environment entirely in Rust (not CPython bindings), with
29
+
Full Python3 environment entirely in Rust (not CPython bindings), with
30
30
a clean implementation and no compatiblity hacks.
31
31
# TODO: integrate this into the "goals" boxes
32
32
progress:
@@ -53,10 +53,10 @@ There are many implementations of Python. For example:
53
53
-[PyPy](https://www.pypy.org/) (Python)
54
54
-[Stackless](http://www.stackless.com/)
55
55
56
-
Each of these implementations offer some benefits: Jython, for example, compiles Python source code to Java byte code, then routes it to the Java Virtual Machine. Because Python code is translated to Java byte code, it looks and feels like a true Java program at runtime and so it integrates well with Java applications.
56
+
Each of these implementations offer some benefits: Jython, for example, compiles Python 2 source code to Java byte code, then routes it to the Java Virtual Machine. Because Python code is translated to Java bytecode, it looks and feels like a true Java program at runtime and so it integrates well with Java applications.
57
57
58
58
IronPython is well-integrated with .NET, which means IronPython can use the .NET framework and Python libraries or vice versa.
59
59
60
60
We want to unlock the same possibilities that Jython and IronPython enable, but for the Rust programming language. In addition, thanks to Rusts' minimal runtime, we're able to compile RustPython to WebAssembly and allow users to run their Python code easily in the browser.
61
61
62
-
Check the "learn more" section for an explainer of all those jargon-y words, or read the blog for more in-depth technical discussion.
62
+
Check out the "learn more" section for an explainer of all those jargon-y words, or read the blog for more in-depth technical discussion.
0 commit comments