| 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)  |
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) *  |
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) * |
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) * |
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) * |
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) * |
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. |
|
|