[issue40257] Improve the use of __doc__ in pydoc

[Erlend E. Aasland]

Change by Erlend E. Aasland :


--
components: +Library (Lib) -Interpreter Core
nosy: +eamanu, gvanrossum, levkivskyi, lukasz.langa, mark.dickinson, mbussonn, 
ncoghlan, serhiy.storchaka, tcaswell, terry.reedy, veky, xtreak -ahmedsayeed1982
versions: +Python 3.9 -Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Erlend E. Aasland]

Change by Erlend E. Aasland :


--
Removed message: https://bugs.python.org/msg405706

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Ahmed Sayeed]

Ahmed Sayeed  added the comment:

<1>: Abbrev Number: 46 (DW_TAG_array_type) 
http://www.compilatori.com/travel/youtube/
   DW_AT_data_location: 2 byte block: 97 6 
(DW_OP_push_object_address; DW_OP_deref) 
http://www.acpirateradio.co.uk/travel/carbon-dioxide-emissions/
   DW_AT_rank: 6 byte block: 97 23 10 6 37 1a
   DW_AT_type: <0x139> 
http://www.logoarts.co.uk/travel/actions-camera/
   DW_AT_sibling : <0xe51>
 <2>: Abbrev Number: 47 (DW_TAG_generic_subrange) 
http://www.slipstone.co.uk/travel/hyundai-kona/
   DW_AT_lower_bound : 8 byte block: 97 14 48 1e 23 20 22 6
(DW_OP_push_object_address; DW_OP_over; DW_OP_lit24; DW_OP_mul; 
DW_OP_plus_uconst: 32; DW_OP_plus; DW_OP_deref) 
http://embermanchester.uk/travel/whatsapp/
   DW_AT_upper_bound : 8 byte block: 97 14 48 1e 23 28 22 6
(DW_OP_push_object_address; DW_OP_over; DW_OP_lit24; DW_OP_mul; 
DW_OP_plus_uconst: 40; DW_OP_plus; DW_OP_deref) 
http://connstr.net/travel/charging-machines/
   DW_AT_byte_stride : 11 byte block: 97 14 48 1e 23 18 22 6 8 38 1e   
(DW_OP_push_object_address; DW_OP_over; DW_OP_lit24; DW_OP_mul; 
http://joerg.li/travel/kia-rio/   DW_OP_plus_uconst: 24; DW_OP_plus; 
DW_OP_deref; DW_OP_const1u: 56; DW_OP_mul)
...
 http://www.jopspeech.com/travel/london/
We start out in read_array_type with:
...
  type = element_type;
... http://www.wearelondonmade.com/travel/renault/
and then iterate over range_types to build up the type further.

But there are no DW_TAG_subrange_type children (only one 
DW_TAG_generic_subrange), so range_types is empty, and type is kept unmodified. 
https://waytowhatsnext.com/services/netflix-services/

Consequently, in set_die_type we apply the DW_AT_data_location to the 
element_type (the one at 0x139) instead of to the newly build array type.
http://www.iu-bloomington.com/services/xiaomi-services/
Then we try to print c_nd:
...
 <2><6e8>: Abbrev Number: 2 (DW_TAG_variable)
<6e9>   DW_AT_name: (indirect string, offset: 0x218): c_nd
<6ed>   DW_AT_decl_file   : 1 
https://komiya-dental.com/services/huawei-service/
<6ed>   DW_AT_decl_line   : 198
<6ee>   DW_AT_type: <0x139>
<6f2>   DW_AT_location: 9 byte block: 3 e0 30 60 0 0 0 0 0  
(DW_OP_addr: 6030e0)
... http://www-look-4.com/travel/new-cars/
and find that the type has a data_location property, which when used gives 
incorrect results.
...
  type = element_type;
...
and then iterate over range_types to build up the type further.
 https://www.webb-dev.co.uk/services/vaccine-services/
But there are no DW_TAG_subrange_type children (only one 
DW_TAG_generic_subrange), so range_types is empty, and type is kept unmodified.

Consequently, in set_die_type we apply the DW_AT_data_location to the 
element_type (the one at 0x139) instead of to the newly build array type.

--
components: +Interpreter Core -Library (Lib)
nosy: +ahmedsayeed1982 -eamanu, gvanrossum, levkivskyi, lukasz.langa, 
mark.dickinson, mbussonn, ncoghlan, serhiy.storchaka, tcaswell, terry.reedy, 
veky, xtreak
versions: +Python 3.6 -Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Emmanuel Arias]

Change by Emmanuel Arias :


--
nosy: +eamanu
nosy_count: 11.0 -> 12.0
pull_requests: +21452
pull_request: https://github.com/python/cpython/pull/22390

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Matthias Bussonnier]

Matthias Bussonnier  added the comment:

> Looks like the revert is solving the issue?

It appears to do so as far as I can tell, and most test pass on nightly, the 
rest seem to be unrelated to changes in current 3.9. 

Many thanks to Serhiy for all the work on making documentation better, and 
there are definitively case where a version of getowndoc, or something that 
discriminate where the docstring comes from would be useful.

I also agree that having _some_ ability to extend docstring would be nice but 
it's likely for another issue.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Łukasz Langa]

Łukasz Langa  added the comment:

Looks like the revert is solving the issue?

--
priority: release blocker -> high

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:


New changeset 08b47c367a08f571a986366aa33828d3951fa88d by Serhiy Storchaka in 
branch 'master':
bpo-40257: Revert changes to inspect.getdoc() (GH-20073)
https://github.com/python/cpython/commit/08b47c367a08f571a986366aa33828d3951fa88d


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Mark Dickinson]

Change by Mark Dickinson :


--
nosy: +mark.dickinson

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Thomas Caswell]

Change by Thomas Caswell :


--
nosy: +tcaswell

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Whether or not an object has a docstring is implementation defined, and I do 
not consider it to be part of its API.  I just backported some new docstrings 
(with Brett Cannon's concurrence), and I would consider it OK for Serhiy to do 
the same with his addition.

But the return value of getdoc is half of its API.  Its 3.8 doc says
"If the documentation string for an object is not provided and the object is a 
class, a method, a property or a descriptor, retrieve the documentation string 
from the inheritance hierarchy.

Changed in version 3.5: Documentation strings are now inherited if not 
overridden."

While inherited class docstrings are sometimes inapplicable, they may not be.  
In any case, not doing so is an API change.  If done, and this is obviously 
controversial, the change needs a deprecation period.  I would say at least 2 
releases.  And this should be a separate issue.  But I suggest leaving getdoc 
alone.  I think it appropriate that it be a bit liberal in returning text that 
just might be useful.

Changing what pydoc does with the information it gets, including from getdoc, 
is a different issue -- this issue.  Pydoc could not call getdoc for classes, 
or it could determine whether the returned string is inherited and change it 
slightly as has been suggested.

Other object information functions can make their own choices. For instance, 
IDLE calltips are primarily about signature and currently only use an object's 
own docstring.  But maybe pydoc should be used for instance methods to get the 
one or two summary lines IDLE displays.

A related note: Useful specific docstrings would be easier if an object could 
directly extend a base objects docstring with
  f"{base_object.__doc__}\nExtra implementation info\n"
following the header instead of having to later write
  derived_object.__doc__ = f"".

In instructional contexts, this would be useful, in addition for classes, for 
functions that implement a docstring specificaton.
  def _factor(number):
"Return prime factors of non-negative ints as list of (prime, count) pairs."
Students could then submit an implementation with 
  def factor(number):
f"{_factor.__doc__}\nImplementation details."


--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Change by Serhiy Storchaka :


--
pull_requests: +19379
stage: resolved -> patch review
pull_request: https://github.com/python/cpython/pull/20073

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

I can just copy the implementation of inspect.getdoc() and related functions in 
pydoc for use in help(), and restore the old code in the  inspect module. Of 
course it will mean that third-party tools will continue to show incorrect 
docstrings in some cases.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Łukasz Langa]

