bpo-45646: clarifying the meaning of expression #29303
Conversation
Expression rules are quite confusing. For example `x & y` is a "or_expr". This makes sens only if you understand that "or_expr" means "you can use an | here, and potentially other things" instead of "an expression using |" which is the intuitive meaning. I check my intuition on #help-broccoli on Python channel, and it seems that multiple helpers were as confused as myself when they discovered that list comprehension used or_expr according to the syntax, while | is not usually defined on list. This edit expects to ensure future reader do not make the same mistake I did while reading chapter 6 of the reference. Furthermore, it provides an example of the syntax note, which, I hope, will help clarify it.
Arthur-Milchior
force-pushed
the
expression
branch
from
ae18b0c to
b57dd58
Compare
This rewritting was provided by Dennis Sweeney (@sweeneyde), with a few changes and Sphinx syntax by me. The only purpose of using `grammar-example` is to ensure that the usual a_expr token is distinct from the example one. So that links can decide whether they points to the example or to the explanation of a_expr I was not able to get m_expr to be a link. According to the doc, `~python-grammar:m_expr` should suffice to link to python-grammar's rule for m_expr. However, after testing, it was just displayed as "~python-grammar:m_expr" (and I checked, it was compiled with sphinx 4.2.0)
|
Rewritten, thanks to @sweeneyde Main difficulty was to ensure that a_expr in the example is not actually used. So that when the documentation links to a_expr, it links to the non-example one, with the actual explanation. For this, I had to use a new scope grammar-example. I've got a slight problem. I want the link to m_expr to link to the usual m_expr. According to Sphinx documentation it is possible https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-productionlist I rebased onto master to use the very recent dependency update of sphinx to 4.2.0. However, I kept the previous commit for history purpose as requested in other PR |
Arthur-Milchior
force-pushed
the
expression
branch
from
b57dd58 to
61cdf4e
Compare
|
Could someone add "skip news" label, please? Because it's the only cause of failure of tests. |
There was a problem hiding this comment.
My apologies that this PR was left for so long. I still believe it can make a meaningful improvement.
Also, could you please git merge the main branch into this branch to make sure everything is up-to-date? That entails something like
git checkout expression
git fetch upstream main # assuming upstream points as python/cpython
git merge upstream/main
git push origin expressions # assuming origin is Arthur-Milchior/cpython
| instances of :token:`~python-grammar:m_expr`, the rule implies that ``x * y``, | ||
| ``x / y + a[i]``, and (recursively) ``foo.bar + x * y - a[i]`` are all instances | ||
| of :token:`~grammar-example:a_expr`. Unless specified otherwise, the semantic of | ||
| all of those expressions considered as an :token:`~grammar-example:a_expr` is |
There was a problem hiding this comment.
all of those expressions
I think the above is ambiguous. It may be more clear to say something like
The semantics of
x * yas ana_exprare the same as its semantics as anm_expr, and the same holds for other "pass-through" rules unless otherwise specified.
| @@ -10,14 +10,28 @@ Expressions | |||
| This chapter explains the meaning of the elements of expressions in Python. | |||
|
|
|||
| **Syntax Notes:** In this and the following chapters, extended BNF notation will | |||
There was a problem hiding this comment.
A link to https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form might be helpful here.
#bpo-45646: clarifying the meaning of expression
Expression rules are quite confusing. For example
x & yis a "or_expr". Thismakes sens only if you understand that "or_expr" means "you can use an | here,
and potentially other things" instead of "an expression using |" which is the
intuitive meaning.
I check my intuition on #help-broccoli on Python channel, and it seems that
multiple helpers were as confused as myself when they discovered that
list comprehension used or_expr according to the syntax, while | is not usually
defined on list.
This edit expects to ensure future reader do not make the same mistake I did
while reading chapter 6 of the reference. Furthermore, it provides an example of
the syntax note, which, I hope, will help clarify it.
https://bugs.python.org/issue45646