Skip to content

Commit 365e077

Browse files
miss-islingtonhugovkhauntsaninja
authored
[3.11] gh-101100: Fix Sphinx warnings in curses and curses.ascii modules (GH-103457) (#104124)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
1 parent 4536b2e commit 365e077

File tree

3 files changed

+500
-468
lines changed

3 files changed

+500
-468
lines changed

‎Doc/howto/curses.rst

+23-21
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
Curses Programming with Python
55
**********************************
66

7+
.. currentmodule:: curses
8+
79
:Author: A.M. Kuchling, Eric S. Raymond
810
:Release: 2.04
911

@@ -65,7 +67,7 @@ The Python module is a fairly simple wrapper over the C functions provided by
6567
curses; if you're already familiar with curses programming in C, it's really
6668
easy to transfer that knowledge to Python. The biggest difference is that the
6769
Python interface makes things simpler by merging different C functions such as
68-
:c:func:`addstr`, :c:func:`mvaddstr`, and :c:func:`mvwaddstr` into a single
70+
:c:func:`!addstr`, :c:func:`!mvaddstr`, and :c:func:`!mvwaddstr` into a single
6971
:meth:`~curses.window.addstr` method. You'll see this covered in more
7072
detail later.
7173

@@ -82,7 +84,7 @@ Before doing anything, curses must be initialized. This is done by
8284
calling the :func:`~curses.initscr` function, which will determine the
8385
terminal type, send any required setup codes to the terminal, and
8486
create various internal data structures. If successful,
85-
:func:`initscr` returns a window object representing the entire
87+
:func:`!initscr` returns a window object representing the entire
8688
screen; this is usually called ``stdscr`` after the name of the
8789
corresponding C variable. ::
8890

@@ -151,8 +153,8 @@ importing the :func:`curses.wrapper` function and using it like this::
151153

152154
The :func:`~curses.wrapper` function takes a callable object and does the
153155
initializations described above, also initializing colors if color
154-
support is present. :func:`wrapper` then runs your provided callable.
155-
Once the callable returns, :func:`wrapper` will restore the original
156+
support is present. :func:`!wrapper` then runs your provided callable.
157+
Once the callable returns, :func:`!wrapper` will restore the original
156158
state of the terminal. The callable is called inside a
157159
:keyword:`try`...\ :keyword:`except` that catches exceptions, restores
158160
the state of the terminal, and then re-raises the exception. Therefore
@@ -200,7 +202,7 @@ This is because curses was originally written with slow 300-baud
200202
terminal connections in mind; with these terminals, minimizing the
201203
time required to redraw the screen was very important. Instead curses
202204
accumulates changes to the screen and displays them in the most
203-
efficient manner when you call :meth:`refresh`. For example, if your
205+
efficient manner when you call :meth:`!refresh`. For example, if your
204206
program displays some text in a window and then clears the window,
205207
there's no need to send the original text because they're never
206208
visible.
@@ -210,7 +212,7 @@ really complicate programming with curses much. Most programs go into a flurry
210212
of activity, and then pause waiting for a keypress or some other action on the
211213
part of the user. All you have to do is to be sure that the screen has been
212214
redrawn before pausing to wait for user input, by first calling
213-
``stdscr.refresh()`` or the :meth:`refresh` method of some other relevant
215+
:meth:`!stdscr.refresh` or the :meth:`!refresh` method of some other relevant
214216
window.
215217

216218
A pad is a special case of a window; it can be larger than the actual display
@@ -234,15 +236,15 @@ displayed. ::
234236
# : filled with pad content.
235237
pad.refresh( 0,0, 5,5, 20,75)
236238

237-
The :meth:`refresh` call displays a section of the pad in the rectangle
239+
The :meth:`!refresh` call displays a section of the pad in the rectangle
238240
extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper
239241
left corner of the displayed section is coordinate (0,0) on the pad. Beyond
240242
that difference, pads are exactly like ordinary windows and support the same
241243
methods.
242244

243245
If you have multiple windows and pads on screen there is a more
244246
efficient way to update the screen and prevent annoying screen flicker
245-
as each part of the screen gets updated. :meth:`refresh` actually
247+
as each part of the screen gets updated. :meth:`!refresh` actually
246248
does two things:
247249

248250
1) Calls the :meth:`~curses.window.noutrefresh` method of each window
@@ -251,8 +253,8 @@ does two things:
251253
2) Calls the function :func:`~curses.doupdate` function to change the
252254
physical screen to match the desired state recorded in the data structure.
253255

