On Thu, 30 Aug 2018 at 12:04, Jonathan Fine <jfine2...@gmail.com> wrote: > First, the docs for the fraction module could be improved. Here's the > page and it's history. > > https://docs.python.org/3/library/fractions.html > https://github.com/python/cpython/commits/3.7/Doc/library/fractions.rst > > Already, doing this will help users.
While the documentation is pretty terse and could be expanded, it's worth noting that the class also has docstrings. And whether we feel that docstrings are sufficiently accessible for users (certainly I often forget to check them) they *are* part of the module documentation. In particular: >>> help(fractions.Fraction.__pow__) Help on function __pow__ in module fractions: __pow__(a, b) a ** b If b is not an integer, the result will be a float or complex since roots are generally irrational. If b is an integer, the result will be rational. That's clear, concise, and explains the current behaviour precisely. Neil's proposal is definitely a functional change (not that he was denying this) in that it alters already documented behaviour. And I think that's something we should remember. This isn't undocumented (or even badly documented) behaviour - it's clearly defined behaviour noted in the official documentation (just in a part of that documentation that's easy to overlook). > In particular, for a different > approach, point them to > > https://www.sympy.org/en/index.html I don't honestly think that sympy is a comparable tool to the stdlib Fraction class. I suspect that most people who need the Fraction class are not even remotely in the target audience for sympy. The ones who are, likely already know about it. > And finally, thank you for drawing to our attention this blemish in > the fractions module (or its documentation). I wouldn't describe it as a blemish. Rather, it's somewhere we could maybe improve the discoverability of the existing documentation. Or an opportunity to review how we make it easier for users to get access to documentation that is held in docstrings, as opposed to the manuals. Maybe a pydoc instance available online, linked from the manual entries? Paul _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/