[issue11977] Document int.conjugate, .denominator, ...

New submission from Jonas H. <jonas@lophus.org>: Various `int` attributes and methods seem undocumented (at least it does not work to intersphinx them): * .conjugate * .denominator * .imag * .numerator * .real ---------- assignee: docs@python components: Documentation messages: 134926 nosy: docs@python, jonash priority: normal severity: normal status: open title: Document int.conjugate, .denominator, ... versions: Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Roundup Robot <devnull@devnull> added the comment: New changeset dc65d1b99dff by Benjamin Peterson in branch '3.1': note abcs of int and float (closes #11977) http://hg.python.org/cpython/rev/dc65d1b99dff New changeset 5b315145e525 by Benjamin Peterson in branch '2.7': note abcs of int and float (closes #11977) http://hg.python.org/cpython/rev/5b315145e525 ---------- nosy: +python-dev resolution: -> fixed stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: Benjamin: In 2.7, long implements those ABCs too. I have added it to the doc in a local commit, I’ll push when I can. Jonas: Does the commit fix your use case? The attributes are now documented in the sense that a human can find them, but can Sphinx? ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: BTW: If not, you can always use things like :attr:`int.real <numbers.Integral.real>` (real target in angle brackets, rest is text to display) but it’s a bit unwieldy. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Jonas H. <jonas@lophus.org> added the comment: It doesn't. Sphinx still can't make any links, which btw also means that it's impossible to reference those methods within the Python documentation. Also I want to point out that I find the information very hard to find as a human. The fact that integers are based on `numbers.Number` is -- at this point in time where 95% of all Python developers don't know about the `numbers` module or abstract base classes in general -- an implementation detail and as such should not affect the way `int` is documented. I propose to have decent class references for int, str, ... similar to the reference for dict -- that is, document all attributes and methods in one place and make them referencable. For those who want to deep-dive into CPython internals, a note about those functionality actually being implemented in ABCs could be added. (But I think that's out of scope for this ticket. I could open a new one if anyone agrees with me... :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Georg Brandl <georg@python.org> added the comment: Reopening, it makes sense to have everything available for linking. (Even if they are quite obscure attributes.) ---------- nosy: +georg.brandl status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment:
---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Ezio Melotti <ezio.melotti@gmail.com> added the comment: Isn't there a way to specify multiple targets for the same entry? The doc could say that int, float and complex all share some methods/attributes and then either list e.g. int.conjugate, float.conjugate, complex.conjugate with a single description or use just int (or even numbers.Number) and create targets for float and complex too in some other way, so that float.conjugate automatically links to the description of Number.conjugate. I don't think it's necessary to document all methods/attributes in the same place. These methods/attributes are not so common, so it's ok to have them documented in the numbers.Number page, for example. A simple link to the page can then be added to the int/float/complex docs. See also #4966 for a discussion about the reorganization of the stdtypes page. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Change by Sergey B Kirpichev <skirpichev@gmail.com>: ---------- nosy: +Sergey.Kirpichev _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11977> _______________________________________

Roundup Robot <devnull@devnull> added the comment: New changeset dc65d1b99dff by Benjamin Peterson in branch '3.1': note abcs of int and float (closes #11977) http://hg.python.org/cpython/rev/dc65d1b99dff New changeset 5b315145e525 by Benjamin Peterson in branch '2.7': note abcs of int and float (closes #11977) http://hg.python.org/cpython/rev/5b315145e525 ---------- nosy: +python-dev resolution: -> fixed stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: Benjamin: In 2.7, long implements those ABCs too. I have added it to the doc in a local commit, I’ll push when I can. Jonas: Does the commit fix your use case? The attributes are now documented in the sense that a human can find them, but can Sphinx? ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: BTW: If not, you can always use things like :attr:`int.real <numbers.Integral.real>` (real target in angle brackets, rest is text to display) but it’s a bit unwieldy. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Jonas H. <jonas@lophus.org> added the comment: It doesn't. Sphinx still can't make any links, which btw also means that it's impossible to reference those methods within the Python documentation. Also I want to point out that I find the information very hard to find as a human. The fact that integers are based on `numbers.Number` is -- at this point in time where 95% of all Python developers don't know about the `numbers` module or abstract base classes in general -- an implementation detail and as such should not affect the way `int` is documented. I propose to have decent class references for int, str, ... similar to the reference for dict -- that is, document all attributes and methods in one place and make them referencable. For those who want to deep-dive into CPython internals, a note about those functionality actually being implemented in ABCs could be added. (But I think that's out of scope for this ticket. I could open a new one if anyone agrees with me... :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Georg Brandl <georg@python.org> added the comment: Reopening, it makes sense to have everything available for linking. (Even if they are quite obscure attributes.) ---------- nosy: +georg.brandl status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment:
---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Ezio Melotti <ezio.melotti@gmail.com> added the comment: Isn't there a way to specify multiple targets for the same entry? The doc could say that int, float and complex all share some methods/attributes and then either list e.g. int.conjugate, float.conjugate, complex.conjugate with a single description or use just int (or even numbers.Number) and create targets for float and complex too in some other way, so that float.conjugate automatically links to the description of Number.conjugate. I don't think it's necessary to document all methods/attributes in the same place. These methods/attributes are not so common, so it's ok to have them documented in the numbers.Number page, for example. A simple link to the page can then be added to the int/float/complex docs. See also #4966 for a discussion about the reorganization of the stdtypes page. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

Change by Sergey B Kirpichev <skirpichev@gmail.com>: ---------- nosy: +Sergey.Kirpichev _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11977> _______________________________________
participants (6)
-
Ezio Melotti
-
Georg Brandl
-
Jonas H.
-
Roundup Robot
-
Sergey B Kirpichev
-
Éric Araujo