Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Python: Dev

Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs.

 

 

Python dev RSS feed   Index | Next | Previous | View Threaded


ncoghlan at gmail

Jun 1, 2012, 5:42 PM

Post #1 of 8 (528 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs.

On Jun 2, 2012 6:21 AM, "r.david.murray" <python-checkins [at] python> wrote:
>
> http://hg.python.org/cpython/rev/24572015e24f
> changeset: 77288:24572015e24f
> branch: 3.2
> parent: 77285:bf6305bce3af
> user: R David Murray <rdmurray [at] bitdance>
> date: Fri Jun 01 16:19:36 2012 -0400
> summary:
> #14957: clarify splitlines docs.
>
> Initial patch by Michael Driscoll, I added the example.
>
> files:
> Doc/library/stdtypes.rst | 8 +++++++-
> 1 files changed, 7 insertions(+), 1 deletions(-)
>
>
> diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
> --- a/Doc/library/stdtypes.rst
> +++ b/Doc/library/stdtypes.rst
> @@ -1329,7 +1329,13 @@
>
> Return a list of the lines in the string, breaking at line boundaries.
Line
> breaks are not included in the resulting list unless *keepends* is
given and
> - true.
> + true. This method uses the universal newlines approach to splitting
lines.
> + Unlike :meth:`~str.split`, if the string ends with line boundary
characters
> + the returned list does ``not`` have an empty last element.
> +
> + For example, ``'ab c\n\nde fg\rkl\r\n'.splitlines()`` returns
> + ``['ab c', '', 'de fg', 'kl']``, while the same call with
``splinelines(True)``
> + returns ``['ab c\n', '\n, 'de fg\r', 'kl\r\n']``.

s/splinelines/splitlines/

Maybe also show what split() would do for that string?

>
>
> .. method:: str.startswith(prefix[, start[, end]])
>
> --
> Repository URL: http://hg.python.org/cpython
>
> _______________________________________________
> Python-checkins mailing list
> Python-checkins [at] python
> http://mail.python.org/mailman/listinfo/python-checkins
>


rdmurray at bitdance

Jun 1, 2012, 8:24 PM

Post #2 of 8 (500 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs. [In reply to]

On Sat, 02 Jun 2012 10:42:13 +1000, Nick Coghlan <ncoghlan [at] gmail> wrote:
> > + For example, ``'ab c\n\nde fg\rkl\r\n'.splitlines()`` returns
> > + ``['ab c', '', 'de fg', 'kl']``, while the same call with
> ``splinelines(True)``
> > + returns ``['ab c\n', '\n, 'de fg\r', 'kl\r\n']``.
>
> s/splinelines/splitlines/

Oops.

> Maybe also show what split() would do for that string?

I'd rather not, since the split examples are just above it in
the docs.

--David
_______________________________________________
Python-Dev mailing list
Python-Dev [at] python
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/list-python-dev%40lists.gossamer-threads.com


ncoghlan at gmail

Jun 1, 2012, 10:16 PM

Post #3 of 8 (483 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs. [In reply to]

On Sat, Jun 2, 2012 at 1:24 PM, R. David Murray <rdmurray [at] bitdance> wrote:
>> Maybe also show what split() would do for that string?
>
> I'd rather not, since the split examples are just above it in
> the docs.

Fair point - one of the downsides of reviewing a diff out of context :)

Cheers,
Nick.

--
Nick Coghlan | ncoghlan [at] gmail | Brisbane, Australia
_______________________________________________
Python-Dev mailing list
Python-Dev [at] python
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/list-python-dev%40lists.gossamer-threads.com


sam.partington at gmail

Jun 7, 2012, 3:08 AM

Post #4 of 8 (460 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs. [In reply to]

> On Jun 2, 2012 6:21 AM, "r.david.murray" <python-checkins [at] python> wrote:
>> + For example, ``'ab c\n\nde fg\rkl\r\n'.splitlines()`` returns
>> + ``['ab c', '', 'de fg', 'kl']``, while the same call with
>> ``splinelines(True)``
>> + returns ``['ab c\n', '\n, 'de fg\r', 'kl\r\n']``

Wouldn't that be better written as a doctest and so avoid any other typos?

Sam
_______________________________________________
Python-Dev mailing list
Python-Dev [at] python
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/list-python-dev%40lists.gossamer-threads.com


rdmurray at bitdance

Jun 7, 2012, 5:55 AM

Post #5 of 8 (454 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs. [In reply to]

On Thu, 07 Jun 2012 11:08:09 +0100, Sam Partington <sam.partington [at] gmail> wrote:
> > On Jun 2, 2012 6:21 AM, "r.david.murray" <python-checkins [at] python> wrote:
> >> +   For example, ``'ab c\n\nde fg\rkl\r\n'.splitlines()`` returns
> >> +   ``['ab c', '', 'de fg', 'kl']``, while the same call with
> >> ``splinelines(True)``
> >> +   returns ``['ab c\n', '\n, 'de fg\r', 'kl\r\n']``
>
> Wouldn't that be better written as a doctest and so avoid any other typos?

Possibly, except (1) I don't think we currently actually test the doctests
in the python docs and (2) I'm following the style of the surrounding text
(the split examples just above this are in the same inline style. Oh, and
(3) it would make the text longer, which could be considered a negative.

I have no objection myself to someone reformatting it, but if that is
done the whole chapter should be gone over and given a consistent style.

--David


tseaver at palladion

Jun 8, 2012, 4:20 AM

Post #6 of 8 (480 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs. [In reply to]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 06/07/2012 08:55 AM, R. David Murray wrote:
> On Thu, 07 Jun 2012 11:08:09 +0100, Sam Partington
> <sam.partington [at] gmail> wrote:

>> Wouldn't that be better written as a doctest and so avoid any other
>> typos?
>
> Possibly, except (1) I don't think we currently actually test the
> doctests in the python docs and

FWIW, I've had a lot of success lately with automating testing of doctest
snippets in Sphinx docs via::

$ /path/to/sphinx-build -b doctest \
-d docs/_build/doctrees docs docs/_build/doctest

(That was from non-Python-core packages where the convention is that the
Sphink docs are managed and built in the 'docs' subdirectory).


Tres.
- --
===================================================================
Tres Seaver +1 540-429-0999 tseaver [at] palladion
Palladion Software "Excellence by Design" http://palladion.com


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk/R4BAACgkQ+gerLs4ltQ426ACgzzr3WHWe8q/4QCdFJgOhYirU
9rAAoMcMZJ3ycPa6B0C4jqCihVdVY9f0
=rYxl
-----END PGP SIGNATURE-----

_______________________________________________
Python-Dev mailing list
Python-Dev [at] python
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/list-python-dev%40lists.gossamer-threads.com


rdmurray at bitdance

Jun 8, 2012, 10:08 AM

Post #7 of 8 (463 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs. [In reply to]

On Fri, 08 Jun 2012 07:20:55 -0400, Tres Seaver <tseaver [at] palladion> wrote:
> On 06/07/2012 08:55 AM, R. David Murray wrote:
> > On Thu, 07 Jun 2012 11:08:09 +0100, Sam Partington
> > <sam.partington [at] gmail> wrote:
>
> >> Wouldn't that be better written as a doctest and so avoid any other
> >> typos?
> >
> > Possibly, except (1) I don't think we currently actually test the
> > doctests in the python docs and
>
> FWIW, I've had a lot of success lately with automating testing of doctest
> snippets in Sphinx docs via::

Oh, the *mechanics* of running the doctests in the docs are not difficult,
'make doctest' in Doc works just fine (on Python2).

The are four issues: (1) we build the python3 docs using python2, so 'make
doctest' on python3 doesn't currently work, and (2) not all the doctest
snippets are valid doctests, (3) not all the code snippets that can
(and should) be validated are recognized as such by 'make doctest', and
(4) there is no buildbot-style automation for running the doc doctests.

(1) is the easiest one to fix.

--David

PS: A year or so ago I cleaned up the doctests for turtle and
multiprocessing, but I haven't re-run those tests since. I just did now:
multiprocessing still passes(*), and there is one failing turtle test.

The grand total on 2.7 is 1131 tests, 78 failures.

(*) If I remember correctly "cleaning up the doctests" in Multiprocessing
mostly meant making them not-doctests from 'make doctest's point of
view, and then hand validating them. But Multiprocessing is a bit of
a special case.
_______________________________________________
Python-Dev mailing list
Python-Dev [at] python
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/list-python-dev%40lists.gossamer-threads.com


ericsnowcurrently at gmail

Jun 8, 2012, 12:03 PM

Post #8 of 8 (454 views)
Permalink
Re: [Python-checkins] cpython (3.2): #14957: clarify splitlines docs. [In reply to]

On Fri, Jun 8, 2012 at 11:08 AM, R. David Murray <rdmurray [at] bitdance> wrote:
> The are four issues: (1) we build the python3 docs using python2, so 'make
> doctest' on python3 doesn't currently work

For reference: http://bugs.python.org/issue10224. Are there any others?

-eric
_______________________________________________
Python-Dev mailing list
Python-Dev [at] python
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/list-python-dev%40lists.gossamer-threads.com

Python dev RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.