classification
Title: Document int.conjugate, .denominator, ...
Type: Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: open Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, jonash, python-dev
Priority: normal Keywords:

Created on 2011-05-01 20:25 by jonash, last changed 2011-12-24 19:20 by ezio.melotti.

Messages (8)
msg134926 - (view) Author: Jonas H. (jonash) * Date: 2011-05-01 20:25
Various `int` attributes and methods seem undocumented (at least it does not work to intersphinx them):

* .conjugate
* .denominator
* .imag
* .numerator
* .real
msg134938 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-05-01 22:37
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
msg135318 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-06 16:35
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?
msg135319 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-06 16:36
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.
msg135341 - (view) Author: Jonas H. (jonash) * Date: 2011-05-06 17:26
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... :-)
msg135342 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-05-06 17:31
Reopening, it makes sense to have everything available for linking.

(Even if they are quite obscure attributes.)
msg135343 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-06 17:31
> 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.
Not really: int is not based on numbers.Number, but the ABC serves as documentation.

> 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.
Hum, I think this should be fixed, but not with tons of text containing duplicated information (once for int, once for long, once for float...)  Ezio: you recently fixed a similar problem with collections ABCs methods; what’s your opinion here?
msg150234 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-24 19:20
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.
History
Date User Action Args
2011-12-24 19:20:36ezio.melottisetmessages: + msg150234
2011-05-06 17:31:57eric.araujosetnosy: + ezio.melotti
messages: + msg135343
2011-05-06 17:31:29georg.brandlsetstatus: closed -> open
nosy: + georg.brandl
messages: + msg135342

2011-05-06 17:26:56jonashsetmessages: + msg135341
2011-05-06 16:36:18eric.araujosetmessages: + msg135319
2011-05-06 16:35:04eric.araujosetnosy: + eric.araujo
messages: + msg135318
2011-05-01 22:37:46python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg134938

resolution: fixed
stage: resolved
2011-05-01 20:25:26jonashcreate