[Python-ideas] Fix some special cases in Fractions?

Paul Moore p.f.moore at gmail.com
Thu Aug 30 08:56:57 EDT 2018


On Thu, 30 Aug 2018 at 12:04, Jonathan Fine <jfine2358 at 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


More information about the Python-ideas mailing list