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/MXMEFFYB6JXAKSS36SZ7DX4ASP6APWFP/ > > 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 <songofaca...@gmail.com> _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/O3TKYY24BEJHJBROC2KEJJCR6SYZLIKM/ Code of Conduct: http://python.org/psf/codeofconduct/