Łukasz Langa  added the comment:

OK, that was my intuition, too. I will block beta on it then.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Yury Selivanov]

Change by Yury Selivanov :


--
nosy:  -yselivanov

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Guido van Rossum]

Guido van Rossum  added the comment:

I feel it should. At the very least, a decision should be made on how to move 
forward.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Łukasz Langa]

Łukasz Langa  added the comment:

Should this block 3.9.0b1, planned for Monday May 18th?

--
nosy: +lukasz.langa

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Matthias Bussonnier]

Matthias Bussonnier  added the comment:

I've sent a request for comments on python-dev 

https://mail.python.org/archives/list/python-...@python.org/thread/6QO2XI5B7RVZDW3YZV24LYD75VGRITFU/

Thanks.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Guido van Rossum]

Guido van Rossum  added the comment:

I'm making this a release blocker -- please everybody come to an agreement or 
ask on python-dev.

--
priority: normal -> release blocker
resolution: fixed -> remind

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Matthias Bussonnier]

Matthias Bussonnier  added the comment:

> Can you all please decide which issue to use?

We can stay here, I opened the other issue before figuring out this was the 
cause.

> If IPython wants to output the help on the instance, it should change the 
> implementation of `?` and `??`. It would be better if it correctly attribute 
> the source of the docstring: the object itself, its class or its superclass. 
> It was difficult to distinguish these cases before, now it is easier.

Sure I can do that, but this issue feel like a important semantic change of 
`inspect.getdoc()`, it may be documented but there is no warning or deprecation 
of behavior. It is also likely to affect untested code (documentation 
generation).

If you decide that this change of behavior is the one you want I'll be happy to 
support you – I just want to make sure the impact on the rest of the ecosystem. 
IPython/Jupyter is likely not the only one to rely on inspect.getdoc behavior, 
I'm thinking pycharm, spyder, sphinx will likely be impacted. I can see 
`inspect.getdoc()` in the source of even scipy/numpy and rarely in tests.


I would prefer new functions with clearer behavior and for example returning a 
sequence of tuple (docs, where it comes from) potentially deprecating 
inspect.getdocs() than a change of behavior that remove data where their used 
to be some


>  I just tried IPython 5.5.0

(You may want to update to 5.10, and do you have reason to still be on 5 and 
not 7 ?)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

help(1) as well as help(int) output the help for int. The only difference is 
that the former has the first line "Help on int object:", and the latter -- 
"Help on class int in module builtins:".

If IPython wants to output the help on the instance, it should change the 
implementation of `?` and `??`. It would be better if it correctly attribute 
the source of the docstring: the object itself, its class or its superclass. It 
was difficult to distinguish these cases before, now it is easier.

By the way, I just tried IPython 5.5.0 with Python 3.6.9, and it does not 
output the docstring either:

In [1]: a = 1

In [2]: a??
Type:int
String form: 1

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Guido van Rossum]

Guido van Rossum  added the comment:

Can you all please decide which issue to use?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Vedran Čačić]

Vedran Čačić  added the comment:

Of course, I thought that

2. inspect.getdoc() returns the object's own docstring.

means it returns the object's own docstring _if it has one_. If it doesn't, 
then it should still return the docstring of its class, of course!

I have no problem with the fact that help(1) gives the same help as help(int). 
Of course, same as with the above (subclasses), we might want to emphasize the 
fact that the help is for the class and not for the object itself, but just 
returning nothing is in no way an improvement.

Guido, load is probably from Pandas, df is a relatively standard abbreviation 
for "dataframe" (an instance of a class DataFrame, with many various methods), 
and obj?? in Jupyter opens the help for obj in a subwindow, enabling you to 
browse it and close when you're done with it.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Matthias Bussonnier]

Matthias Bussonnier  added the comment:

> can you clarify your example? What's load()? And what does df?? do?

It was vague on purpose, 

