Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[3.11] gh-101100: Fix Sphinx warnings in curses and curses.ascii modules (GH-103457) #104124

Merged
merged 1 commit into from
May 3, 2023
Merged

[3.11] gh-101100: Fix Sphinx warnings in curses and curses.ascii modules (GH-103457) #104124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 23 additions & 21 deletions Doc/howto/curses.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
Curses Programming with Python
**********************************

.. currentmodule:: curses

:Author: A.M. Kuchling, Eric S. Raymond
:Release: 2.04

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

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

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

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

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

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

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

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

Instead you can call :meth:`noutrefresh` on a number of windows to
update the data structure, and then call :func:`doupdate` to update
Instead you can call :meth:`!noutrefresh` on a number of windows to
update the data structure, and then call :func:`!doupdate` to update
the screen.


Expand All @@ -261,11 +263,11 @@ Displaying Text

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

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

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

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

The :meth:`getch` method returns an integer; if it's between 0 and 255, it
The :meth:`!getch` method returns an integer; if it's between 0 and 255, it
represents the ASCII code of the key pressed. Values greater than 255 are
special keys such as Page Up, Home, or the cursor keys. You can compare the
value returned to constants such as :const:`curses.KEY_PPAGE`,
Expand Down
150 changes: 75 additions & 75 deletions Doc/library/curses.ascii.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,81 +15,81 @@ The :mod:`curses.ascii` module supplies name constants for ASCII characters and
functions to test membership in various ASCII character classes. The constants
supplied are names for control characters as follows:

+--------------+----------------------------------------------+
| Name | Meaning |
+==============+==============================================+
| :const:`NUL` | |
+--------------+----------------------------------------------+
| :const:`SOH` | Start of heading, console interrupt |
+--------------+----------------------------------------------+
| :const:`STX` | Start of text |
+--------------+----------------------------------------------+
| :const:`ETX` | End of text |
+--------------+----------------------------------------------+
| :const:`EOT` | End of transmission |
+--------------+----------------------------------------------+
| :const:`ENQ` | Enquiry, goes with :const:`ACK` flow control |
+--------------+----------------------------------------------+
| :const:`ACK` | Acknowledgement |
+--------------+----------------------------------------------+
| :const:`BEL` | Bell |
+--------------+----------------------------------------------+
| :const:`BS` | Backspace |
+--------------+----------------------------------------------+
| :const:`TAB` | Tab |
+--------------+----------------------------------------------+
| :const:`HT` | Alias for :const:`TAB`: "Horizontal tab" |
+--------------+----------------------------------------------+
| :const:`LF` | Line feed |
+--------------+----------------------------------------------+
| :const:`NL` | Alias for :const:`LF`: "New line" |
+--------------+----------------------------------------------+
| :const:`VT` | Vertical tab |
+--------------+----------------------------------------------+
| :const:`FF` | Form feed |
+--------------+----------------------------------------------+
| :const:`CR` | Carriage return |
+--------------+----------------------------------------------+
| :const:`SO` | Shift-out, begin alternate character set |
+--------------+----------------------------------------------+
| :const:`SI` | Shift-in, resume default character set |
+--------------+----------------------------------------------+
| :const:`DLE` | Data-link escape |
+--------------+----------------------------------------------+
| :const:`DC1` | XON, for flow control |
+--------------+----------------------------------------------+
| :const:`DC2` | Device control 2, block-mode flow control |
+--------------+----------------------------------------------+
| :const:`DC3` | XOFF, for flow control |
+--------------+----------------------------------------------+
| :const:`DC4` | Device control 4 |
+--------------+----------------------------------------------+
| :const:`NAK` | Negative acknowledgement |
+--------------+----------------------------------------------+
| :const:`SYN` | Synchronous idle |
+--------------+----------------------------------------------+
| :const:`ETB` | End transmission block |
+--------------+----------------------------------------------+
| :const:`CAN` | Cancel |
+--------------+----------------------------------------------+
| :const:`EM` | End of medium |
+--------------+----------------------------------------------+
| :const:`SUB` | Substitute |
+--------------+----------------------------------------------+
| :const:`ESC` | Escape |
+--------------+----------------------------------------------+
| :const:`FS` | File separator |
+--------------+----------------------------------------------+
| :const:`GS` | Group separator |
+--------------+----------------------------------------------+
| :const:`RS` | Record separator, block-mode terminator |
+--------------+----------------------------------------------+
| :const:`US` | Unit separator |
+--------------+----------------------------------------------+
| :const:`SP` | Space |
+--------------+----------------------------------------------+
| :const:`DEL` | Delete |
+--------------+----------------------------------------------+
+---------------+----------------------------------------------+
| Name | Meaning |
+===============+==============================================+
| .. data:: NUL | |
+---------------+----------------------------------------------+
| .. data:: SOH | Start of heading, console interrupt |
+---------------+----------------------------------------------+
| .. data:: STX | Start of text |
+---------------+----------------------------------------------+
| .. data:: ETX | End of text |
+---------------+----------------------------------------------+
| .. data:: EOT | End of transmission |
+---------------+----------------------------------------------+
| .. data:: ENQ | Enquiry, goes with :const:`ACK` flow control |
+---------------+----------------------------------------------+
| .. data:: ACK | Acknowledgement |
+---------------+----------------------------------------------+
| .. data:: BEL | Bell |
+---------------+----------------------------------------------+
| .. data:: BS | Backspace |
+---------------+----------------------------------------------+
| .. data:: TAB | Tab |
+---------------+----------------------------------------------+
| .. data:: HT | Alias for :const:`TAB`: "Horizontal tab" |
+---------------+----------------------------------------------+
| .. data:: LF | Line feed |
+---------------+----------------------------------------------+
| .. data:: NL | Alias for :const:`LF`: "New line" |
+---------------+----------------------------------------------+
| .. data:: VT | Vertical tab |
+---------------+----------------------------------------------+
| .. data:: FF | Form feed |
+---------------+----------------------------------------------+
| .. data:: CR | Carriage return |
+---------------+----------------------------------------------+
| .. data:: SO | Shift-out, begin alternate character set |
+---------------+----------------------------------------------+
| .. data:: SI | Shift-in, resume default character set |
+---------------+----------------------------------------------+
| .. data:: DLE | Data-link escape |
+---------------+----------------------------------------------+
| .. data:: DC1 | XON, for flow control |
+---------------+----------------------------------------------+
| .. data:: DC2 | Device control 2, block-mode flow control |
+---------------+----------------------------------------------+
| .. data:: DC3 | XOFF, for flow control |
+---------------+----------------------------------------------+
| .. data:: DC4 | Device control 4 |
+---------------+----------------------------------------------+
| .. data:: NAK | Negative acknowledgement |
+---------------+----------------------------------------------+
| .. data:: SYN | Synchronous idle |
+---------------+----------------------------------------------+
| .. data:: ETB | End transmission block |
+---------------+----------------------------------------------+
| .. data:: CAN | Cancel |
+---------------+----------------------------------------------+
| .. data:: EM | End of medium |
+---------------+----------------------------------------------+
| .. data:: SUB | Substitute |
+---------------+----------------------------------------------+
| .. data:: ESC | Escape |
+---------------+----------------------------------------------+
| .. data:: FS | File separator |
+---------------+----------------------------------------------+
| .. data:: GS | Group separator |
+---------------+----------------------------------------------+
| .. data:: RS | Record separator, block-mode terminator |
+---------------+----------------------------------------------+
| .. data:: US | Unit separator |
+---------------+----------------------------------------------+
| .. data:: SP | Space |
+---------------+----------------------------------------------+
| .. data:: DEL | Delete |
+---------------+----------------------------------------------+

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