This is /home/pdm/install/Python-2.1/Doc/lib/python-lib.info, produced by makeinfo version 4.0 from lib.texi. April 15, 2001 2.1  File: python-lib.info, Node: time, Next: sched, Prev: popen2, Up: Generic Operating System Services Time access and conversions =========================== Time access and conversions. This module provides various time-related functions. It is always available, but not all functions are available on all platforms. An explanation of some terminology and conventions is in order. * The "epoch" is the point where the time starts. On January 1st of that year, at 0 hours, the "time since the epoch" is zero. For UNIX, the epoch is 1970. To find out what the epoch is, look at `gmtime(0)'. * The functions in this module do not handle dates and times before the epoch or far in the future. The cut-off point in the future is determined by the C library; for UNIX, it is typically in 2038. * *Year 2000 (Y2K) issues*: Python depends on the platform's C library, which generally doesn't have year 2000 issues, since all dates and times are represented internally as seconds since the epoch. Functions accepting a time tuple (see below) generally require a 4-digit year. For backward compatibility, 2-digit years are supported if the module variable `accept2dyear' is a non-zero integer; this variable is initialized to `1' unless the environment variable `PYTHONY2K' is set to a non-empty string, in which case it is initialized to `0'. Thus, you can set `PYTHONY2K' to a non-empty string in the environment to require 4-digit years for all year input. When 2-digit years are accepted, they are converted according to the POSIX or X/Open standard: values 69-99 are mapped to 1969-1999, and values 0-68 are mapped to 2000-2068. Values 100-1899 are always illegal. Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1, would add 1900 to year values below 1900. * UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or GMT). The acronym UTC is not a mistake but a compromise between English and French. * DST is Daylight Saving Time, an adjustment of the timezone by (usually) one hour during part of the year. DST rules are magic (determined by local law) and can change from year to year. The C library has a table containing the local rules (often it is read from a system file for flexibility) and is the only source of True Wisdom in this respect. * The precision of the various real-time functions may be less than suggested by the units in which their value or argument is expressed. E.g. on most UNIX systems, the clock "ticks" only 50 or 100 times a second, and on the Mac, times are only accurate to whole seconds. * On the other hand, the precision of `time()' and `sleep()' is better than their UNIX equivalents: times are expressed as floating point numbers, `time()' returns the most accurate time available (using UNIX `gettimeofday()' where available), and `sleep()' will accept a time with a nonzero fraction (UNIX `select()' is used to implement this, where available). * The time tuple as returned by `gmtime()', `localtime()', and `strptime()', and accepted by `asctime()', `mktime()' and `strftime()', is a tuple of 9 integers: Index Field Values ------ ----- ----- 0 year (e.g. 1993) 1 month range [1,12] 2 day range [1,31] 3 hour range [0,23] 4 minute range [0,59] 5 second range [0,61]; see *(1)* in `strftime()' description 6 weekday range [0,6], Monday is 0 7 Julian day range [1,366] 8 daylight savings flag 0, 1 or -1; see below Note that unlike the C structure, the month value is a range of 1-12, not 0-11. A year value will be handled as described under "Year 2000 (Y2K) issues" above. A `-1' argument as daylight savings flag, passed to `mktime()' will usually result in the correct daylight savings state to be filled in. The module defines the following functions and data items: `accept2dyear' Boolean value indicating whether two-digit year values will be accepted. This is true by default, but will be set to false if the environment variable `PYTHONY2K' has been set to a non-empty string. It may also be modified at run time. `altzone' The offset of the local DST timezone, in seconds west of UTC, if one is defined. This is negative if the local DST timezone is east of UTC (as in Western Europe, including the UK). Only use this if `daylight' is nonzero. `asctime([tuple])' Convert a tuple representing a time as returned by `gmtime()' or `localtime()' to a 24-character string of the following form: `'Sun Jun 20 23:21:05 1993''. If TUPLE is not provided, the current time as returned by `localtime()' is used. Note: unlike the C function of the same name, there is no trailing newline. `clock()' Return the current CPU time as a floating point number expressed in seconds. The precision, and in fact the very definition of the meaning of "CPU time", depends on that of the C function of the same name, but in any case, this is the function to use for benchmarking Python or timing algorithms. `ctime([secs])' Convert a time expressed in seconds since the epoch to a string representing local time. If SECS is not provided, the current time as returned by `time()' is used. `ctime(SECS)' is equivalent to `asctime(localtime(SECS))'. `daylight' Nonzero if a DST timezone is defined. `gmtime([secs])' Convert a time expressed in seconds since the epoch to a time tuple in UTC in which the dst flag is always zero. If SECS is not provided, the current time as returned by `time()' is used. Fractions of a second are ignored. See above for a description of the tuple lay-out. `localtime([secs])' Like `gmtime()' but converts to local time. The dst flag is set to `1' when DST applies to the given time. `mktime(tuple)' This is the inverse function of `localtime()'. Its argument is the full 9-tuple (since the dst flag is needed; use `-1' as the dst flag if it is unknown) which expresses the time in _local_ time, not UTC. It returns a floating point number, for compatibility with `time()'. If the input value cannot be represented as a valid time, `OverflowError' is raised. `sleep(secs)' Suspend execution for the given number of seconds. The argument may be a floating point number to indicate a more precise sleep time. The actual suspension time may be less than that requested because any caught signal will terminate the `sleep()' following execution of that signal's catching routine. Also, the suspension time may be longer than requested by an arbitrary amount because of the scheduling of other activity in the system. `strftime(format[, tuple])' Convert a tuple representing a time as returned by `gmtime()' or `localtime()' to a string as specified by the FORMAT argument. If TUPLE is not provided, the current time as returned by `localtime()' is used. FORMAT must be a string. The following directives can be embedded in the FORMAT string. They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the `strftime()' result: Directive Meaning Notes ------ ----- ----- %a Locale's abbreviated weekday name. %A Locale's full weekday name. %b Locale's abbreviated month name. %B Locale's full month name. %c Locale's appropriate date and time representation. %d Day of the month as a decimal number [01,31]. %H Hour (24-hour clock) as a decimal number [00,23]. %I Hour (12-hour clock) as a decimal number [01,12]. %j Day of the year as a decimal number [001,366]. %m Month as a decimal number [01,12]. %M Minute as a decimal number [00,59]. %p Locale's equivalent of either AM or PM. %S Second as a decimal (1) number [00,61]. %U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. %w Weekday as a decimal number [0(Sunday),6]. %W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. %x Locale's appropriate date representation. %X Locale's appropriate time representation. %y Year without century as a decimal number [00,99]. %Y Year with century as a decimal number. %Z Time zone name (or by no characters if no time zone exists). %% A literal `%' character. Notes: `(1)' The range really is `0' to `61'; this accounts for leap seconds and the (very rare) double leap seconds. Here is an example, a format for dates compatible with that specified in the RFC 822 Internet email standard. (1) >>> from time import * >>> strftime("%a, %d %b %Y %H:%M:%S %Z", localtime()) 'Sat, 27 Jan 2001 05:15:05 EST' >>> Additional directives may be supported on certain platforms, but only the ones listed here have a meaning standardized by ANSI C. On some platforms, an optional field width and precision specification can immediately follow the initial `%' of a directive in the following order; this is also not portable. The field width is normally 2 except for `%j' where it is 3. `strptime(string[, format])' Parse a string representing a time according to a format. The return value is a tuple as returned by `gmtime()' or `localtime()'. The FORMAT parameter uses the same directives as those used by `strftime()'; it defaults to `"%a %b %d %H:%M:%S %Y"' which matches the formatting returned by `ctime()'. The same platform caveats apply; see the local UNIX documentation for restrictions or additional supported directives. If STRING cannot be parsed according to FORMAT, `ValueError' is raised. Values which are not provided as part of the input string are filled in with default values; the specific values are platform-dependent as the XPG standard does not provide sufficient information to constrain the result. *Note:* This function relies entirely on the underlying platform's C library for the date parsing, and some of these libraries are buggy. There's nothing to be done about this short of a new, portable implementation of `strptime()'. Availability: Most modern UNIX systems. `time()' Return the time as a floating point number expressed in seconds since the epoch, in UTC. Note that even though the time is always returned as a floating point number, not all systems provide time with a better precision than 1 second. `timezone' The offset of the local (non-DST) timezone, in seconds west of UTC (i.e. negative in most of Western Europe, positive in the US, zero in the UK). `tzname' A tuple of two strings: the first is the name of the local non-DST timezone, the second is the name of the local DST timezone. If no DST timezone is defined, the second string should not be used. See also: *Note locale:: Internationalization services. The locale settings can affect the return values for some of the functions in the `time' module. ---------- Footnotes ---------- (1) The use of %Z is now deprecated, but the %z escape that expands to the preferred hour/minute offset is not supported by all ANSI C libraries. Also, a strict reading of the original 1982 RFC 822 standard calls for a two-digit year (%y rather than %Y), but practice moved to 4-digit years long before the year 2000.  File: python-lib.info, Node: sched, Next: mutex, Prev: time, Up: Generic Operating System Services Event scheduler =============== This section was written by Moshe Zadka . General purpose event scheduler. The `sched' module defines a class which implements a general purpose event scheduler: `scheduler(timefunc, delayfunc)' The `scheduler' class defines a generic interface to scheduling events. It needs two functions to actually deal with the "outside world" -- TIMEFUNC should be callable without arguments, and return a number (the "time", in any units whatsoever). The DELAYFUNC function should be callable with one argument, compatible with the output of TIMEFUNC, and should delay that many time units. DELAYFUNC will also be called with the argument `0' after each event is run to allow other threads an opportunity to run in multi-threaded applications. Example: >>> import sched, time >>> s=sched.scheduler(time.time, time.sleep) >>> def print_time(): print "From print_time", time.time() ... >>> def print_some_times(): ... print time.time() ... s.enter(5, 1, print_time, ()) ... s.enter(10, 1, print_time, ()) ... s.run() ... print time.time() ... >>> print_some_times() 930343690.257 From print_time 930343695.274 From print_time 930343700.273 930343700.276 * Menu: * Scheduler Objects::  File: python-lib.info, Node: Scheduler Objects, Prev: sched, Up: sched Scheduler Objects ----------------- `scheduler' instances have the following methods: `enterabs(time, priority, action, argument)' Schedule a new event. The TIME argument should be a numeric type compatible with the return value of the TIMEFUNC function passed to the constructor. Events scheduled for the same TIME will be executed in the order of their PRIORITY. Executing the event means executing `apply(ACTION, ARGUMENT)'. ARGUMENT must be a tuple holding the parameters for ACTION. Return value is an event which may be used for later cancellation of the event (see `cancel()'). `enter(delay, priority, action, argument)' Schedule an event for DELAY more time units. Other then the relative time, the other arguments, the effect and the return value are the same as those for `enterabs()'. `cancel(event)' Remove the event from the queue. If EVENT is not an event currently in the queue, this method will raise a `RuntimeError'. `empty()' Return true if the event queue is empty. `run()' Run all scheduled events. This function will wait (using the `delayfunc' function passed to the constructor) for the next event, then execute it and so on until there are no more scheduled events. Either ACTION or DELAYFUNC can raise an exception. In either case, the scheduler will maintain a consistent state and propagate the exception. If an exception is raised by ACTION, the event will not be attempted in future calls to `run()'. If a sequence of events takes longer to run than the time available before the next event, the scheduler will simply fall behind. No events will be dropped; the calling code is responsible for canceling events which are no longer pertinent.  File: python-lib.info, Node: mutex, Next: getpass, Prev: sched, Up: Generic Operating System Services Mutual exclusion support ======================== This section was written by Moshe Zadka . Lock and queue for mutual exclusion. The `mutex' module defines a class that allows mutual-exclusion via acquiring and releasing locks. It does not require (or imply) threading or multi-tasking, though it could be useful for those purposes. The `mutex' module defines the following class: `mutex()' Create a new (unlocked) mutex. A mutex has two pieces of state -- a "locked" bit and a queue. When the mutex is not locked, the queue is empty. Otherwise, the queue contains zero or more `(FUNCTION, ARGUMENT)' pairs representing functions (or methods) waiting to acquire the lock. When the mutex is unlocked while the queue is not empty, the first queue entry is removed and its `FUNCTION(ARGUMENT)' pair called, implying it now has the lock. Of course, no multi-threading is implied - hence the funny interface for `lock()', where a function is called once the lock is acquired. * Menu: * Mutex Objects::  File: python-lib.info, Node: Mutex Objects, Prev: mutex, Up: mutex Mutex Objects ------------- `mutex' objects have following methods: `test()' Check whether the mutex is locked. `testandset()' "Atomic" test-and-set, grab the lock if it is not set, and return true, otherwise, return false. `lock(function, argument)' Execute `FUNCTION(ARGUMENT)', unless the mutex is locked. In the case it is locked, place the function and argument on the queue. See `unlock' for explanation of when `FUNCTION(ARGUMENT)' is executed in that case. `unlock()' Unlock the mutex if queue is empty, otherwise execute the first element in the queue.  File: python-lib.info, Node: getpass, Next: curses, Prev: mutex, Up: Generic Operating System Services Portable password input ======================= Portable reading of passwords and retrieval of the userid. This module was documented by Piers Lauder . This section was written by Fred L. Drake, Jr. . The `getpass' module provides two functions: `getpass([prompt])' Prompt the user for a password without echoing. The user is prompted using the string PROMPT, which defaults to `'Password: ''. Availability: Macintosh, UNIX, Windows. `getuser()' Return the "login name" of the user. Availability: UNIX, Windows. This function checks the environment variables `LOGNAME', `USER', `LNAME' and `USERNAME', in order, and returns the value of the first one which is set to a non-empty string. If none are set, the login name from the password database is returned on systems which support the `pwd' module, otherwise, an exception is raised.  File: python-lib.info, Node: curses, Next: curses.textpad, Prev: getpass, Up: Generic Operating System Services Terminal handling for character-cell displays ============================================= This section was written by Moshe Zadka . This section was written by Eric Raymond . An interface to the curses library, providing portable terminal handling. _Changed in Python version 1.6_ The `curses' module provides an interface to the curses library, the de-facto standard for portable advanced terminal handling. While curses is most widely used in the UNIX environment, versions are available for DOS, OS/2, and possibly other systems as well. This extension module is designed to match the API of ncurses, an open-source curses library hosted on Linux and the BSD variants of UNIX. See also: *Note curses.ascii:: Utilities for working with ASCII characters, regardless of your locale settings. *Note curses.panel:: A panel stack extension that adds depth to curses windows. *Note curses.textpad:: Editable text widget for curses supporting `Emacs'-like bindings. *Note curses.wrapper:: Convenience function to ensure proper terminal setup and resetting on application entry and exit. `Curses Programming with Python'{Tutorial material on using curses with Python, by Andrew Kuchling and Eric Raymond, is available on the Python Web site.} The `Demo/curses/' directory in the Python source distribution contains some example programs using the curses bindings provided by this module. * Menu: * Functions 2:: * Window Objects:: * Constants::  File: python-lib.info, Node: Functions 2, Next: Window Objects, Prev: curses, Up: curses Functions --------- The module `curses' defines the following exception: `error' Exception raised when a curses library function returns an error. *Note:* Whenever X or Y arguments to a function or a method are optional, they default to the current cursor location. Whenever ATTR is optional, it defaults to `A_NORMAL'. The module `curses' defines the following functions: `baudrate()' Returns the output speed of the terminal in bits per second. On software terminal emulators it will have a fixed high value. Included for historical reasons; in former times, it was used to write output loops for time delays and occasionally to change interfaces depending on the line speed. `beep()' Emit a short attention sound. `can_change_color()' Returns true or false, depending on whether the programmer can change the colors displayed by the terminal. `cbreak()' Enter cbreak mode. In cbreak mode (sometimes called "rare" mode) normal tty line buffering is turned off and characters are available to be read one by one. However, unlike raw mode, special characters (interrupt, quit, suspend, and flow control) retain their effects on the tty driver and calling program. Calling first `raw()' then `cbreak()' leaves the terminal in cbreak mode. `color_content(color_number)' Returns the intensity of the red, green, and blue (RGB) components in the color COLOR_NUMBER, which must be between `0' and `COLORS'. A 3-tuple is returned, containing the R,G,B values for the given color, which will be between `0' (no component) and `1000' (maximum amount of component). `color_pair(color_number)' Returns the attribute value for displaying text in the specified color. This attribute value can be combined with `A_STANDOUT', `A_REVERSE', and the other `A_*' attributes. `pair_number()' is the counterpart to this function. `curs_set(visibility)' Sets the cursor state. VISIBILITY can be set to 0, 1, or 2, for invisible, normal, or very visible. If the terminal supports the visibility requested, the previous cursor state is returned; otherwise, an exception is raised. On many terminals, the "visible" mode is an underline cursor and the "very visible" mode is a block cursor. `def_prog_mode()' Saves the current terminal mode as the "program" mode, the mode when the running program is using curses. (Its counterpart is the "shell" mode, for when the program is not in curses.) Subsequent calls to `reset_prog_mode()' will restore this mode. `def_shell_mode()' Saves the current terminal mode as the "shell" mode, the mode when the running program is not using curses. (Its counterpart is the "program" mode, when the program is using curses capabilities.) Subsequent calls to `reset_shell_mode()' will restore this mode. `delay_output(ms)' Inserts an MS millisecond pause in output. `doupdate()' Update the physical screen. The curses library keeps two data structures, one representing the current physical screen contents and a virtual screen representing the desired next state. The `doupdate()' ground updates the physical screen to match the virtual screen. The virtual screen may be updated by a `noutrefresh()' call after write operations such as `addstr()' have been performed on a window. The normal `refresh()' call is simply `noutrefresh()' followed by `doupdate()'; if you have to update multiple windows, you can speed performance and perhaps reduce screen flicker by issuing `noutrefresh()' calls on all windows, followed by a single `doupdate()'. `echo()' Enter echo mode. In echo mode, each character input is echoed to the screen as it is entered. `endwin()' De-initialize the library, and return terminal to normal status. `erasechar()' Returns the user's current erase character. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself. `filter()' The `filter()' routine, if used, must be called before `initscr()' is called. The effect is that, during those calls, 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 the current line, and so are screen updates. This may be used for enabling cgaracter-at-a-time line editing without touching the rest of the screen. `flash()' Flash the screen. That is, change it to reverse-video and then change it back in a short interval. Some people prefer such as `visible bell' to the audible attention signal produced by `beep()'. `flushinp()' Flush all input buffers. This throws away any typeahead that has been typed by the user and has not yet been processed by the program. `getmouse()' After `getch()' returns `KEY_MOUSE' to signal a mouse event, this method should be call to retrieve the queued mouse event, represented as a 5-tuple `(ID, X, Y, Z, BSTATE)'. ID is an ID value used to distinguish multiple devices, and X, Y, Z are the event's coordinates. (Z is currently unused.). BSTATE is an integer value whose bits will be set to indicate the type of event, and will be the bitwise OR of one or more of the following constants, where N is the button number from 1 to 4: `BUTTONN_PRESSED', `BUTTONN_RELEASED', `BUTTONN_CLICKED', `BUTTONN_DOUBLE_CLICKED', `BUTTONN_TRIPLE_CLICKED', `BUTTON_SHIFT', `BUTTON_CTRL', `BUTTON_ALT'. `getsyx()' Returns the current coordinates of the virtual screen cursor in y and x. If leaveok is currently true, then -1,-1 is returned. `getwin(file)' Reads window related data stored in the file by an earlier `putwin()' call. The routine then creates and initializes a new window using that data, returning the new window object. `has_colors()' Returns true if the terminal can display colors; otherwise, it returns false. `has_ic()' Returns true if the terminal has insert- and delete- character capabilities. This function is included for historical reasons only, as all modern software terminal emulators have such capabilities. `has_il()' Returns true if the terminal has insert- and delete-line capabilities, or can simulate them using scrolling regions. This function is included for historical reasons only, as all modern software terminal emulators have such capabilities. `has_key(ch)' Takes a key value CH, and returns true if the current terminal type recognizes a key with that value. `halfdelay(tenths)' Used for half-delay mode, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after blocking for TENTHS tenths of seconds, an exception is raised if nothing has been typed. The value of TENTHS must be a number between 1 and 255. Use `nocbreak()' to leave half-delay mode. `init_color(color_number, r, g, b)' Changes the definition of a color, taking the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of COLOR_NUMBER must be between `0' and `COLORS'. Each of R, G, B, must be a value between `0' and `1000'. When `init_color()' is used, all occurrences of that color on the screen immediately change to the new definition. This function is a no-op on most terminals; it is active only if `can_change_color()' returns `1'. `init_pair(pair_number, fg, bg)' Changes the definition of a color-pair. It takes three arguments: the number of the color-pair to be changed, the foreground color number, and the background color number. The value of PAIR_NUMBER must be between `1' and `COLOR_PAIRS - 1' (the `0' color pair is wired to white on black and cannot be changed). The value of FG and BG arguments must be between `0' and `COLORS'. If the color-pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition. `initscr()' Initialize the library. Returns a `WindowObject' which represents the whole screen. `isendwin()' Returns true if `endwin()' has been called (that is, the curses library has been deinitialized). `keyname(k)' Return the name of the key numbered K. The name of a key generating printable ASCII character is the key's character. The name of a control-key combination is a two-character string consisting of a caret followed by the corresponding printable ASCII character. The name of an alt-key combination (128-255) is a string consisting of the prefix `M-' followed by the name of the corresponding ASCII character. `killchar()' Returns the user's current line kill character. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself. `longname()' Returns a string containing the terminfo long name field describing the current terminal. The maximum length of a verbose description is 128 characters. It is defined only after the call to `initscr()'. `meta(yes)' If YES is 1, allow 8-bit characters to be input. If YES is 0, allow only 7-bit chars. `mouseinterval(interval)' Sets the maximum time in milliseconds that can elapse between press and release events in order for them to be recognized as a click, and returns the previous interval value. The default value is 200 msec, or one fifth of a second. `mousemask(mousemask)' Sets the mouse events to be reported, and returns a tuple `(AVAILMASK, OLDMASK)'. AVAILMASK indicates which of the specified mouse events can be reported; on complete failure it returns 0. OLDMASK is the previous value of the given window's mouse event mask. If this function is never called, no mouse events are ever reported. `napms(ms)' Sleep for MS milliseconds. `newpad(nlines, ncols)' Creates and returns a pointer to a new pad data structure with the given number of lines and columns. A pad is returned as a window object. A pad is like a window, except that it is not restricted by the screen size, and is not necessarily associated with a particular part of the screen. Pads can be used when a large window is needed, and only a part of the window will be on the screen at one time. Automatic refreshes of pads (e.g., from scrolling or echoing of input) do not occur. The `refresh()' and `noutrefresh()' methods of a pad require 6 arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. The arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p arguments refer to the upper left corner of the the pad region to be displayed and the s arguments define a clipping box on the screen within which the pad region is to be displayed. `newwin([nlines, ncols,] begin_y, begin_x)' Return a new window, whose left-upper corner is at `(BEGIN_Y, BEGIN_X)', and whose height/width is NLINES/NCOLS. By default, the window will extend from the specified position to the lower right corner of the screen. `nl()' Enter newline mode. This mode translates the return key into newline on input, and translates newline into return and line-feed on output. Newline mode is initially on. `nocbreak()' Leave cbreak mode. Return to normal "cooked" mode with line buffering. `noecho()' Leave echo mode. Echoing of input characters is turned off, `nonl()' Leave newline mode. Disable translation of return into newline on input, and disable low-level translation of newline into newline/return on output (but this does not change the behavior of `addch('\n')', which always does the equivalent of return and line feed on the virtual screen). With translation off, curses can sometimes speed up vertical motion a little; also, it will be able to detect the return key on input. `noqiflush()' When the noqiflush routine is used, normal flush of input and output queues associated with the INTR, QUIT and SUSP characters will not be done. You may want to call `noqiflush()' in a signal handler if you want output to continue as though the interrupt had not occurred, after the handler exits. `noraw()' Leave raw mode. Return to normal "cooked" mode with line buffering. `pair_content(pair_number)' Returns a tuple (FG,BG) containing the colors for the requested color pair. The value of PAIR_NUMBER must be between 0 and COLOR_PAIRS-1. `pair_number(attr)' Returns the number of the color-pair set by the attribute value ATTR. `color_pair()' is the counterpart to this function. `putp(string)' Equivalent to `tputs(str, 1, putchar)'; emits the value of a specified terminfo capability for the current terminal. Note that the output of putp always goes to standard output. `qiflush( [flag] )' If FLAG is false, the effect is the same as calling `noqiflush()'. If FLAG is true, or no argument is provided, the queues will be flushed when these control characters are read. `raw()' Enter raw mode. In raw mode, normal line buffering and processing of interrupt, quit, suspend, and flow control keys are turned off; characters are presented to curses input functions one by one. `reset_prog_mode()' Restores the terminal to "program" mode, as previously saved by `def_prog_mode()'. `reset_shell_mode()' Restores the terminal to "shell" mode, as previously saved by `def_shell_mode()'. `setsyx(y, x)' Sets the virtual screen cursor to Y, X. If Y and X are both -1, then leaveok is set. `setupterm([termstr, fd])' Initializes the terminal. TERMSTR is a string giving the terminal name; if omitted, the value of the TERM environment variable will be used. FD is the file descriptor to which any initialization sequences will be sent; if not supplied, the file descriptor for `sys.stdout' will be used. `start_color()' Must be called if the programmer wants to use colors, and before any other color manipulation routine is called. It is good practice to call this routine right after `initscr()'. `start_color()' initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and two global variables in the `curses' module, `COLORS' and `COLOR_PAIRS', containing the maximum number of colors and color-pairs the terminal can support. It also restores the colors on the terminal to the values they had when the terminal was just turned on. `termattrs()' Returns a logical OR of all video attributes supported by the terminal. This information is useful when a curses program needs complete control over the appearance of the screen. `termname()' Returns the value of the environment variable TERM, truncated to 14 characters. `tigetflag(capname)' Returns the value of the Boolean capability corresponding to the terminfo capability name CAPNAME. The value `-1' is returned if CAPNAME is not a Boolean capability, or `0' if it is canceled or absent from the terminal description. `tigetnum(capname)' Returns the value of the numeric capability corresponding to the terminfo capability name CAPNAME. The value `-2' is returned if CAPNAME is not a numeric capability, or `-1' if it is canceled or absent from the terminal description. `tigetstr(capname)' Returns the value of the string capability corresponding to the terminfo capability name CAPNAME. `None' is returned if CAPNAME is not a string capability, or is canceled or absent from the terminal description. `tparm(str[,...])' Instantiates the string STR with the supplied parameters, where STR should be a parameterized string obtained from the terminfo database. E.g. `tparm(tigetstr("cup"), 5, 3)' could result in `'\033[6;4H'', the exact result depending on terminal type. `typeahead(fd)' Specifies that the file descriptor FD be used for typeahead checking. If FD is `-1', then no typeahead checking is done. The curses library does "line-breakout optimization" by looking for typeahead periodically while updating the screen. If input is found, and it is coming from a tty, the current update is postponed until refresh or doupdate is called again, allowing faster response to commands typed in advance. This function allows specifying a different file descriptor for typeahead checking. `unctrl(ch)' Returns a string which is a printable representation of the character CH. Control characters are displayed as a caret followed by the character, for example as `^C'. Printing characters are left as they are. `ungetch(ch)' Push CH so the next `getch()' will return it. *Note:* only one CH can be pushed before `getch()' is called. `ungetmouse(id, x, y, z, bstate)' Push a `KEY_MOUSE' event onto the input queue, associating the given state data with it. `use_env(flag)' If used, this function should be called before `initscr()' or newterm are called. When FLAG is false, the values of lines and columns specified in the terminfo database will be used, even if environment variables `LINES' and `COLUMNS' (used by default) are set, or if curses is running in a window (in which case default behavior would be to use the window size if `LINES' and `COLUMNS' are not set).