`load()` would be for example `load_csv()` from `pandas` that return a 
`pandas.DataFrame`. The point being that users typically won't really know the 
type of what they will get, they may get a DataFrame, but they may get a 
subclass if for example they use `dask` to do distributed computing. 

`?` or `??` is the way to get help in IPython/Jupyter, we try to pull as much 
information as we can and under the hood call `inspect.getdoc()`.

Assuming 

In [4]: class A:
   ...: "doc"

In [5]: class B(A):
   ...: pass

In [6]: b = B()

Python 3.8 gives:

In [9]: b?
Type:B
String form: <__main__.B object at 0x104be7d00>
Docstring:   
Class docstring: doc

Python 3.9 give

In [4]: b?
Type:B
String form: <__main__.B object at 0x10a0b7140>
Docstring:   


We do already pull docs from the superclass of the instance if no doc is found 
on current object, but now we get even less for the user. We could of course 
publish patch and walk the hierarchy ourselves, but it will require many users 
to upgrade (which you of course know they are not good at).

(Here i'm using `?`, `??` try to pull even more informations like the source, 
known subclasses and other stuff)


(Will try to get examples with actual code, but I haven't had time to build 
pandas or other scientific package on 3.9 yet).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Karthikeyan Singaravelan]

Karthikeyan Singaravelan  added the comment:

https://bugs.python.org/issue40587 has been opened. Copy paste of the report as 
below : 


In python 3.8:

```
>>> class A(object):
... """standard docstring"""
... pass
...
>>> import inspect
>>> inspect.getdoc(A())
'standard docstring'
```

In 3.9:

```
$ python
Python 3.9.0a6+ (heads/master:5b956ca42d, May 10 2020, 20:31:26)
[Clang 9.0.0 (clang-900.0.39.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> class A(object):
KeyboardInterrupt
>>> class A(object):
... """standard docstring"""
... pass
...
>>> import inspect
>>> inspect.getdoc(A())
>>>
```

--
nosy: +xtreak

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Guido van Rossum]

Guido van Rossum  added the comment:

Okay, let's reopen.

@Matthias, can you clarify your example? What's load()? And what does df?? do?

--
status: closed -> open

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Matthias Bussonnier]

Matthias Bussonnier  added the comment:

This is going to potentially break a lot of interactive usage in the Scientific 
ecosystem. 

A a lot of people are going to do:

df = load('my.csv')
df??

To ask for help and will get nothing. 

Even for subclass, I want to argue that a docstring for a superclass is better 
than no docstring. 


This will be devastating for many users.

--
nosy: +mbussonn

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:


New changeset 2fbc57af851814df567fb51054cb6f6a399f814a by Serhiy Storchaka in 
branch 'master':
bpo-40257: Tweak docstrings for special generic aliases. (GH-20022)
https://github.com/python/cpython/commit/2fbc57af851814df567fb51054cb6f6a399f814a


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Change by Serhiy Storchaka :


--
pull_requests: +19333
pull_request: https://github.com/python/cpython/pull/20022

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

Some work is still needed for HTML output. But this code is so different from 
the code for plain text output and so complicated that I was afraid to break 
something. I'll rewrite it in separate issue.

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:


New changeset 7e64414f57b70dc5bc0ab19a3162a0735f9bfabf by Serhiy Storchaka in 
branch 'master':
bpo-40257: Improve help for the typing module (GH-19546)
https://github.com/python/cpython/commit/7e64414f57b70dc5bc0ab19a3162a0735f9bfabf


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Change by Serhiy Storchaka :


--
pull_requests: +18892
pull_request: https://github.com/python/cpython/pull/19546

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:


New changeset fbf2786c4c89430e2067016603078cf3500cfe94 by Serhiy Storchaka in 
branch 'master':
bpo-40257: Output object's own docstring in pydoc (GH-19479)
https://github.com/python/cpython/commit/fbf2786c4c89430e2067016603078cf3500cfe94


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Vedran Čačić]

Vedran Čačić  added the comment:

Then I'm fine with it. Thanks.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

Yes, of course. And if it overrides some methods, but do not specify doctrings 
for new methods, they will be inherited from the parent class.

