[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: I move this issue to 3.8 -- versions: +Python 3.8 -Python 3.6 ___ Python tracker ___

[issue12916] Add inspect.splitdoc

Ben Finney added the comment: 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

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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 -- ___ Python tracker rep...@bugs.python.org

[issue12916] Add inspect.splitdoc

Yury Selivanov added the comment: 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. -- versions: +Python 3.6 -Python 3.5 ___ Python tracker

[issue12916] Add inspect.splitdoc

Serhiy Storchaka added the comment: It's not too late for 3.5. Just there is no consensus. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Serhiy Storchaka added the comment: 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

[issue12916] Add inspect.splitdoc

Berker Peksag added the comment: 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:

[issue12916] Add inspect.splitdoc

Serhiy Storchaka added the comment: I support Yury. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___ ___ Python-bugs-list mailing list

[issue12916] Add inspect.splitdoc

Martin Panter added the comment: 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? --

[issue12916] Add inspect.splitdoc

Serhiy Storchaka added the comment: I doubt that inspect is better place for splitdoc() than pydoc. So count my voice against moving splitdoc(). -- nosy: +serhiy.storchaka ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Martin Panter added the comment: Uploading issue12916-splitdoc-5.patch: * Documented TypeError * Added stacklevel=2 to warning * Test improvements * Dropped the test for pydoc.splitdoc() removal -- Added file: http://bugs.python.org/file37956/issue12916-splitdoc-5.patch

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: Hi Martin, you reused my own patch for this issue? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

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. -- ___ Python tracker rep...@bugs.python.org

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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

[issue12916] Add inspect.splitdoc

Martin Panter added the comment: 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

[issue12916] Add inspect.splitdoc

Changes by Martin Panter vadmium...@gmail.com: Removed file: http://bugs.python.org/file37948/issue12916-splitdoc-4.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Martin Panter added the comment: Oops, seems I forgot to refresh my patch -- Added file: http://bugs.python.org/file37949/issue12916-splitdoc-4.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: @berker.peksag Could you review the last patch? and keep me informed? Thanks, -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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 -- Added file: http://bugs.python.org/file36880/issue12916-3.patch ___ Python tracker

[issue12916] Add inspect.splitdoc

Berker Peksag added the comment: I left a couple of comments on Rietveld. -- stage: commit review - patch review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Martin Panter added the comment: 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] =

[issue12916] Add inspect.splitdoc

Claudiu Popa added the comment: There's a small typo in your patch, strign instead of string. Otherwise, looks good to me. -- stage: patch review - commit review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: Hi all, No news about this issue, Do you have time for a feedback? Thanks -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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 -- Added file: http://bugs.python.org/file35093/issue12916-2.patch

[issue12916] Add inspect.splitdoc

R. David Murray added the comment: It should receive a string. This is parallel to cleandoc, and I think splitdoc should go in the documentation right after cleandoc. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: I will fix this issue asap, but I was too tired with the travel to Belgium. Hope to propose patch during this week. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

R. David Murray added the comment: 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

[issue12916] Add inspect.splitdoc

Eric Snow added the comment: 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?).

[issue12916] Add inspect.splitdoc

Yury Selivanov added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Éric Araujo added the comment: Added some comments. -- stage: needs patch - patch review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

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,

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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 =

[issue12916] Add inspect.splitdoc

Yury Selivanov added the comment: 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

[issue12916] Add inspect.splitdoc

Yury Selivanov added the comment: 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

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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. --

[issue12916] Add inspect.splitdoc

Yury Selivanov added the comment: I'd keep the name (splitdoc), and let it receive a string. But let's hear what Eric David think about it. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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 -- ___ Python tracker rep...@bugs.python.org

[issue12916] Add inspect.splitdoc

Éric Araujo added the comment: I'd keep the name (splitdoc), and let it receive a string. Yes please. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: And it takes a string or an object? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___ ___

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: Yury, what's your feedback about this point? Thanks -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Yury Selivanov added the comment: 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

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: 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. -- keywords:

[issue12916] Add inspect.splitdoc

R. David Murray added the comment: 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

[issue12916] Add inspect.splitdoc

Yury Selivanov added the comment: 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. -- ___ Python tracker

[issue12916] Add inspect.splitdoc

Stéphane Wirtel added the comment: Yury and David, please, can you discuss about this point, or just close this ticket if this one is useless. Thank you -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

R. David Murray added the comment: The precedent has already been set by the 'cleandoc' function, I think. This one seems to go right along with that one. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Changes by Martin Panter vadmium...@gmail.com: -- nosy: +vadmium ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___ ___ Python-bugs-list

[issue12916] Add inspect.splitdoc

Changes by Yury Selivanov yselivanov...@gmail.com: -- nosy: +yselivanov ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___ ___

[issue12916] Add inspect.splitdoc

Changes by Yury Selivanov yselivanov...@gmail.com: -- versions: +Python 3.5 -Python 3.4 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Changes by Claudiu.Popa pcmantic...@gmail.com: -- nosy: +Claudiu.Popa ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___ ___ Python-bugs-list

[issue12916] Add inspect.splitdoc

Changes by Ben Finney ben+pyt...@benfinney.id.au: -- nosy: +bignose ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___ ___ Python-bugs-list

[issue12916] Add inspect.splitdoc

Changes by Berker Peksag berker.pek...@gmail.com: -- nosy: +berker.peksag stage: - needs patch versions: +Python 3.4 -Python 3.3 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

Raymond Hettinger added the comment: Unassigning. I don't recall what I intended to do to further this along. -- assignee: rhettinger - ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916

[issue12916] Add inspect.splitdoc

Changes by Raymond Hettinger raymond.hettin...@gmail.com: -- assignee: - rhettinger nosy: +rhettinger ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12916 ___

[issue12916] Add inspect.splitdoc

New submission from Éric Araujo mer...@netwok.org: 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. -- components: