
Hi, Riccardo. I'm who removed the __cause__ from tutorial, and I had translated Japanese translation of official Python document hard. On Sun, Nov 8, 2020 at 3:07 AM Riccardo Polignieri via Python-Dev <python-dev@python.org> wrote:
This morning I noticed this new commit, referring to bpo-42179: "Remove mention of __cause__" (https://bugs.python.org/issue42179). From reading this thread, it turns out that a minor confusion in the wording, about __cause__ and __context__, very quickly turned into the decision to completely remove any reference to __cause__, the reason being that "generally speaking (...) we should *reduce* some details from tutorial".
Note that the discussion not only in the b.p.o thread, but in this mailing list too. Please read this long thread. https://mail.python.org/archives/list/python-dev@python.org/thread/MXMEFFYB6...
We all know that the tutorial is "too difficult", not really suitable for beginners (perhaps not even Python beginners!). Having spent a couple of weeks translating it as recently as this spring, I am well aware of this. At times, it feels more like a demo or a features' showcase: a feeling reinforced, by the way, often by the *recent* additions like the special parameters syntax (https://docs.python.org/3/tutorial/controlflow.html#special-parameters).
Agree.
However, unless someone undertakes a sweeping rewriting of the tutorial (and until they do), I think it would be unwise to start cherry-picking the occasional bit of information to expunge or "simplify" from time to time, without an overall guideline.
I expect documenting working group will discuss the guideline.
Reason is, right now the tutorial is packed with informations (beginner-unfriendly as they might be) that you would be hard pressed to find elsewhere in the documentation: see the aforementioned section on special parameters; see the maddening chapter on Classes (and especially the exposition on scopes and namespaces); see, of course, the floating point appendix; and I could go on.
Agree. There are tons of beginner unfriendly bits in the tutorial.
My concern here is that if you start removing or simplifying some "too-difficult-for-a-tutorial" bits of information on an occasional basis, and without too much scrutiny or editorial guidance, you will end up loosing something precious.
Like everyone, I also look forward to an overall rewriting of the tutorial; but in the meantime, I would kindly ask you to be very careful and conservative about deleting information solely for "didactic" reasons.
For the record, when I removed the `__cause__` from the tutorial, I believe I was careful and conservative enough. I think `from exc` syntax is not new Python users should know. Documenting implicit chaining is enough for 99% use cases, and `from None` covers 0.99% of the rest. So I considered removing explicit chaining (e.g. `from exc`) from the section too. But I kept it, because it's a "syntax showcase" even though it will give more noise to beginners. And deleting `__cause__` is not solery for "didactic" reason, nor "loosing something precious." As written in the b.p.o. issue, mention only `__cause__` "lose some precious". We need to describe `__context__` and `__suppress_context__` too. But all of them are documented in library/exceptions.html. Removing `__cause__` and adding a link to library/exceptions.html makes sense more than documenting all. Bests, -- Inada Naoki <songofacandy@gmail.com>