classification
Title: Add inspect.splitdoc
Type: enhancement Stage: patch review
Components: Library (Lib) Versions: Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Claudiu.Popa, berker.peksag, bignose, eric.araujo, eric.snow, martin.panter, matrixise, r.david.murray, rhettinger, serhiy.storchaka, yselivanov
Priority: normal Keywords: patch

Created on 2011-09-06 16:32 by eric.araujo, last changed 2016-08-16 05:01 by bignose.

Files
File name Uploaded Description Edit
issue12916_1.patch matrixise, 2014-04-14 21:56 review
issue12916-2.patch matrixise, 2014-04-29 15:34 review
issue12916-3.patch matrixise, 2014-10-11 13:52
issue12916-splitdoc-4.patch martin.panter, 2015-02-01 02:12 Now accepts None review
issue12916-splitdoc-5.patch martin.panter, 2015-02-01 12:14 review
Messages (47)
msg143627 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-06 16:32
splitdoc is a hidden gem in pydoc: it’s a little helper to implement docstring splitting as documented in the docstrings PEPs.  It is not a one-liner, so I think there is value in making it public in the inspect module.
msg192925 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-07-12 06:34
Unassigning.  I don't recall what I intended to do to further this along.
msg216229 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-14 21:56
I move the pydoc.splitdoc function to the inspect module.
Update the documentation.
Add a unittest for this new function.

I can provide an other patch for the backward-compatiblity if this function is used by an other module than pydoc.
msg216231 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-04-14 22:06
The patch looks good, but 'splitdoc' needs to remain a valid name for the function in the pydoc namespace.  You could just add 'splitdoc = inspect.splitdoc' after the import statements.  (The reason it needs to remain valid is for backward compatibility...there may be people who discovered it and have been importing it from pydoc.)
msg216238 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-04-14 22:25
I don't like this idea. inspect module is about introspection, and not about interpreting its results. I'd keep this function in pydoc and document it if there is noticeable demand for it.
msg216240 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-14 22:31
Yury and David, please, can you discuss about this point, or just close this ticket if this one is useless.

Thank you
msg216269 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-04-15 01:50
The precedent has already been set by the 'cleandoc' function, I think.  This one seems to go right along with that one.
msg216368 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-15 19:31
Yury, what's your feedback about this point?

Thanks
msg216374 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-04-15 20:09
David:

> The precedent has already been set by the 'cleandoc' function, I think.  This one seems to go right along with that one.

What do you think if we keep the function in pydoc module, but document it and make it public?  I agree, that there is a precedent of having non-introspection APIs in inspect, but I'd still like to keep it minimal.  Having this function in pydoc also makes sense, as it's more about python docstring convention, than introspection (cleandoc() is used by getdoc(), which is why it is in inspect after all)
msg216469 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-04-16 14:07
Well, perhaps inspect needs a get_doc_synopsis method :)

Actually, I'm not sure that should be a smiley.