254-
Instead you can call :meth:`noutrefresh` on a number of windows to
255-
update the data structure, and then call :func:`doupdate` to update
256+
Instead you can call :meth:`!noutrefresh` on a number of windows to
257+
update the data structure, and then call :func:`!doupdate` to update
256258
the screen.
257259

258260

@@ -261,11 +263,11 @@ Displaying Text
261263

262264
From a C programmer's point of view, curses may sometimes look like a
263265
twisty maze of functions, all subtly different. For example,
264-
:c:func:`addstr` displays a string at the current cursor location in
265-
the ``stdscr`` window, while :c:func:`mvaddstr` moves to a given y,x
266-
coordinate first before displaying the string. :c:func:`waddstr` is just
267-
like :c:func:`addstr`, but allows specifying a window to use instead of
268-
using ``stdscr`` by default. :c:func:`mvwaddstr` allows specifying both
266+
:c:func:`!addstr` displays a string at the current cursor location in
267+
the ``stdscr`` window, while :c:func:`!mvaddstr` moves to a given y,x
268+
coordinate first before displaying the string. :c:func:`!waddstr` is just
269+
like :c:func:`!addstr`, but allows specifying a window to use instead of
270+
using ``stdscr`` by default. :c:func:`!mvwaddstr` allows specifying both
269271
a window and a coordinate.
270272

271273
Fortunately the Python interface hides all these details. ``stdscr``
@@ -298,7 +300,7 @@ the next subsection.
298300
The :meth:`~curses.window.addstr` method takes a Python string or
299301
bytestring as the value to be displayed. The contents of bytestrings
300302
are sent to the terminal as-is. Strings are encoded to bytes using
301-
the value of the window's :attr:`encoding` attribute; this defaults to
303+
the value of the window's :attr:`~window.encoding` attribute; this defaults to
302304
the default system encoding as returned by :func:`locale.getencoding`.
303305

304306
The :meth:`~curses.window.addch` methods take a character, which can be
@@ -444,15 +446,15 @@ There are two methods for getting input from a window:
444446

445447
It's possible to not wait for the user using the
446448
:meth:`~curses.window.nodelay` window method. After ``nodelay(True)``,
447-
:meth:`getch` and :meth:`getkey` for the window become
448-
non-blocking. To signal that no input is ready, :meth:`getch` returns
449-
``curses.ERR`` (a value of -1) and :meth:`getkey` raises an exception.
449+
:meth:`!getch` and :meth:`!getkey` for the window become
450+
non-blocking. To signal that no input is ready, :meth:`!getch` returns
451+
``curses.ERR`` (a value of -1) and :meth:`!getkey` raises an exception.
450452
There's also a :func:`~curses.halfdelay` function, which can be used to (in
451-
effect) set a timer on each :meth:`getch`; if no input becomes
453+
effect) set a timer on each :meth:`!getch`; if no input becomes
452454
available within a specified delay (measured in tenths of a second),
453455
curses raises an exception.
454456

455-
The :meth:`getch` method returns an integer; if it's between 0 and 255, it
457+
The :meth:`!getch` method returns an integer; if it's between 0 and 255, it
456458
represents the ASCII code of the key pressed. Values greater than 255 are
457459
special keys such as Page Up, Home, or the cursor keys. You can compare the
458460
value returned to constants such as :const:`curses.KEY_PPAGE`,

