msg143627 - (view) |
Author: Éric Araujo (eric.araujo) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
Date: 2014-04-16 21:16 |
Added some comments.
|
msg216597 - (view) |
Author: Yury Selivanov (yselivanov) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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: PCManticore (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) *  |
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) *  |
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) *  |
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) *  |
Date: 2015-02-01 02:12 |
Oops, seems I forgot to refresh my patch
|
msg235163 - (view) |
Author: Martin Panter (martin.panter) *  |
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) *  |
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) *  |
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) *  |
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) *  |
Date: 2015-03-08 21:31 |
I support Yury.
|
msg237600 - (view) |
Author: Berker Peksag (berker.peksag) *  |
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) *  |
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) *  |
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) *  |
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?
|
msg311417 - (view) |
Author: Stéphane Wirtel (matrixise) *  |
Date: 2018-02-01 10:23 |
I move this issue to 3.8
|
|
Date |
User |
Action |
Args |
2022-04-11 14:57:21 | admin | set | github: 57125 |
2018-02-01 10:23:40 | matrixise | set | messages:
+ msg311417 versions:
+ Python 3.8, - Python 3.6 |
2016-08-16 05:01:53 | bignose | set | messages:
+ msg272832 |
2015-03-09 16:36:36 | serhiy.storchaka | set | messages:
+ msg237674 |
2015-03-09 15:54:58 | matrixise | set | messages:
+ msg237668 |
2015-03-09 15:40:12 | yselivanov | set | messages:
+ msg237665 versions:
+ Python 3.6, - Python 3.5 |
2015-03-09 08:35:21 | serhiy.storchaka | set | messages:
+ msg237603 |
2015-03-09 07:31:45 | berker.peksag | set | messages:
+ msg237600 |
2015-03-08 21:31:35 | serhiy.storchaka | set | messages:
+ msg237571 |
2015-03-08 21:25:50 | martin.panter | set | messages:
+ msg237570 |
2015-03-08 15:05:26 | serhiy.storchaka | set | nosy:
+ serhiy.storchaka messages:
+ msg237538
|
2015-02-02 06:51:59 | matrixise | set | messages:
+ msg235224 |
2015-02-01 21:03:38 | martin.panter | set | messages:
+ msg235207 |
2015-02-01 18:51:05 | matrixise | set | messages:
+ msg235195 |
2015-02-01 12:14:23 | martin.panter | set | files:
+ issue12916-splitdoc-5.patch
messages:
+ msg235163 |
2015-02-01 02:12:16 | martin.panter | set | files:
- issue12916-splitdoc-4.patch |
2015-02-01 02:12:03 | martin.panter | set | files:
+ issue12916-splitdoc-4.patch
messages:
+ msg235140 |
2015-02-01 02:07:08 | martin.panter | set | files:
+ issue12916-splitdoc-4.patch
messages:
+ msg235139 |
2014-10-25 13:36:15 | matrixise | set | messages:
+ msg229997 |
2014-10-11 13:52:28 | matrixise | set | files:
+ issue12916-3.patch
messages:
+ msg229088 |
2014-09-20 05:11:00 | berker.peksag | set | messages:
+ msg227144 stage: commit review -> patch review |
2014-09-13 23:59:01 | martin.panter | set | messages:
+ msg226859 |
2014-06-24 20:00:05 | Claudiu.Popa | set | messages:
+ msg221483 stage: patch review -> commit review |
2014-05-08 09:48:48 | matrixise | set | messages:
+ msg218102 |
2014-04-29 15:34:42 | matrixise | set | files:
+ issue12916-2.patch
messages:
+ msg217524 |
2014-04-21 17:10:17 | matrixise | set | messages:
+ msg216953 |
2014-04-21 17:09:13 | r.david.murray | set | messages:
+ msg216952 |
2014-04-16 21:51:26 | matrixise | set | messages:
+ msg216608 |
2014-04-16 21:49:42 | eric.araujo | set | messages:
+ msg216607 |
2014-04-16 21:48:27 | matrixise | set | messages:
+ msg216606 |
2014-04-16 21:46:44 | yselivanov | set | messages:
+ msg216605 |
2014-04-16 21:40:54 | matrixise | set | messages:
+ msg216604 |
2014-04-16 21:40:13 | yselivanov | set | messages:
+ msg216602 |
2014-04-16 21:37:31 | yselivanov | set | messages:
+ msg216601 |
2014-04-16 21:36:35 | matrixise | set | messages:
+ msg216600 |
2014-04-16 21:28:27 | matrixise | set | messages:
+ msg216598 |
2014-04-16 21:24:55 | yselivanov | set | messages:
+ msg216597 |
2014-04-16 21:16:26 | eric.araujo | set | messages:
+ msg216594 stage: needs patch -> patch review |
2014-04-16 16:09:59 | yselivanov | set | messages:
+ msg216486 |
2014-04-16 14:11:07 | eric.snow | set | nosy:
+ eric.snow messages:
+ msg216470
|
2014-04-16 14:07:27 | r.david.murray | set | messages:
+ msg216469 |
2014-04-15 20:09:25 | yselivanov | set | messages:
+ msg216374 |
2014-04-15 19:31:10 | matrixise | set | messages:
+ msg216368 |
2014-04-15 01:50:12 | r.david.murray | set | messages:
+ msg216269 |
2014-04-14 22:31:52 | matrixise | set | messages:
+ msg216240 |
2014-04-14 22:25:27 | yselivanov | set | messages:
+ msg216238 |
2014-04-14 22:06:13 | r.david.murray | set | nosy:
+ r.david.murray messages:
+ msg216231
|
2014-04-14 21:56:10 | matrixise | set | files:
+ issue12916_1.patch
nosy:
+ matrixise messages:
+ msg216229
keywords:
+ patch |
2014-02-10 22:55:08 | martin.panter | set | nosy:
+ martin.panter
|
2014-01-29 06:44:57 | Claudiu.Popa | set | nosy:
+ Claudiu.Popa
|
2014-01-29 00:16:15 | yselivanov | set | nosy:
+ yselivanov
|
2014-01-29 00:16:11 | yselivanov | set | versions:
+ Python 3.5, - Python 3.4 |
2013-09-08 13:00:14 | bignose | set | nosy:
+ bignose
|
2013-07-13 09:23:11 | berker.peksag | set | nosy:
+ berker.peksag stage: needs patch
versions:
+ Python 3.4, - Python 3.3 |
2013-07-12 06:34:38 | rhettinger | set | assignee: rhettinger -> messages:
+ msg192925 |
2011-09-11 08:32:01 | rhettinger | set | assignee: rhettinger
nosy:
+ rhettinger |
2011-09-06 16:32:26 | eric.araujo | create | |