bpo-30872: Update the curses docs to Python 3. #2620

serhiy-storchaka · 2017-07-07T15:15:45Z

https://bugs.python.org/issue30872

mention-bot · 2017-07-07T15:15:47Z

@serhiy-storchaka, thanks for your PR! By analyzing the history of the files in this pull request, we identified @ezio-melotti, @birkenfeld and @orsenthil to be potential reviewers.

mlouielu · 2017-07-13T09:44:22Z

Doc/library/curses.ascii.rst

@@ -176,7 +176,7 @@ C library:

   Checks for a non-ASCII character (ordinal values 0x80 and above).

-These functions accept either integers or strings; when the argument is a
+These functions accept either integers or single-character strings; when the argument is a


Should this be changed? It accept multi-character strings, too. Alought it will raise TypeError by ord.

Also, after this paragraph, it has written this Note that all these functions check ordinal bit values derived from the first character of the string you pass in.

Does single-character string as same as you mention in note? (it can be specified as a Unicode string or a byte string.). If yes, but these function can't accept byte string:

>>> curses.ascii.ascii(b'1') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python3.6/curses/ascii.py", line 75, in ascii return _ctoi(c) & 0x7f TypeError: unsupported operand type(s) for &: 'bytes' and 'int' >>> curses.ascii.ctrl(b'1') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python3.6/curses/ascii.py", line 81, in ctrl return _ctoi(c) & 0x1f TypeError: unsupported operand type(s) for &: 'bytes' and 'int'

Raising TypeError doesn't mean that the function accepts multi-character strings.

"string" means just string here. Although I think it is worth to add the support of bytes here, this PR changes only the documentation.

mlouielu · 2017-07-13T09:53:12Z

Doc/library/curses.rst

-   Return the current coordinates of the virtual screen cursor in y and x.  If
-   leaveok is currently true, then -1,-1 is returned.
+   Return the current coordinates of the virtual screen cursor as a tuple
+   ``(y, x)``.  If **leaveok** is currently true, then ``(-1, -1)`` is returned.


true should be cast to ``True``?

Probably it should be True. Even if the module isn't actually using booleans internally, conceptually it is; leaveok can really only have boolean values.

leaveok is a name of the window option. It is changed by the method window.leaveok(). How better to reword this?

vadmium · 2017-07-16T22:43:12Z

Doc/library/curses.rst

-   If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0,  allow only
-   7-bit chars.
+   If an argument is ``True``, allow 8-bit characters to be input.  If an
+   argument is ``False``,  allow only 7-bit chars.


the argument

vadmium · 2017-07-16T22:44:00Z

Doc/library/curses.rst

-   string is set to the value of cr. The effect is that the cursor is confined to
+   called.  The effect is that, during those calls, :envvar:`LINES` is set to ``1``; the
+   capabilities **clear**, **cup**, **cud**, **cud1**, **cuu1**, **cuu**, **vpa** are disabled; and the **home**
+   string is set to the value of **cr**. The effect is that the cursor is confined to


Double asterisks mark up as bold don’t they? Perhaps italics (single asterisks) would be more appropriate.

bitdancer

I checked, and we use "bytes object" 98 times in library docs, and "byte string" 42 times. So I think we are shifting to using "bytes object". I would like to see all the instances of "byte string" changed to "bytes object" here.

bitdancer · 2017-07-16T21:48:56Z

Doc/library/curses.ascii.rst

@@ -176,7 +176,7 @@ C library:

   Checks for a non-ASCII character (ordinal values 0x80 and above).

-These functions accept either integers or strings; when the argument is a
+These functions accept either integers or single-character strings; when the argument is a
 string, it is first converted using the built-in function :func:`ord`.

 Note that all these functions check ordinal bit values derived from the  first


"from the first character of the string you pass in" seems confusing, given that the string may only have one character. Perhaps change it to "from the character in the string you pass in". (I realize this is an "existing bug", but we might as well make it more precise while we are editing the rest).

Agree. Thank you for the suggestion.

The rest of the paragraph looks outdated too. Most functions was moved from the string module and become str methods. And they don't know about the character encoding because handle Unicode.

bitdancer · 2017-07-16T22:03:31Z

Doc/library/curses.rst

-   string is set to the value of cr. The effect is that the cursor is confined to
+   called.  The effect is that, during those calls, :envvar:`LINES` is set to ``1``; the
+   capabilities **clear**, **cup**, **cud**, **cud1**, **cuu1**, **cuu**, **vpa** are disabled; and the **home**
+   string is set to the value of **cr**. The effect is that the cursor is confined to


I haven't seen two asterisks used before. What convention does this follow? I'm thinking these should be single *s?

I wanted to distinguish them from other names. These names are not the names of arguments (which are rendered as italic). They are the names of terminal capabilities. If you prefer, I can change them to be rendered as fixed-width (``clear``), but not as italic.