class A:
"""Base class"""
def foo(self): """Some docstring"""
def bar(self): """Other docstring"""

class B(A):
def foo(self): pass

help(B)

Help on class B in module __main__:

class B(A)
 |  Method resolution order:
 |  B
 |  A
 |  builtins.object
 |  
 |  Methods defined here:
 |  
 |  foo(self)
 |  Some docstring
 |  
 |  --
 |  Methods inherited from A:
 |  
 |  bar(self)
 |  Other docstring
 |  
...

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Vedran Čačić]

Vedran Čačić  added the comment:

Ok, I get what you're saying. But if someone writes

class B(A):
  # no docstring at all
  ...

help(B)

they'll still get other elements of current help? Particularly, "Methods 
inherited from A" (with their docstrings)?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

Inheritance of docstrings was added in issue15582. It works good for class 
members, but I now realized that doing it for class itself was a mistake. For 
example:

>>> import wave
>>> help(wave.Error)
Help on class Error in module wave:

class Error(builtins.Exception)
 |  Common base class for all non-exit exceptions.
 |  
 |  Method resolution order:
 |  Error
 |  builtins.Exception
 |  builtins.BaseException
 |  builtins.object
 |  
...

I fixed many similar issues by adding docstrings to classes, but there are even 
more exception classes and other classes in the stdlib for which help() gives 
incorrect description. I don't remember a single case when inheritance of the 
docstring was helpful.

Note that help() outputs the list of base class right after the docstring, so 
it is not hard to give an additional information, especially in interactive 
browser mode. If you want to inherit a docstring, you can do it explicitly:

__doc__ = BaseClass.__doc__

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Ivan Levkivskyi]

Ivan Levkivskyi  added the comment:

FWIW I like the idea. There are many objects in typing module that are not 
classes, it would be great to display docs for them.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Vedran Čačić]

Vedran Čačić  added the comment:

I don't agree with 1. I use that feature a lot, I write a base class which my 
students must subclass to their liking, but they still expect that 
help(TheirClass) will give them the documentation they need.

I agree that in _some_ cases it is not helpful (but even when the base is 
abstract, it might be helpful). How about: we keep the current behavior, but 
make it clear that the docstring applies to a superclass? It might be subtle, 
as just changing the first line of help() output (currently it says "Help on 
class Derived in module ...", change it to "Help on class Base in module ..."), 
or write a longer message such as "Documentation for Derived not found, showing 
the documentation for Base". But just removing it in all cases is really a 
wrong thing to do.

--
nosy: +veky

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Change by Serhiy Storchaka :


--
keywords: +patch
pull_requests: +18833
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/19479

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

New submission from Serhiy Storchaka :

Currently pydoc outputs __doc__ for classes, functions, methods, properties, 
etc (using inspect.getdoc()). If the object itself does not have non-empty 
__doc__, it searches non-empty __doc__ in the class parenthesis (if the object 
is a class) or in the corresponding overloaded members of the class to which 
the object (method, property, etc) belongs.

There are several problems with this.

1. Using the docstring of a parent class is misleading in most classes, 
especially if it is a base or abstract class (like object, Exception, Mapping).

2. If the object does not have the __doc__ attribute, it inherits it from its 
class, so inspect.getdoc(1) returns the same as inspect.getdoc(int).

3. If the object has own docstring, but is not a class or function, it will be 
output in the section DATA without a docstring.

The following PR fixes these issues.

1. Docstrings for classes are not inherited. It is better to not output a 
docstring than output the wrong one.

2. inspect.getdoc() returns the object's own docstring.

3. Docstrings are always output for object with a docstring. See for example 
help(typing).

In future issues I'll make help(typing) even more informative.

--
components: Library (Lib)
messages: 366220
nosy: gvanrossum, levkivskyi, ncoghlan, serhiy.storchaka, yselivanov
priority: normal
severity: normal
status: open
title: Improve the use of __doc__ in pydoc
type: enhancement
versions: Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com