[issue12154] PyDoc Partial Functions

[Karthikeyan Singaravelan]

Karthikeyan Singaravelan  added the comment:

Adding my analysis here which is also at related issue : issue30129. On the 
attached program written by @skip.montanaro both c.sum and Child.sum return 
None for inspect.getdocs thus docstrings in pydoc are empty which can be fixed 
in both functools and inspect module as below : 

1. When we do inspect.getdoc(c.sum) where c is a partialmethod it looks for 
obj.__doc__ (c.sum.__doc__) returning partialmethod.__doc__ ("new function with 
partial...") instead of checking if c.sum is a partial method and  returning 
obj.func.__doc__ which contains the relevant doc ("sum doc"). Thus getdoc needs 
to check before trying for obj.__doc__ if the obj is a partialmethod or partial 
object thus returning the original function object.

2. When we do inspect.getdoc(Child.sum) it looks for obj.__doc__ 
(Child.sum.__doc__) and since Child.sum is a partialmethod which has __get__ 
overridden it calls _make_unbound_method that returns a _method object with no 
doc and thus returning None. partialmethod object copies objects from the given 
function at [0] and the actual object is returned at [1] . Here self.func has 
the original function in this case Base.sum and _method._partialmethod has 
reference to Base.sum which contains the relevant docs but _method itself has 
no docs thus pydoc doesn't get any docs. So we can set _method.__doc__ = 
self.func.__doc__ and getdoc can pick up the docs.

[0] 
https://github.com/python/cpython/blob/f1b9ad3d38c11676b45edcbf2369239bae436e56/Lib/functools.py#L368
[1] 
https://github.com/python/cpython/blob/f1b9ad3d38c11676b45edcbf2369239bae436e56/Lib/functools.py#L401

Before patch partialmethod.__doc__ : 

$ ./python.exe
>>> import functools, inspect
>>> inspect.getdoc(functools.partial(int, base=2))
'partial(func, *args, **keywords) - new function with partial application\nof 
the given arguments and keywords.'

After patch returns int.__doc__ : 

./python.exe
>>> import functools, inspect
>>> inspect.getdoc(functools.partial(int, base=2))
"int([x]) -> integer\nint(x, base=10) -> integer\n\nConvert a number or string 
to an integer ..." # Trimmed

# Patch

diff --git a/Lib/functools.py b/Lib/functools.py
index ab7d71e126..751f67fcd0 100644
--- a/Lib/functools.py
+++ b/Lib/functools.py
@@ -398,6 +398,7 @@ class partialmethod(object):
 return self.func(*call_args, **call_keywords)
 _method.__isabstractmethod__ = self.__isabstractmethod__
 _method._partialmethod = self
+_method.__doc__ = self.func.__doc__ or self.__doc__
 return _method

 def __get__(self, obj, cls):
diff --git a/Lib/inspect.py b/Lib/inspect.py
index b8a142232b..2c796546b2 100644
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -600,6 +600,9 @@ def getdoc(object):
 All tabs are expanded to spaces.  To clean up docstrings that are
 indented to line up with blocks of code, any whitespace than can be
 uniformly removed from the second line onwards is removed."""
+if isinstance(object, (functools.partialmethod, functools.partial)):
+return object.func.__doc__
+
 try:
 doc = object.__doc__
 except AttributeError:

--
nosy: +xtreak
Added file: https://bugs.python.org/file47910/bpo30129.py

___
Python tracker 

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

[issue12154] PyDoc Partial Functions

[Aaron Hall]

Aaron Hall  added the comment:

Should pydoc treat a partial object like a function?

Should a partial be an instance of a function?

Should we be able to add all the nice things that functions have to it?

If we want that, should we simply instantiate a function the normal way, with a 
new function definition? That is, instead of this:

>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'convert base 2 string to int'

do this:

def basetwo(string:str) -> int:
'convert base 2 string to int'
return int(string, base=2)

Otherwise, either the partial definition or pydoc needs some work.

(Cheers and bump!)

--

___
Python tracker 

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

[issue12154] PyDoc Partial Functions

[Aaron Hall]

Aaron Hall added the comment:

It seems that this issue is still properly open. (Another open issue seems be 
related: http://bugs.python.org/issue30129)

In the docs on partial, we have:

>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'convert base 2 string to int'

But the help function doesn't find that __doc__:

>>> help(basetwo)
class partial(builtins.object)
 |  partial(func, *args, **keywords) - new function with partial application
...

Perhaps this could be solved by having PyDoc check for isinstance of a Callable 
or making partial an instance of a Function?

>>> type(basetwo)

>>> basetwo.__dict__
{'__doc__': 'convert base 2 string to int'}
>>> type(basetwo)

>>> isinstance(basetwo, partial)
True
>>> from types import FunctionType; from collections import Callable
>>> isinstance(basetwo, FunctionType)
False
>>> isinstance(basetwo, Callable)
True

The partial repr seems to get us close:

>>> repr(basetwo)
"functools.partial(, base=2)"

I haven't dug much further into this, but I'm interested in doing the work to 
finish it, and I don't think the patch submitted 6 years ago quite gets us 
there. Any other thoughts before I decide to give it a go?

--
nosy: +Aaron Hall
versions: +Python 3.7 -Python 3.3

___
Python tracker 

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

[issue12154] PyDoc Partial Functions

[Phil Connell]

Changes by Phil Connell pconn...@gmail.com:


--
nosy: +pconnell

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

[issue12154] PyDoc Partial Functions

[Éric Araujo]

Éric Araujo mer...@netwok.org added the comment:

This section should help: 
http://docs.python.org/dev/library/inspect#classes-and-functions

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12154] PyDoc Partial Functions

[JJeffries]

JJeffries jamesjeffri...@gmail.com added the comment:

If it is changed to use inspect.getfullargspec is it still ok to use 
inspect.formatargspec? I cant work which values returned by getfullargspec need 
to go into which parameters for formatargspec.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12154] PyDoc Partial Functions

[JJeffries]

New submission from JJeffries jamesjeffri...@gmail.com:

PyDoc currently does not support partial functions. It currently just outputs 
the following, treating it as a data member instead of a function.

my_partial_function = functools.partial object

I think that if the __doc__ it should be treated as a function and the __doc__ 
read.

--
components: Library (Lib)
messages: 136596
nosy: JJeffries
priority: normal
severity: normal
status: open
title: PyDoc Partial Functions
type: feature request
versions: Python 2.7

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12154] PyDoc Partial Functions

[Éric Araujo]

Éric Araujo mer...@netwok.org added the comment:

Thanks for the report.  pydoc recently gained ad-hoc support for named tuples, 
so it could be improved to treat partial objects as functions.  Would you like 
to submit a patch?  If so, guidelines are on http://docs.python.org/devguide

--
nosy: +eric.araujo, rhettinger
versions: +Python 3.3 -Python 2.7

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12154] PyDoc Partial Functions

[JJeffries]

JJeffries jamesjeffri...@gmail.com added the comment:

I have written and tested a patch based on 2.7.1 src distribution (only src I 
have access to at work). I will get the latest code from the repository and 
test against that later.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12154] PyDoc Partial Functions

[Éric Araujo]

Éric Araujo mer...@netwok.org added the comment:

Thanks for your work!  Feel free to post the patch so that it won’t get lost.  
It may be that it ports cleanly or with trivial adaptations to 3.x, I can test 
and report if you don’t want to set up a full devel environment.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12154] PyDoc Partial Functions

[Ezio Melotti]

Changes by Ezio Melotti ezio.melo...@gmail.com:


--
nosy: +ezio.melotti

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12154] PyDoc Partial Functions

[JJeffries]

JJeffries jamesjeffri...@gmail.com added the comment:

Tested this on 2.7.1. currently only covers the HTMLDoc class. The TextDoc 
class will also need updating with the docpartialfunc method.

--
keywords: +patch
Added file: http://bugs.python.org/file22086/partial.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue12154
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com