[issue20751] Harmonize descriptor protocol documentation: direct call, super binding with Descriptor Howto docs
Change by Arthur Milchior : -- pull_requests: +28486 pull_request: https://github.com/python/cpython/pull/30271 ___ Python tracker <https://bugs.python.org/issue20751> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46182] `super` and descriptor clarification
Arthur Milchior added the comment: I do regret to have created a single bug, as I now realize that there are two issues that are less related than I first imagined. Is there a way to split a bug in two, so that both discussion can be discussed in different places. Actually, after more search abound "unbound method", I discovered in https://www.python.org/download/releases/3.0/whatsnew/ that this concept was supposed to be gone for good in 3.0 The notion is also used in a few other places in the documentation but as far as I can tell the only "definition" would be in https://docs.python.org/3.11/c-api/method.html#method-objects. While my first suggestion here was clearly wrong, I believe it still indicates a documentation bug. In that if the concept is still in the language, "unbound" should be a link to this concept. If the concept is not in the language anymore, then it should not be used without explanation. "super considered super" does not give a single example of super with a single argument. Which is probably great, because this case is far less super. However, this means that: * there is currently no way for a user that want to discover python to know that there is virtually no more reason to use super with a single argument. * for someone reading a codebase with super called with a single argument, it would be hard to figure out what it does. Actually, I was going to create a PR https://github.com/Arthur-Milchior/cpython/commit/dd453acad2b1f61867717cee4b47f944d37fb213 before seeing your answer, and while less certain, I still believe it has merits -- ___ Python tracker <https://bugs.python.org/issue46182> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue20751] Harmonize descriptor protocol documentation: direct call, super binding with Descriptor Howto docs
Arthur Milchior added the comment: "a base class ``B`` following ``A``" shouldn't it be "the base class"? . After all, there is at most one base class following ``A``. Also, I find it unclear what means "``x`` is returned unchanged, since in this context ``x`` is not a value which exists by itself. -- ___ Python tracker <https://bugs.python.org/issue20751> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46182] `super` and descriptor clarification
Arthur Milchior added the comment: "a base class ``B`` following ``A``" shouldn't it be "the base class"? . After all, there is at most one base class following ``A``. Also, I find it unclear what means "``x`` is returned unchanged, since in this context ``x`` is not a value which exists by itself. -- ___ Python tracker <https://bugs.python.org/issue46182> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46182] `super` and descriptor clarification
Arthur Milchior added the comment: I just realized that https://bugs.python.org/issue20751 already tackled some of my issues. While I still believe that some things can be improved, this mean that some of the critiques in my first messages are not entirely up to date. -- versions: -Python 3.11 ___ Python tracker <https://bugs.python.org/issue46182> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue20751] Harmonize descriptor protocol documentation: direct call, super binding with Descriptor Howto docs
Arthur Milchior added the comment: Shouldn't those change be ported to 3.10 and maybe even earlier version? They are great, but hard to find if you read the current version manual. I'm just surprised by the term "dotted lookup". The remaining of the documentation mention "attribute access". So I assumed that there was a reason to use "dotted lookup" instead of "attribute access". If there is such a reason, it's not clear right now. Otherwise, if they are equivalent, I'd suggest remaining consistent in the term used. I must note that "dotted lookup" is also used in the howto about descriptor, but it does not explain the difference with "attribute access". One last note, I find it a little bit strange that `a` was supposed to be the value on which the access is done, and suddenly it becomes a part of the value. -- nosy: +Arthur-Milchior ___ Python tracker <https://bugs.python.org/issue20751> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46182] `super` and descriptor clarification
New submission from Arthur Milchior : I find super documentation confusing because it uses multiple variables that are never introduced. Once you understand super, the meaning of those variables gets easier to understand, but still, I believe that it would help the documentation to rephrase some sentences. In https://docs.python.org/3/reference/datamodel.html#invoking-descriptors you can read > If a is an instance of super, then the binding super(B, obj).m() searches > obj.__class__.__mro__ for the base class A immediately following B and then > invokes the descriptor with the call: A.__dict__['m'].__get__(obj, > obj.__class__). It took me many reading to understand that `obj` is supposed to be a new variable; and also why `a` only appear once in the line. I believe it'd be better to explicitly state "We consider the case where a = super(B, obj), with `obj` an instance of B." Also, `super(B, obj).m()` seems to indicate that the method `m` is called. While ` A.__dict__['m'].__get__(obj, obj.__class__)` does not seems to call this method. Hence, I believe that the parentheses should be removed after `m` (and either `m` should be renamed to `x`, or we should state explicitly that we are not considered `a.x` anymore, contrary to the previous cases) In https://docs.python.org/3/library/functions.html#super , you can read > If the second argument is omitted, the super object returned is unbound. If > the second argument is an object, isinstance(obj, type) must be true. If the > second argument is a type, issubclass(type2, type) must be true (this is > useful for classmethods). On first reading, I have no idea what it means that a returned object is unbound. I know what "variable binding" mean, but it really does not seems to apply here. My current understanding, and I would love if someone can confirm it, is that the first sentence means that "contrary to the other cases, the returned value do not have to satisfy any bound". In this case, I believe that it would be far better to put the case with no second argument at the end of the paragraph, ensuring that "is unbound" makes sens to the reader since they already will have seen bounds. Also, it may help clarify to write "is an object `obj`" and "is a type `type2`" so that it get clear what `obj` and `type2` means. Any feedback welcome. -- assignee: docs@python components: Documentation messages: 409201 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: `super` and descriptor clarification type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue46182> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46087] format library documentation error
Arthur Milchior added the comment: ipypthon3 does not print the loop content. python3 does. I only tested with ipython. I beg your pardon. I didn't know about this difference in behavior -- nosy: -eric.smith title: Zip library documentation error -> format library documentation error ___ Python tracker <https://bugs.python.org/issue46087> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46087] Zip library documentation error
Change by Arthur Milchior : -- keywords: +patch pull_requests: +28345 stage: -> patch review pull_request: https://github.com/python/cpython/pull/30126 ___ Python tracker <https://bugs.python.org/issue46087> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46087] Zip library documentation error
New submission from Arthur Milchior :
I don't have permission to assign the issue, but I intend to post the change in
a few minutes as a PR
Copied from Richard Hyde's email to doc mailing list.
One of the examples of string formatting doesn't work. This applies to prior
versions of Python as well.
The last set of the examples headed: 'Nesting arguments and more complex
examples:' starts with the following code:
>>> for align, text in zip('<^>', ['left', 'center', 'right']):
... '{0:{fill}{align}16}'.format(text, fill=align, align=align)
...
This omits print()
The correct code would be:
>>> for align, text in zip('<^>', ['left', 'center', 'right']):
... print('{0:{fill}{align}16}'.format(text, fill=align, align=align))
...
---
I agree with Richard here that there is a problem. Most example don't use
print, but since there is no returned expression, that's the most relevant way
to express the meaning of the example. Adding an expression would just make
things more complex.
Bug introducde in 28fbea412819f90698527c1997ece5aeddf8e9a7 in 2010.
--
assignee: docs@python
components: Documentation
messages: 408624
nosy: Arthur-Milchior, docs@python
priority: normal
severity: normal
status: open
title: Zip library documentation error
type: behavior
versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python
3.9
___
Python tracker
<https://bugs.python.org/issue46087>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45922] Many method, function, built-in... are not clickable and should be
Arthur Milchior added the comment: Thanks for the warning about double link. I agree with you. I guess it's another reason why it would be non trivial to automate here. -- ___ Python tracker <https://bugs.python.org/issue45922> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45922] Many method, function, built-in... are not clickable and should be
New submission from Arthur Milchior :
I would like to work on this documentation improvement. Before spending time on
it, I would like to know whether it would be accepted in principle and whether
the way I would intend to improve the documentation would be accepted.
# Problem:
In a lot of part of the documentation, the text refers to a method, function,
built-in, variable, member defined somewhere else in the doc, but does not link
to it (I'll call it "the defined thing" in the remaining of this BPO).
## Example
As an example, in https://docs.python.org/3.10/library/imp.html#imp.reload ,
you'll get link to import from, but no link on __name__. Admittedly, it's
probably not a big deal by itself, and I would not have opened a bug report
only for this one. But I'm convinced that there are sufficiently many missing
links that a PR that would solve add a lot of them would improve the day to day
use of the documentation in a small way for a lot of users.
This example seems interesting to me because it also shows that creating the
links can not be 100% automated (even if most of it can). Indeed, __name__ is a
property of modules, but it is also a property of class, function, method,
descriptor and generator instances. The former is defined in
https://docs.python.org/3.10/library/types.html?highlight=__name__#types.ModuleType.__name__
while the latter is defined in
https://docs.python.org/3.10/library/stdtypes.html?highlight=__name__#definition.__name__
. Hence, a commit dealing with __name__ need to check that the correct
reference is used each time.
I got the idea from a change requested by Terry J Reedy on another of my
documentation PR a few days ago:
https://github.com/python/cpython/pull/29183#pullrequestreview-816414072 and I
believe this should be more systematic.
# How I'll solve this issue
## Ensuring the PR is easy to review
For each defined thing, I'll create a commit that simply add links to this
refered thing. In the example I gave, it will transform ``__name__`` to
:meth:`__name__`. That means that each commit will be very easy to review (even
if it will be boring). Even better, any diff tools can show that there are no
other difference than the one I claim to make.
### One downside
The downside is that it requires that I do not change the place where line
break occurs (otherwise, git default diff tool will show a lot of difference).
this mean that some lines will grow larger than 80 characters. In this case, I
believe that this is a cost worth paying because:
* there are already a lot of lines with more than 80 characters in the
documentation,
* reformating each paragraph will makes the reviewer work extremely hard, for
virtually no benefits
* if required, a last commit can reformat all paragraphs at the end.
## How I'll find missing references
I will NOT find all missing references. I do not believe it is a realistic
goal. My goal here is to improve the documentation, I don't care if it is not
perfect here. What I do is that I search for lines containing matching the
regexp `\`\.{2,}\`\`; they are generally, but not always, code that should be
reference. For each missing reference, I'll use search and replace in the
documentation codebase to replace the code by the link, I'll compile and check
that the link works.
## Future work
I believe ideally a linter should warn if a single word betwen `` and `` could
potentially be a reference. This seems harder work to be honest, I don't know
how I'd start it. And it seems useless while so many missing references are in
the codebase.
# Conclusion
My questions are thus:
* If I were to make such a PR, would it be accepted
* is there any feedback, improvement one would suggest that may improve the
result or save time
--
assignee: docs@python
components: Documentation
messages: 407242
nosy: Arthur-Milchior, docs@python
priority: normal
severity: normal
status: open
title: Many method, function, built-in... are not clickable and should be
type: enhancement
versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python
3.9
___
Python tracker
<https://bugs.python.org/issue45922>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45920] make doctest fails
Arthur Milchior added the comment: I know understand one thing I missed. I needed to do `make venv` after changing the make file to get 3.10 in virtual environment. The issue being that this would make doc harder to create on ubuntu since 3.10 is not yet easily accessible through apt/snap. Anyway, even when it's done, when 3.10-venv is installed on my machine and I remake venv, and I run doctest, it still fails with: Document: library/statistics Warning, treated as error: ** File "library/statistics.rst", line 150, in default Failed example: fmean(grades, weights) Exception raised: Traceback (most recent call last): File "/usr/lib/python3.10/doctest.py", line 1348, in __run exec(compile(example.source, filename, "single", File "", line 1, in fmean(grades, weights) TypeError: fmean() takes 1 positional argument but 2 were given Which comes from the fact that fmean got a new argument in 3.11 it didn't had in 3.10 So I guess the only way to actually get make doctest to work is if the virtual env uses the version of python in main. Is there anyway to do that? -- ___ Python tracker <https://bugs.python.org/issue45920> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45920] make doctest fails
New submission from Arthur Milchior : On current main, f87ea0350286837e9e96de03f8bfa215176c2928 , ``` cd cpython/Doc make doctest ``` fails. Due to: Document: library/functions --- Warning, treated as error: ** File "library/functions.rst", line ?, in default Failed example: list(zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True)) Expected: Traceback (most recent call last): ... ValueError: zip() argument 2 is longer than argument 1 Got: Traceback (most recent call last): File "/usr/lib/python3.8/doctest.py", line 1336, in __run exec(compile(example.source, filename, "single", File "", line 1, in list(zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True)) TypeError: zip() takes no keyword arguments This is not surprising since zip didn't take "Strict" kwarg in 3.8. The issue is that 3.10 doc is tested with Python 3.8. If in Makefile I change Python to "Python3.10" I get a new error, but it still mention "/usr/lib/python3.8/doctest.py" so I guess for some reason it was not using 3.10 everywhere. I don't know make enough to have any idea how to correct this one. By the way, is there a tool to auto-format .rst file? Initially, that was what I was trying to figure out, if I could get automatically warning when a new line is more than 80 chars long for example. -- assignee: docs@python components: Documentation messages: 407238 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: make doctest fails versions: Python 3.10 ___ Python tracker <https://bugs.python.org/issue45920> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45646] Star expression in comprehension wrongly indicates to use or_expression after the star
Arthur Milchior added the comment: Thank you very much Dennis. For two reasons. First, because I like a lot what you wrote. I suspect that it would have saved me time and make things less confusing. That's not certain, because at the time I was reading the documentation of or_expr, I may have skipped or forgotten the part about BNF. A solution - that would require a bigger change - is that the various blocks containing rules have a small link back to the text you wrote, so that if a reader reads the rule directly, they can find out the meta information they need to know about rules. I guess that it's technically possible to do it with an extra sphinx rule, but may not be trivial to do, and it's not clear how such a link and text should look like in practice, as it must be noticeable the first time and easy to ignore next time. Thanks also because I'm happy, and slightly relieved, that my concerns are taken seriously. I admit that I feared that I would get as answer something such as: > actually, if you knew BNF, it should be clear that the actual meaning of > or_expr is And the fact that the answer I got tries to actually clarify the documentation for people wanting to learn or review Python without being expert in programming language theory is really great. Do you open a PR with your suggested test or do I update mine? -- ___ Python tracker <https://bugs.python.org/issue45646> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45584] Clarifying truncating in documentation
Arthur Milchior added the comment: Done -- ___ Python tracker <https://bugs.python.org/issue45584> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45584] Clarifying truncating in documentation
Arthur Milchior added the comment: I'm quite fan of your suggestion. Should I push it on the PR? Do you create another PR? I'm not used to BPO, I beg your pardon, only to github -- ___ Python tracker <https://bugs.python.org/issue45584> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45646] Star expression in comprehension wrongly indicates to use or_expression after the star
Change by Arthur Milchior : -- keywords: +patch pull_requests: +27571 stage: -> patch review pull_request: https://github.com/python/cpython/pull/29303 ___ Python tracker <https://bugs.python.org/issue45646> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45646] Star expression in comprehension wrongly indicates to use or_expression after the star
Arthur Milchior added the comment: Message 405188 was supposed to be another bug report. My bad. -- ___ Python tracker <https://bugs.python.org/issue45646> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45646] Star expression in comprehension wrongly indicates to use or_expression after the star
Change by Arthur Milchior : -- title: "expression" is erroneous in the doc -> Star expression in comprehension wrongly indicates to use or_expression after the star ___ Python tracker <https://bugs.python.org/issue45646> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45647] "expression" is erroneous in the doc
New submission from Arthur Milchior : https://docs.python.org/3/reference/expressions.html#grammar-token-python-grammar-expression is wrong This line state: `expression ::= conditional_expression | lambda_expr` and it is a problem because, by the way sphinx understand reference, this mean that any people who use the token `expression` will be linked to this particular line. For example in https://docs.python.org/3/reference/expressions.html#grammar-token-python-grammar-key_datum `key_datum ::= expression ":" expression | "**" or_expr` while clearly a key_datum is not expecting only a conditional expression or a lambda expression. Admittedly, you can derive, from expression: * conditional_expression * or_test * and_test * not_test * comparison * or_expr * xor_expr * and_expr * shift_expr * a_expr * m_expr * u_expr * power * primary * atom in this order, so in practice you can probably derive most of the expressions. However, I doubt that this is what the documentation meant here, and clearly not practical. -- assignee: docs@python components: Documentation messages: 405189 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: "expression" is erroneous in the doc versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue45647> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45646] "expression" is erroneous in the doc
Arthur Milchior added the comment: https://docs.python.org/3/reference/expressions.html#grammar-token-python-grammar-expression is wrong This line state: `expression ::= conditional_expression | lambda_expr` and it is a problem because, by the way sphinx understand reference, this mean that any people who use the token `expression` will be linked to this particular line. For example in https://docs.python.org/3/reference/expressions.html#grammar-token-python-grammar-key_datum `key_datum ::= expression ":" expression | "**" or_expr` while clearly a key_datum is not expecting only a conditional expression or a lambda expression. Admittedly, you can derive, from expression: * conditional_expression * or_test * and_test * not_test * comparison * or_expr * xor_expr * and_expr * shift_expr * a_expr * m_expr * u_expr * power * primary * atom in this order, so in practice you can probably derive most of the expressions. However, I doubt that this is what the documentation meant here, and clearly not practical. -- title: The documentation wrongly uses or_expr for star expresion in displays -> "expression" is erroneous in the doc ___ Python tracker <https://bugs.python.org/issue45646> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45646] The documentation wrongly uses or_expr for star expresion in displays
New submission from Arthur Milchior : According to the current documentation, I believe there is an error in list_display, set_display and dict_display. According to list display, this is a valid expression [* l1 ^ l2] parsed as list_display: "[" starred_list: starred_item: "*" or_expr: xor_expr: xor_expr: "l1" "^" and_expr: "l2" "]" I add the full derivation from and_expr to l2 at the end of the report, it's not important for this topic. The same issue is present for set. For dictionary it is also present, but instead the error is in key_datum. I have no idea what would be the proper correction. Indeed [*l1+l2] is valid (in 3.9) at least. So it's not like the element after a star is restricted to be an atom. At the very least, I believe it should be clearly indicated that, contrary to what the name indicates, "or_expr" do not mean that we accept any or, nor any expression. It just mean that *some_complex_expression is interpreted as * (some_complex_expression) and that it is valid iff some_complex_expression is valid shift_expr: a_expr: m_expr: power: primary: atom: identifier: "l2" ------ assignee: docs@python components: Documentation messages: 405187 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: The documentation wrongly uses or_expr for star expresion in displays versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue45646> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45640] Production tokens are not clickable
Change by Arthur Milchior : -- keywords: +patch pull_requests: +27525 stage: -> patch review pull_request: https://github.com/python/cpython/pull/29260 ___ Python tracker <https://bugs.python.org/issue45640> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45640] Production tokens are not clickable
New submission from Arthur Milchior : In the current documentation, production tokens are not clickable. For example in https://docs.python.org/3/reference/expressions.html#yield-expressions , you highlight `yield_from` as a token but do not link to it. I suppose that the goal, when using :token:`yeld_from`, was to ensure that the token links to its definition. However, Sphinx require to use :token:`~python-grammar:yeld_from` for the link to appear. I suggest adding ~python-grammar after each token:. -- assignee: docs@python components: Documentation messages: 405147 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: Production tokens are not clickable versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue45640> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45619] Mentioning structural pattern matching in the list of binding
Change by Arthur Milchior : -- keywords: +patch pull_requests: +27495 stage: -> patch review pull_request: https://github.com/python/cpython/pull/29232 ___ Python tracker <https://bugs.python.org/issue45619> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45619] Mentioning structural pattern matching in the list of binding
New submission from Arthur Milchior : https://docs.python.org/3/reference/executionmodel.html list all of the way a variable may be bound. However, it seems that it was not updated. Indeed, structural pattern matching in 3.10 also allows to bind a variable and is not mentionned. As a related issue, the sentence is far too long and really would need to be broken down. At the very least, the special case "and targets that are identifiers if" is not clear, it is not indicated whether this case extends to the end of the sentence or is just local -- assignee: docs@python components: Documentation messages: 405066 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: Mentioning structural pattern matching in the list of binding versions: Python 3.10, Python 3.11 ___ Python tracker <https://bugs.python.org/issue45619> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45602] The grammar misses links that are present everywhere else
New submission from Arthur Milchior : The grammar, in https://docs.python.org/3/reference/grammar.html , lacks some utilities that the remaining of the documentation have. While it remains usable, it is hard to navigate. As an example https://www.python.org/dev/peps/pep-0634/ 's "star_named_exrpsession" and "block" links to the general grammar page, and indeed can't link to the specific rules as there are no anchor on them. This would also allow a related improvement: being able to click on a rule R in the right side of a declaration and go to the definition of R. Given the recursive nature of grammar, that would transform a sequence of search into a sequence of click (and even allow to use the browser's "back" to go back to the previous definition, or to open the new definition in a new tab) As far as I can tell, the first action would be to add a new kind of token on Doc/tools/extensions/peg_highlight.py , so that we distinguish the left and the right part of the rule. The left part (the name of the declared rule) would be easy to recognize as it always start on the beginning of the line and end with :. The second action would be that, for each declaration D, the html would contain an anchor "#D". And each time D would appear on the right hand side of a rule, it would be in a link to #D I suspect that adding those links and anchor could be done by overriding the default formatter or highlighter, but I don't understand pygment well enough to know what should be done here -- assignee: docs@python components: Documentation messages: 404946 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: The grammar misses links that are present everywhere else type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue45602> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45584] Clarifying truncating in documentation
New submission from Arthur Milchior : While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) I assume that I won't be the only user having this trouble, especially for people whose mother tongue is not English. So I suggest adding a clarification to help make what should be obvious to most actually explicit -- assignee: docs@python components: Documentation messages: 404850 nosy: ArthurMilchior, docs@python priority: normal severity: normal status: open title: Clarifying truncating in documentation type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue45584> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45583] Documentation of int() in datamodel.rst is out of date
New submission from Arthur Milchior : In 3.8, int() default implementation changed, using __index__() if it is available instead of __trunc__(). The file function.rst was updated accordingly, but the redundant information in datamodel.rst contained out of date information I offer a correction in https://github.com/python/cpython/pull/29182 (but ideally it should be added back to 3.8 python documentation) -- assignee: docs@python components: Documentation messages: 404848 nosy: ArthurMilchior, docs@python priority: normal severity: normal status: open title: Documentation of int() in datamodel.rst is out of date versions: Python 3.8 ___ Python tracker <https://bugs.python.org/issue45583> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