‎Doc/library/curses.ascii.rst

+75-75
Original file line numberDiff line numberDiff line change
@@ -15,81 +15,81 @@ The :mod:`curses.ascii` module supplies name constants for ASCII characters and
1515
functions to test membership in various ASCII character classes. The constants
1616
supplied are names for control characters as follows:
1717

18-
+--------------+----------------------------------------------+
19-
| Name | Meaning |
20-
+==============+==============================================+
21-
| :const:`NUL` | |
22-
+--------------+----------------------------------------------+
23-
| :const:`SOH` | Start of heading, console interrupt |
24-
+--------------+----------------------------------------------+
25-
| :const:`STX` | Start of text |
26-
+--------------+----------------------------------------------+
27-
| :const:`ETX` | End of text |
28-
+--------------+----------------------------------------------+
29-
| :const:`EOT` | End of transmission |
30-
+--------------+----------------------------------------------+
31-
| :const:`ENQ` | Enquiry, goes with :const:`ACK` flow control |
32-
+--------------+----------------------------------------------+
33-
| :const:`ACK` | Acknowledgement |
34-
+--------------+----------------------------------------------+
35-
| :const:`BEL` | Bell |
36-
+--------------+----------------------------------------------+
37-
| :const:`BS` | Backspace |
38-
+--------------+----------------------------------------------+
39-
| :const:`TAB` | Tab |
40-
+--------------+----------------------------------------------+
41-
| :const:`HT` | Alias for :const:`TAB`: "Horizontal tab" |
42-
+--------------+----------------------------------------------+
43-
| :const:`LF` | Line feed |
44-
+--------------+----------------------------------------------+
45-
| :const:`NL` | Alias for :const:`LF`: "New line" |
46-
+--------------+----------------------------------------------+
47-
| :const:`VT` | Vertical tab |
48-
+--------------+----------------------------------------------+
49-
| :const:`FF` | Form feed |
50-
+--------------+----------------------------------------------+
51-
| :const:`CR` | Carriage return |
52-
+--------------+----------------------------------------------+
53-
| :const:`SO` | Shift-out, begin alternate character set |
54-
+--------------+----------------------------------------------+
55-
| :const:`SI` | Shift-in, resume default character set |
56-
+--------------+----------------------------------------------+
57-
| :const:`DLE` | Data-link escape |
58-
+--------------+----------------------------------------------+
59-
| :const:`DC1` | XON, for flow control |
60-
+--------------+----------------------------------------------+
61-
| :const:`DC2` | Device control 2, block-mode flow control |
62-
+--------------+----------------------------------------------+
63-
| :const:`DC3` | XOFF, for flow control |
64-
+--------------+----------------------------------------------+
65-
| :const:`DC4` | Device control 4 |
66-
+--------------+----------------------------------------------+
67-
| :const:`NAK` | Negative acknowledgement |
68-
+--------------+----------------------------------------------+
69-
| :const:`SYN` | Synchronous idle |
70-
+--------------+----------------------------------------------+
71-
| :const:`ETB` | End transmission block |
72-
+--------------+----------------------------------------------+
73-
| :const:`CAN` | Cancel |
74-
+--------------+----------------------------------------------+
75-
| :const:`EM` | End of medium |
76-
+--------------+----------------------------------------------+
77-
| :const:`SUB` | Substitute |
78-
+--------------+----------------------------------------------+
79-
| :const:`ESC` | Escape |
80-
+--------------+----------------------------------------------+
81-
| :const:`FS` | File separator |
82-
+--------------+----------------------------------------------+
83-
| :const:`GS` | Group separator |
84-
+--------------+----------------------------------------------+
85-
| :const:`RS` | Record separator, block-mode terminator |
86-
+--------------+----------------------------------------------+
87-
| :const:`US` | Unit separator |
88-
+--------------+----------------------------------------------+
89-
| :const:`SP` | Space |
90-
+--------------+----------------------------------------------+
91-
| :const:`DEL` | Delete |
92-
+--------------+----------------------------------------------+
18+
+---------------+----------------------------------------------+
19+
| Name | Meaning |
20+
+===============+==============================================+
21+
| .. data:: NUL | |
22+
+---------------+----------------------------------------------+
23+
| .. data:: SOH | Start of heading, console interrupt |
24+
+---------------+----------------------------------------------+
25+
| .. data:: STX | Start of text |
26+
+---------------+----------------------------------------------+
27+
| .. data:: ETX | End of text |
28+
+---------------+----------------------------------------------+
29+
| .. data:: EOT | End of transmission |
30+
+---------------+----------------------------------------------+
31+
| .. data:: ENQ | Enquiry, goes with :const:`ACK` flow control |
32+
+---------------+----------------------------------------------+
33+
| .. data:: ACK | Acknowledgement |
34+
+---------------+----------------------------------------------+
35+
| .. data:: BEL | Bell |
36+
+---------------+----------------------------------------------+
37+
| .. data:: BS | Backspace |
38+
+---------------+----------------------------------------------+
39+
| .. data:: TAB | Tab |
40+
+---------------+----------------------------------------------+
41+
| .. data:: HT | Alias for :const:`TAB`: "Horizontal tab" |
42+
+---------------+----------------------------------------------+
43+
| .. data:: LF | Line feed |
44+
+---------------+----------------------------------------------+
45+
| .. data:: NL | Alias for :const:`LF`: "New line" |
46+
+---------------+----------------------------------------------+
47+
| .. data:: VT | Vertical tab |
48+
+---------------+----------------------------------------------+
49+
| .. data:: FF | Form feed |
50+
+---------------+----------------------------------------------+
51+
| .. data:: CR | Carriage return |
52+
+---------------+----------------------------------------------+
53+
| .. data:: SO | Shift-out, begin alternate character set |
54+
+---------------+----------------------------------------------+
55+
| .. data:: SI | Shift-in, resume default character set |
56+
+---------------+----------------------------------------------+
57+
| .. data:: DLE | Data-link escape |
58+
+---------------+----------------------------------------------+
59+
| .. data:: DC1 | XON, for flow control |
60+
+---------------+----------------------------------------------+
61+
| .. data:: DC2 | Device control 2, block-mode flow control |
62+
+---------------+----------------------------------------------+
63+
| .. data:: DC3 | XOFF, for flow control |
64+
+---------------+----------------------------------------------+
65+
| .. data:: DC4 | Device control 4 |
66+
+---------------+----------------------------------------------+
67+
| .. data:: NAK | Negative acknowledgement |
68+
+---------------+----------------------------------------------+
69+
| .. data:: SYN | Synchronous idle |
70+
+---------------+----------------------------------------------+
71+
| .. data:: ETB | End transmission block |
72+
+---------------+----------------------------------------------+
73+
| .. data:: CAN | Cancel |
74+
+---------------+----------------------------------------------+
75+
| .. data:: EM | End of medium |
76+
+---------------+----------------------------------------------+
77+
| .. data:: SUB | Substitute |
78+
+---------------+----------------------------------------------+
79+
| .. data:: ESC | Escape |
80+
+---------------+----------------------------------------------+
81+
| .. data:: FS | File separator |
82+
+---------------+----------------------------------------------+
83+
| .. data:: GS | Group separator |
84+
+---------------+----------------------------------------------+
85+
| .. data:: RS | Record separator, block-mode terminator |
86+
+---------------+----------------------------------------------+
87+
| .. data:: US | Unit separator |
88+
+---------------+----------------------------------------------+
89+
| .. data:: SP | Space |
90+
+---------------+----------------------------------------------+
91+
| .. data:: DEL | Delete |
92+
+---------------+----------------------------------------------+
9393

9494
Note that many of these have little practical significance in modern usage. The
9595
mnemonics derive from teleprinter conventions that predate digital computers.

0 commit comments

Comments
 (0)