PyDoc Partial Functions

[295ddde5-6656-4074-bd20-8813caa7cc28]

BPO	12154
Nosy	@rhettinger, @ezio-melotti, @merwok, @phmc, @aaronchall, @tirkarthi
Files	partial.patch: Patch to include partial functions in PyDoc bpo30129.py

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['3.7', 'type-feature', 'library'] title = 'PyDoc Partial Functions' updated_at = user = 'https://bugs.python.org/JJeffries' ``` bugs.python.org fields: ```python activity = actor = 'xtreak' assignee = 'none' closed = False closed_date = None closer = None components = ['Library (Lib)'] creation = creator = 'JJeffries' dependencies = [] files = ['22086', '47910'] hgrepos = [] issue_num = 12154 keywords = ['patch'] message_count = 10.0 messages = ['136596', '136600', '136642', '136660', '136686', '136779', '136966', '301180', '317971', '329349'] nosy_count = 7.0 nosy_names = ['rhettinger', 'ezio.melotti', 'eric.araujo', 'JJeffries', 'pconnell', 'Aaron Hall', 'xtreak'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue12154' versions = ['Python 3.7'] ```

[295ddde5-6656-4074-bd20-8813caa7cc28]

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.

[merwok]

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

[295ddde5-6656-4074-bd20-8813caa7cc28]

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.

[merwok]

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.

[295ddde5-6656-4074-bd20-8813caa7cc28]

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

[295ddde5-6656-4074-bd20-8813caa7cc28]

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.

[merwok]

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

[affb16c2-6fdb-403f-b328-86b7e719c99e]

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)
<class 'functools.partial'>
>>> basetwo.__dict__
{'__doc__': 'convert base 2 string to int'}
>>> type(basetwo)
<class 'functools.partial'>
>>> 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(<class 'int'>, 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?

[affb16c2-6fdb-403f-b328-86b7e719c99e]

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!)

[tirkarthi]

Adding my analysis here which is also at related issue : bpo-30129. 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_unboundmethod 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: