Not found in the documentation

[Stestagg]

On Tue, Apr 27, 2021 at 12:52 PM elas tica <elasstiika at gmail.com> wrote:

>
> > However, in this case, the general information in the docs is
> > absolutely sufficient, and the basic principle that the repr should
> > (where possible) be a valid literal should explain what's needed.
>
>
> This is a subjective statement. Recall: explicit is better implicit. Alas,
> many parts of the Python docs are written in a conversational style, full
> of implicit and fuzzy meanings.
>

The general rule of thumb that I use is:

The *Library Reference* section of the Python docs contains info that cover
90% of use-cases and questions. (note built-in types are a section in the
library reference, despite being built-in to the interpreter and not really
part of the standard library, but this makes sense if you consider the
library reference to be more 'friendly' documentation that tries to balance
verbosity and covering every corner case explicitly against readability and
approachability.  This could be considered a 'conversational' style, but
that style is generally considered a feature in the library reference
section.

The *Language Reference* is designed to be much more formally defined, and
favors correctness and completeness over being easy to access by less
technical readers.

In this case, subjectively, I (and I think Chris agrees here) feel that
python's behavior with calling str(<int_val>) is suitably non-surprising
(especially when compared to almost every other modern language) that being
described in the language reference seems entirely reasonable.

There's an argument to be made that the description of the expected
__str__() behavior of ints is not easy to find within section 3 of the
language reference, and I imagine that a reasonable proposed change to this
wording would be considered favourably. (python is accepting pull requests
when they pass review :).

Steve



> --
> https://mail.python.org/mailman/listinfo/python-list
>