Do you feel bad because of the Python docs?
Terry Reedy
tjreedy at udel.edu
Tue Feb 26 20:48:51 EST 2013
On 2/26/2013 1:52 PM, Devin Jeanpierre wrote:
> I would assert it isn't very kind to those even with basic fundamentals.
>
> For example, under precisely what circumstances does int() raise
> TypeError? You won't find that under either int's documentation, or
> TypeError's documentation, you have to look it up under __int__, which
> is _not_ a basic fundamental. And rather than helping you along the
> way, the documentation for int() actively misleads you by its
> implicature that the only acceptable types are strings, ints, and
> floats. And then even if you have the foresight to remember "oh yeah,
> isn't there a special method for this?", you have to find the
> documentation for __int__, which is itself is three quarters of the
> way down this massive page:
> http://docs.python.org/2/reference/datamodel.html
Have you opened an issue, or checked for existing issue? I would be open
to the idea that entries like that for int should not be overly type
specific and imply that the defaults are the only possibilities.
Perhaps there should be a cross-reference to corresponding special
methods. Perhaps that idea might be opposed. I am not sure. Perhaps
Built-in Functions needs a bit more general explanatory text at the top.
--
Terry Jan Reedy
More information about the Python-list
mailing list