I don't really have a strong opinion on this myself (say I'm +0 for inspect), so I asked a couple other core devs here at the sprint (Eric Smith and Eric Snow), and they both thought it should be in inspect rather than pydoc.  (Eric's Snow reason is that pydoc is not really a user facing library (actually what he said is "it's a mess"), and both thought it was more appropriate for inspect anyway).
msg216470 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2014-04-16 14:11
I agree with Éric that exposing splidoc publicly in the inspect module is the right thing.  inspect already has other similar functions.  If it doesn't land in inspect then the only other place that makes real sense to me would be a new module (docstring?).  However, that seems like overkill to me.

Furthermore, pydoc doesn't seem like a good place to expose the function (or perhaps any function <wink>).  It isn't a module relating explicitly to docstrings so much as to exposing API documentation.  The use of splitdoc there is an implementation detail while splitdoc itself is generally useful.  That said, I would still expect splitdoc to be exposed in pydoc for backward compatibility (via "from inspect import splitdoc").
msg216486 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-04-16 16:09
OK, since it's two-and-a-half votes against one, let's do this. I'll do the final review of the patch and commit it.
msg216594 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-04-16 21:16
Added some comments.
msg216597 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-04-16 21:24
The current patch proposes to add inspect.splitdoc(obj), instead of pydoc.splitdoc(doc).  The former takes an object, extracts documentation out of it, and returns a tuple.  The latter, just splits the passed doc string.

If you want this function in inspect, we need to find a better name for it, or don't make it to receive an object.
msg216598 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-16 21:28
On 16 Apr 2014, at 17:24, Yury Selivanov wrote:

> Yury Selivanov added the comment:
>
> The current patch proposes to add inspect.splitdoc(obj), instead of 
> pydoc.splitdoc(doc).  The former takes an object, extracts 
> documentation out of it, and returns a tuple.  The latter, just splits 
> the passed doc string.
>
> If you want this function in inspect, we need to find a better name 
> for it, or don't make it to receive an object.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue12916>
> _______________________________________

In the inspect module, I think all the functions take a object and not a 
string, it's the reason why I included the code of pydoc.getdoc() into 
inspect.splitdoc().

One point, the former ( pydoc.splitdoc() ) takes a string, and returns a 
tuple. it's not the case with the new version.
msg216600 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-16 21:36
Yury,

An other point, as you proposed, I will check the version of Python in 
an unit test.

But is there a good practice?
Here is my way to check that:

Example from my patch for the issue with inspect.getfullargspec()

+        getfullargspec = getattr(inspect, 'getfullargspec', None)
+        if getfullargspec and sys.version_info >= (3, 7):
+            self.fail("inspect.getfullargspec() is deprecated since 
3.5, "
+                      "you must to remove it in 3.7")

Are you agree with that, or there is a good way for this kind of 
improvement?

Thank you so much,

Stephane
msg216601 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-04-16 21:37
> In the inspect module, I think all the functions take a object and not a 
string, it's the reason why I included the code of pydoc.getdoc() into 
inspect.splitdoc().

I understand. But you also do inspect.getdoc or inspect.getcomments, which I don't really like.  What's the point of having getcomments there?  Are comments considered docstrings?  If not, then why is the method called splitdocs?

Don't get me wrong, I'm not trying to pushback on the idea (since everybody is agreeing to have it), I just want the naming and behaviour be consistent.
msg216602 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-04-16 21:40
> Are you agree with that, or there is a good way for this kind of 
improvement?

Having a unittest to check if a deprecated functionality is removed in the future versions was Brett's idea, and I like it. So I think it's good to do the same here.  Your way of doing this is fine.
msg216604 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-16 21:40
Totally agree with you,

I want to learn how to contribute to cpython and there is a learning 
curve and it's normal.

So, if you think we need to change the names or the signature of the 
function, I can work on this issue.
msg216605 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-04-16 21:46
I'd keep the name ("splitdoc"), and let it receive a string.  But let's hear what Eric & David think about it.
msg216606 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-16 21:48
Ok, I will work on this bug after the feedback of Eric and David.

Thanks for your time.
--
Stéphane Wirtel - http://wirtel.be - @matrixise
msg216607 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-04-16 21:49
> I'd keep the name ("splitdoc"), and let it receive a string.

Yes please.
msg216608 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-16 21:51
And it takes a string or an object?
msg216952 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-04-21 17:09
It should receive a string.  This is parallel to cleandoc, and I think splitdoc should go in the documentation right after cleandoc.
msg216953 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-21 17:10
I will fix this issue asap, but I was too tired with the travel to Belgium.

Hope to propose patch during this week.
msg217524 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-04-29 15:34
Hi all,

Here is a new version of the patch, please, keep me informed and I think I have to modify some parts, but give me your feedback.

Thanks
msg218102 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-05-08 09:48
Hi all,

No news about this issue,

Do you have time for a feedback?

Thanks
msg221483 - (view) Author: Claudiu Popa (Claudiu.Popa) * Date: 2014-06-24 20:00
There's a small typo in your patch, strign instead of string. Otherwise, looks good to me.
msg226859 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2014-09-13 23:59
Although it is not documented, inspect.getdoc() may return None instead of a documentation string. In patch 2, inspect.splitdoc() only accepts a string; perhaps it should also accept None? Otherwise you might have to use it like this:

[summary, body] = splitdoc(getdoc(api) or "")
msg227144 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-09-20 05:11
I left a couple of comments on Rietveld.
msg229088 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-10-11 13:52
Hi all,

Here is the last version of this patch for a review, the tests are ok.

Thank you in advance for the time.

Stephane
msg229997 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2014-10-25 13:36
@berker.peksag Could you review the last patch? and keep me informed?

Thanks,
msg235139 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-01 02:07
Here is a 4th patch that allows None as input. Other changes:

* Document and test getdoc() returning None
* Limited the splitting and re-joining dance
* Document when the synopsis and body strings are empty
* More test cases

I left the pydoc test there, though I don’t see a big need for this test. It is no problem if the deprecated function remains in version 3.7.
msg235140 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-01 02:12
Oops, seems I forgot to refresh my patch
msg235163 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-01 12:14
Uploading issue12916-splitdoc-5.patch:

* Documented TypeError
* Added stacklevel=2 to warning
* Test improvements
* Dropped the test for pydoc.splitdoc() removal
msg235195 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2015-02-01 18:51
Hi Martin, you reused my own patch for this issue?
msg235207 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-01 21:03
Yes, this is based on your patch, Stéphane. On top of it I added support for splitdoc(None), and made the other changes in the bullet points.
msg235224 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2015-02-02 06:51
On 1 Feb 2015, at 22:03, Martin Panter wrote:

> Martin Panter added the comment:
>
> Yes, this is based on your patch, Stéphane. On top of it I added 
> support for splitdoc(None), and made the other changes in the bullet 
> points.

Great good news.

Hope these patches will be accepted.
msg237538 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-08 15:05
I doubt that inspect is better place for splitdoc() than pydoc. So count my voice against moving splitdoc().
msg237570 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-03-08 21:25
Serhiy, would you be in favour of making it public in the pydoc module, as originally suggested by Yury in <https://bugs.python.org/issue12916#msg216238>, or some other module, or are you saying to reject this completely?
msg237571 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-08 21:31
I support Yury.
msg237600 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-03-09 07:31
pydoc doesn't have public API other than its CLI and the help() function. I'd cleanup or even rewrite pydoc before declare anything public in it. On the other hand, there are already functions related to splitdoc() in the inspect module: https://docs.python.org/3/library/inspect.html#retrieving-source-code See also issue 18956.

There is no rush to make splitdoc() public. We can improve pydoc in 3.5 and 3.6 timeline and then decide what's should be part of the public API.
msg237603 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-09 08:35
My opposition against moving splitdoc() to the inspect module is not strict and I don't want to fight for it. In an case two-and-a-half votes are larger than one-and-a-half.

When you move splitdoc(), you should get rid of the use pydoc.splitdoc() in the stdlib and add DeprecatedWarning assertion to the test of pydoc.splitdoc(). The existence of pydoc.splitdoc() test is an argument to keep splitdoc() in the pydoc module.
msg237665 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2015-03-09 15:40
Berker, I agree. Let's wait till 3.6.

I still don't like having this function in the inspect module, and I still don't understand why it should be there.
msg237668 - (view) Author: Stéphane Wirtel (matrixise) * Date: 2015-03-09 15:54
Ok, so in this case, you are right to move this issue to the Python 3.6 
version, and it's too late for 3.5

Thank you for your help and feedbacks.

Stephane
msg237674 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-09 16:36
It's not too late for 3.5. Just there is no consensus.
msg272832 - (view) Author: Ben Finney (bignose) Date: 2016-08-16 05:01
Am I right that this:

> pydoc doesn't have public API other than its CLI and the help() function.
> […] On the other hand, there are already functions related to splitdoc()
> in the inspect module […].

> There is no rush to make splitdoc() public. We can improve pydoc in 3.5
> and 3.6 timeline and then decide what's should be part of the public API.

represents the latest on this issue?

We now have the alpha phase of Python 3.6. Can we get a resolution that makes ‘splitdoc’ public somewhere?
History
Date User Action Args
2016-08-16 05:01:53bignosesetmessages: + msg272832
2015-03-09 16:36:36serhiy.storchakasetmessages: + msg237674
2015-03-09 15:54:58matrixisesetmessages: + msg237668
2015-03-09 15:40:12yselivanovsetmessages: + msg237665
versions: + Python 3.6, - Python 3.5
2015-03-09 08:35:21serhiy.storchakasetmessages: + msg237603
2015-03-09 07:31:45berker.peksagsetmessages: + msg237600
2015-03-08 21:31:35serhiy.storchakasetmessages: + msg237571
2015-03-08 21:25:50martin.pantersetmessages: + msg237570
2015-03-08 15:05:26serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg237538
2015-02-02 06:51:59matrixisesetmessages: + msg235224
2015-02-01 21:03:38martin.pantersetmessages: + msg235207
2015-02-01 18:51:05matrixisesetmessages: + msg235195
2015-02-01 12:14:23martin.pantersetfiles: + issue12916-splitdoc-5.patch

messages: + msg235163
2015-02-01 02:12:16martin.pantersetfiles: - issue12916-splitdoc-4.patch
2015-02-01 02:12:03martin.pantersetfiles: + issue12916-splitdoc-4.patch

messages: + msg235140
2015-02-01 02:07:08martin.pantersetfiles: + issue12916-splitdoc-4.patch

messages: + msg235139
2014-10-25 13:36:15matrixisesetmessages: + msg229997
2014-10-11 13:52:28matrixisesetfiles: + issue12916-3.patch

messages: + msg229088
2014-09-20 05:11:00berker.peksagsetmessages: + msg227144
stage: commit review -> patch review
2014-09-13 23:59:01martin.pantersetmessages: + msg226859
2014-06-24 20:00:05Claudiu.Popasetmessages: + msg221483
stage: patch review -> commit review
2014-05-08 09:48:48matrixisesetmessages: + msg218102
2014-04-29 15:34:42matrixisesetfiles: + issue12916-2.patch

messages: + msg217524
2014-04-21 17:10:17matrixisesetmessages: + msg216953
2014-04-21 17:09:13r.david.murraysetmessages: + msg216952
2014-04-16 21:51:26matrixisesetmessages: + msg216608
2014-04-16 21:49:42eric.araujosetmessages: + msg216607
2014-04-16 21:48:27matrixisesetmessages: + msg216606
2014-04-16 21:46:44yselivanovsetmessages: + msg216605
2014-04-16 21:40:54matrixisesetmessages: + msg216604
2014-04-16 21:40:13yselivanovsetmessages: + msg216602
2014-04-16 21:37:31yselivanovsetmessages: + msg216601
2014-04-16 21:36:35matrixisesetmessages: + msg216600
2014-04-16 21:28:27matrixisesetmessages: + msg216598
2014-04-16 21:24:55yselivanovsetmessages: + msg216597
2014-04-16 21:16:26eric.araujosetmessages: + msg216594
stage: needs patch -> patch review
2014-04-16 16:09:59yselivanovsetmessages: + msg216486
2014-04-16 14:11:07eric.snowsetnosy: + eric.snow
messages: + msg216470
2014-04-16 14:07:27r.david.murraysetmessages: + msg216469
2014-04-15 20:09:25yselivanovsetmessages: + msg216374
2014-04-15 19:31:10matrixisesetmessages: + msg216368
2014-04-15 01:50:12r.david.murraysetmessages: + msg216269
2014-04-14 22:31:52matrixisesetmessages: + msg216240
2014-04-14 22:25:27yselivanovsetmessages: + msg216238
2014-04-14 22:06:13r.david.murraysetnosy: + r.david.murray
messages: + msg216231
2014-04-14 21:56:10matrixisesetfiles: + issue12916_1.patch

nosy: + matrixise
messages: + msg216229

keywords: + patch
2014-02-10 22:55:08martin.pantersetnosy: + martin.panter
2014-01-29 06:44:57Claudiu.Popasetnosy: + Claudiu.Popa
2014-01-29 00:16:15yselivanovsetnosy: + yselivanov
2014-01-29 00:16:11yselivanovsetversions: + Python 3.5, - Python 3.4
2013-09-08 13:00:14bignosesetnosy: + bignose
2013-07-13 09:23:11berker.peksagsetnosy: + berker.peksag
stage: needs patch

versions: + Python 3.4, - Python 3.3
2013-07-12 06:34:38rhettingersetassignee: rhettinger ->
messages: + msg192925
2011-09-11 08:32:01rhettingersetassignee: rhettinger

nosy: + rhettinger
2011-09-06 16:32:26eric.araujocreate