Internals

Warning

The functions and methods listed in this section are implementation details of pythondialog. Do not use them in your programs, as they are likely to change in incompatible ways without prior notice. The only reason they are documented here is because some public methods or functions refer to them when listing the notable exceptions they may raise.

dialog._to_onoff(val)[source]

Convert boolean expressions to "on" or "off".

Returns

  • "on" if val is True, a non-zero integer, "on" or any case variation thereof;

  • "off" if val is False, 0, "off" or any case variation thereof.

Notable exceptions:

dialog.widget(func)[source]

Decorator to mark Dialog methods that provide widgets.

This allows code to perform automatic operations on these specific methods. For instance, one can define a class that behaves similarly to Dialog, except that after every widget-producing call, it spawns a “confirm quit” dialog if the widget returned Dialog.ESC, and loops in case the user doesn’t actually want to quit.

When it is unclear whether a method should have the decorator or not, the return value is used to draw the line. For instance, among Dialog.gauge_start(), Dialog.gauge_update() and Dialog.gauge_stop(), only the last one has the decorator because it returns a Dialog exit code, whereas the first two don’t return anything meaningful.

Note:

Some widget-producing methods return the Dialog exit code, but other methods return a sequence, the first element of which is the Dialog exit code; the retval_is_code attribute, which is set by the decorator of the same name, allows to programmatically discover the interface a given method conforms to.

New in version 2.14.

dialog.retval_is_code(func)[source]

Decorator for Dialog widget-producing methods whose return value is the Dialog exit code.

This decorator is intended for widget-producing methods whose return value consists solely of the Dialog exit code. When this decorator is not used on a widget-producing method, the Dialog exit code must be the first element of the return value.

New in version 3.0.

Dialog._call_program(cmdargs, *, dash_escape='non-first', use_persistent_args=True, redir_child_stdin_from_fd=None, close_fds=(), **kwargs)[source]

Do the actual work of invoking the dialog-like program.

Communication with the dialog-like program is performed through one pipe(2) and optionally a user-specified file descriptor, depending on redir_child_stdin_from_fd. The pipe allows the parent process to read what dialog writes on its standard error stream 1.

If use_persistent_args is True (the default), the elements of self.dialog_persistent_arglist are passed as the first arguments to self._dialog_prg; otherwise, self.dialog_persistent_arglist is not used at all. The remaining arguments are those computed from kwargs followed by the elements of cmdargs.

If dash_escape is the string "non-first", then every element of cmdargs that starts with '--' is escaped by prepending an element consisting of '--', except the first one (which is usually a dialog option such as '--yesno'). In order to disable this escaping mechanism, pass the string "none" as dash_escape.

If redir_child_stdin_from_fd is not None, it should be an open file descriptor (i.e., an integer). That file descriptor will be connected to dialog’s standard input. This is used by the gauge widget to feed data to dialog, as well as for progressbox() in order to allow dialog to read data from a possibly-growing file.

If redir_child_stdin_from_fd is None, the standard input in the child process (which runs dialog) is not redirected in any way.

If close_fds is passed, it should be a sequence of file descriptors that will be closed by the child process before it exec()s the dialog-like program.

Notable exception:

PythonDialogOSError (if any of the pipe(2) or close(2) system calls fails…)

1

standard ouput stream if use_stdout is True

Dialog._wait_for_program_termination(child_pid, child_output_rfd)[source]

Wait for a dialog-like process to terminate.

This function waits for the specified process to terminate, raises the appropriate exceptions in case of abnormal termination and returns the Dialog exit code and stderr 2 output of the process as a tuple: (hl_exit_code, output_string).

child_output_rfd must be the file descriptor for the reading end of the pipe created by _call_program(), the writing end of which was connected by _call_program() to the child process’s standard error 2.

This function reads the process output on the standard error 2 from child_output_rfd and closes this file descriptor once this is done.

Notable exceptions:

2(1,2,3)

standard output if self.use_stdout is True

Dialog._perform(cmdargs, *, dash_escape='non-first', use_persistent_args=True, **kwargs)[source]

Perform a complete dialog-like program invocation.

This method:

  • invokes the dialog-like program;

  • waits for its termination;

  • removes the temporary file used to pass its argument list, if any;

  • and returns the appropriate Dialog exit code along with whatever output it produced.

See _call_program() for a description of the parameters.

Notable exceptions:

any exception raised by _call_program() or _handle_program_exit()