gh-156234: Fix and rewrite the curses documentation on reading

[serhiy-storchaka]

Fix wrong types: instr() and getstr() return a bytes object, not a str, and their n limits the number of bytes; getkey() returns a str; unctrl() returns a bytes object. Make clear whether an integer standing for a character is an encoded byte or a character code.

Rewrite the documentation of getch(), get_wch(), getkey(), getstr(), get_wstr(), instr(), in_wstr() and in_wchstr(), following X/Open Curses.

• Issue: curses: incorrect and incomplete documentation of the reading functions #156234

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34186557 | 📁 Comparing 2aeb57f against main (f74cdf8)

  🔍 Preview build  

1 file changed

± library/curses.html

[miss-islington-app]

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington-app]

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.15 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker be87bfa8a1a68516cedc618c7cf5bb7b0b251678 3.15

[miss-islington-app]

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker be87bfa8a1a68516cedc618c7cf5bb7b0b251678 3.14

[miss-islington-app]

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker be87bfa8a1a68516cedc618c7cf5bb7b0b251678 3.13

[bedevere-app]

GH-156279 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

GH-156280 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-156281 is a backport of this pull request to the 3.13 branch.

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot AMD64 Arch Linux Asan 3.13 (tierless) has failed when building commit 2eb7ed5.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1464/builds/1214) and take a look at the build logs.
4. Check if the failure is related to this commit (2eb7ed5) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1464/builds/1214

Failed tests:

• test_io

Failed subtests:

• test_daemon_threads_shutdown_stderr_deadlock - test.test_io.CMiscIOTest.test_daemon_threads_shutdown_stderr_deadlock
• test_daemon_threads_shutdown_stdout_deadlock - test.test_io.CMiscIOTest.test_daemon_threads_shutdown_stdout_deadlock

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4821, in test_daemon_threads_shutdown_stderr_deadlock
    self.check_daemon_threads_shutdown_deadlock('stderr')
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4811, in check_daemon_threads_shutdown_deadlock
    self.assertFalse(err.strip('.!'))
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
AssertionError: '=================================================================\n==2309649==ERROR: AddressSanitizer: heap-use-after-free on address 0x7cfd71c52898 at pc 0x563587e7d146 bp 0x7bcd6f9fe080 sp 0x7bcd6f9fe070\nREAD of size 8 at 0x7cfd71c52898 thread T1\n' is not false


Traceback (most recent call last):
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4821, in test_daemon_threads_shutdown_stderr_deadlock
    self.check_daemon_threads_shutdown_deadlock('stderr')
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4811, in check_daemon_threads_shutdown_deadlock
    self.assertFalse(err.strip('.!'))
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
AssertionError: '=================================================================\n==2299230==ERROR: AddressSanitizer: heap-use-after-free on address 0x7cd7e5652898 at pc 0x559e0f1c6146 bp 0x7ba7e33fe080 sp 0x7ba7e33fe070\nREAD of size 8 at 0x7cd7e5652898 thread T1\n' is not false


Traceback (most recent call last):
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4816, in test_daemon_threads_shutdown_stdout_deadlock
    self.check_daemon_threads_shutdown_deadlock('stdout')
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4811, in check_daemon_threads_shutdown_deadlock
    self.assertFalse(err.strip('.!'))
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
AssertionError: '=================================================================\n==2309651==ERROR: AddressSanitizer: heap-use-after-free on address 0x7c3ee0652898 at pc 0x556241f89146 bp 0x7b0ede3fe080 sp 0x7b0ede3fe070\nREAD of size 8 at 0x7c3ee0652898 thread T1\n' is not false


Traceback (most recent call last):
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4816, in test_daemon_threads_shutdown_stdout_deadlock
    self.check_daemon_threads_shutdown_deadlock('stdout')
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/buildbot/buildarea/3.13.pablogsal-arch-x86_64.asan/build/Lib/test/test_io.py", line 4811, in check_daemon_threads_shutdown_deadlock
    self.assertFalse(err.strip('.!'))
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
AssertionError: '=================================================================\n==2299232==ERROR: AddressSanitizer: heap-use-after-free on address 0x7c98d2852898 at pc 0x564dddb32146 bp 0x7b68d05fe080 sp 0x7b68d05fe070\nREAD of size 8 at 0x7c98d2852898 thread T1\n' is not false

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot x86-64 macOS 3.13 (tier-2) has failed when building commit 2eb7ed5.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1483/builds/1645) and take a look at the build logs.
4. Check if the failure is related to this commit (2eb7ed5) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1483/builds/1645

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/Users/buildbot/buildarea/3.13.billenstein-macos/build/Lib/unittest/case.py", line 606, in _callTestMethod
    if method() is not None:
ResourceWarning: unclosed <socket.socket fd=7, family=2, type=1, proto=6, laddr=('127.0.0.1', 60582)>
k


Traceback (most recent call last):
  File "/Users/buildbot/buildarea/3.13.billenstein-macos/build/Lib/unittest/case.py", line 606, in _callTestMethod
    if method() is not None:
ResourceWarning: unclosed <socket.socket fd=7, family=2, type=1, proto=6, laddr=('127.0.0.1', 61600)>
k