Yes, I think that would be better.

bitdancer · 2017-07-16T22:09:08Z

Doc/library/curses.rst

-   Return the current coordinates of the virtual screen cursor in y and x.  If
-   leaveok is currently true, then -1,-1 is returned.
+   Return the current coordinates of the virtual screen cursor as a tuple
+   ``(y, x)``.  If **leaveok** is currently true, then ``(-1, -1)`` is returned.


Probably it should be True. Even if the module isn't actually using booleans internally, conceptually it is; leaveok can really only have boolean values.

bitdancer · 2017-07-16T22:16:12Z

Doc/library/curses.rst

-   If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0,  allow only
-   7-bit chars.
+   If an argument is ``True``, allow 8-bit characters to be input.  If an
+   argument is ``False``,  allow only 7-bit chars.


s/an argument/*flag*/

I unified all boolean argument names (now all are "flag"), but removed names from descriptions because actually the name is arbitrary. Since all these functions take a single argument, there is no need to name it.

With these reasons what is better, "the argument" or "*flag*"?

*flag*. Our documentation convention is that we refer to the arguments by the name given in the prototype, regardless of whether that is what is actually used in the code or not. It would be valid English to say "the argument", but I think consistency with the bulk of the docs is a good idea.

bitdancer · 2017-07-16T23:51:06Z

Doc/library/curses.rst

-   Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then
-   leaveok is set.
+   Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, then
+   **leaveok** is set.


I think this should be a link to the function, and it should probably say "set true".

If *y* and *x* are both ``-1``, then :meth:`~window.leaveok` set true.

Right?

"is set true". Sorry I didn't make that clear.

bitdancer · 2017-07-17T00:28:57Z

Doc/library/curses.rst


-   If called with *yes* equal to 1, :mod:`curses` will try and use hardware line
+   If called with an argument equal to ``True``, :mod:`curses` will try and use hardware line


s/an argument/*flag*/

bitdancer · 2017-07-17T00:29:18Z

Doc/library/curses.rst

   editing facilities. Otherwise, line insertion/deletion are disabled.


 .. method:: window.immedok(flag)

-   If *flag* is ``True``, any change in the window image automatically causes the
+   If an argument is ``True``, any change in the window image automatically causes the


revert this

bitdancer · 2017-07-17T00:29:46Z

Doc/library/curses.rst

-   If *yes* is 1, escape sequences generated by some keys (keypad,  function keys)
-   will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be
+   If an argument is ``True``, escape sequences generated by some keys (keypad,  function keys)
+   will be interpreted by :mod:`curses`. If an argument is ``False``, escape sequences will be


s/an argument/*flag*/

bitdancer · 2017-07-17T00:30:09Z

Doc/library/curses.rst


-   If *yes* is 1, cursor is left where it is on update, instead of being at "cursor
+   If an argument is ``True``, cursor is left where it is on update, instead of being at "cursor


s/an argument/*flag*/

Ok, I'm going to stop noting this every time, you get the idea :)

bitdancer · 2017-07-17T00:32:04Z

Doc/library/curses.rst

@@ -1202,7 +1209,7 @@ the following methods and attributes:

 .. method:: window.syncok(flag)

-   If called with *flag* set to ``True``, then :meth:`syncup` is called automatically
+   If called with ``True``, then :meth:`syncup` is called automatically


If *flag* is ``True``...

serhiy-storchaka · 2017-07-17T05:46:41Z

I intentionally used the term "byte string" for accenting that a bytes object is not just arbitrary couple of bits as in binary representation of floats or images, but mostly human-readable string. Do you think this makes sense?

bitdancer · 2017-07-17T17:37:08Z

I still prefer bytes object, but in this context it is not a strong preference. The "character string" idiom is also somewhat problematic, but I don't have a better solution to suggest.

vadmium · 2017-08-12T00:31:17Z

Doc/library/curses.rst

@@ -786,7 +787,7 @@ the following methods and attributes:
            window.chgat(y, x, num, attr)

   Set the attributes of *num* characters at the current cursor position, or at
-   position ``(y, x)`` if supplied. If no value of *num* is given or *num* = ``-1``,
+   position ``(y, x)`` if supplied. If no value of *num* is given or ``-1`` is given,


Why this change? I think the original read better. If you want to use words rather than code, you could write “or num is −1”, or “num is negative one”. Or perhaps “If num is not given or is −1”.

It was changed on the request by @bitdancer.

I don't particularly remember this, but I suspect my logic was that we don't usually write "arg = " when describing argument values, since that looks like code and thus is potentially confusing in this context. I like the "if num is not given or is -1" phrasing. Oddly enough, I think it might read better in the form "if num is -1 or is not given", but either one is fine with me.

Either is fine by me

vadmium · 2017-08-12T01:04:15Z

Doc/library/curses.rst

-   range: function keys, keypad keys and so on return numbers higher than 256. In
-   no-delay mode, ``-1`` is returned if there is no input, else the function waits
-   until a key is pressed.
+   range: function keys, keypad keys and so are represented by numbers higher


I would prefer to restore the word on. And so on means and similar cases.

Good catch! I removed it by mistake when edited following words.

serhiy-storchaka · 2017-09-21T12:01:32Z

Should I do anything more @bitdancer?

serhiy-storchaka · 2017-09-26T19:12:36Z

Ping.

miss-islington · 2017-10-04T19:44:16Z

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.6.
🐍🍒⛏🤖

miss-islington · 2017-10-04T19:44:18Z

@serhiy-storchaka, Something is wrong... I can't backport for now.
Please backport using cherry_picker on command line.
cherry_picker 300dd552b15825abfe0e367ac14cec4c3e050dbc 3.6

(cherry picked from commit 300dd55)

bedevere-bot · 2017-10-04T19:45:54Z

GH-3887 is a backport of this pull request to the 3.6 branch.

serhiy-storchaka · 2017-10-04T19:48:22Z

@Mariatta, running cherry_picker manually didn't expose any conflicts. I don't know why @miss-islington failed with backporting.

Mariatta · 2017-10-04T19:54:23Z

Thanks @serhiy-storchaka . It's strange; quickly reading the log, there's an exception when it was trying to do git fetch upstream..
However I haven't find out the cause of that..

bitdancer · 2017-10-04T20:23:07Z

I don't know if it is relevant, but in the past few days on the commercial project I'm working on we've seen an increased incidence of codeship CI jobs failing because the pull from github fails, and then the restarted job will work fine. That is, this may be a github reliability issue.

Mariatta · 2017-10-04T20:40:32Z

Thanks @bitdancer :) Yeah I just restarted miss-islington hoping to get it in clean state ..

I think the next backport should work..

(cherry picked from commit 300dd55)

bpo-30872: Update the curses docs to Python 3.

558af76

serhiy-storchaka added needs backport to 3.5 docs Documentation in the Doc dir labels Jul 7, 2017

the-knights-who-say-ni added the CLA signed label Jul 7, 2017

mlouielu reviewed Jul 13, 2017

View reviewed changes

vadmium reviewed Jul 16, 2017

View reviewed changes

bitdancer requested changes Jul 17, 2017

View reviewed changes

Address some of commit reviews.

2f553bc

serhiy-storchaka added 2 commits July 20, 2017 09:36

Address other review comments.

a9803fc

Merge branch 'master' into curses-docs

de0f636

brettcannon removed the needs backport to 3.5 label Aug 11, 2017

vadmium reviewed Aug 12, 2017

View reviewed changes

serhiy-storchaka added 4 commits August 12, 2017 08:06

Address comments by @vadmium.

e0797e7

Merge branch 'master' into curses-docs

35b8a2f

Fix the wording for num.

d8d3bec

Merge branch 'master' into curses-docs

37bbfb2

serhiy-storchaka added the skip news label Sep 26, 2017

serhiy-storchaka merged commit 300dd55 into python:master Oct 4, 2017

serhiy-storchaka deleted the curses-docs branch October 4, 2017 19:44

serhiy-storchaka added a commit to serhiy-storchaka/cpython that referenced this pull request Oct 4, 2017

[3.6] bpo-30872: Update the curses docs to Python 3. (pythonGH-2620)

2401d7a

(cherry picked from commit 300dd55)

bedevere-bot removed the needs backport to 3.6 label Oct 4, 2017

serhiy-storchaka added a commit that referenced this pull request Oct 5, 2017

[3.6] bpo-30872: Update the curses docs to Python 3. (GH-2620) (#3887)

de5427a

(cherry picked from commit 300dd55)


		If called with yes equal to 1, :mod:`curses` will try and use hardware line
		If called with an argument equal to ``True``, :mod:`curses` will try and use hardware line


		If yes is 1, cursor is left where it is on update, instead of being at "cursor
		If an argument is ``True``, cursor is left where it is on update, instead of being at "cursor

bpo-30872: Update the curses docs to Python 3. #2620

bpo-30872: Update the curses docs to Python 3. #2620

Conversation

serhiy-storchaka commented Jul 7, 2017 • edited by bedevere-bot Loading

mention-bot commented Jul 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bitdancer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

serhiy-storchaka commented Jul 17, 2017

bitdancer commented Jul 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

serhiy-storchaka commented Sep 21, 2017

serhiy-storchaka commented Sep 26, 2017

miss-islington commented Oct 4, 2017

miss-islington commented Oct 4, 2017

bedevere-bot commented Oct 4, 2017

serhiy-storchaka commented Oct 4, 2017

Mariatta commented Oct 4, 2017

bitdancer commented Oct 4, 2017

Mariatta commented Oct 4, 2017

serhiy-storchaka commented Jul 7, 2017 •

edited by bedevere-bot

Loading