diff --git a/doc/source/conf.py b/doc/source/conf.py index 64d35ed..3998803 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -78,4 +78,4 @@ html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] diff --git a/doc/source/examples.rst b/doc/source/examples.rst new file mode 100644 index 0000000..7c9a34a --- /dev/null +++ b/doc/source/examples.rst @@ -0,0 +1,110 @@ +Examples +======== + +`hello_wexpect.py `_ + + This is the simplest example. It starts a windows command interpreter (aka. cmd) lists the current + directory and exits. + + .. code-block:: python + + import wexpect + + # Start cmd as child process + child = wexpect.spawn('cmd.exe') + + # Wait for prompt when cmd becomes ready. + child.expect('>') + + # Prints the cmd's start message + print(child.before, end='') + print(child.after, end='') + + # run list directory command + child.sendline('ls') + + # Waiting for prompt + child.expect('>') + + # Prints content of the directory + print(child.before, end='') + print(child.after, end='') + + # Exit from cmd + child.sendline('exit') + + # Waiting for cmd termination. + child.wait() + + +`terminaton.py `_ + + This script shows three method to terminate your application. `terminate_programmatically()` + shows the recommended way, which kills the child by sending the application specific exit command. + After that waiting for the terminaton is recommended. + `terminate_eof()` shows how to terminate child program by sending EOF character. Some program can be + terminated by sending EOF character. Waiting for the terminaton is recommended in this case too. + `terminate_terminate()` shows how to terminate child program by sending kill signal. Some + application requires sending SIGTERM to kill the child process. `terminate()` call `kill()` + function, which sends SIGTERM to child process. Waiting for the terminaton is not required + explicitly in this case. The wait is included in `terminate()` function. + + .. code-block:: python + + import wexpect + + def terminate_programmatically(): + '''Terminate child program by command. This is the recommended method. Send your application's + exit command to quit the child's process. After that wait for the terminaton. + ''' + print('terminate_programmatically') + + # Start cmd as child process + child = wexpect.spawn('cmd.exe') + + # Wait for prompt when cmd becomes ready. + child.expect('>') + + # Exit from cmd + child.sendline('exit') + + # Waiting for cmd termination. + child.wait() + + def terminate_eof(): + '''Terminate child program by sending EOF character. Some program can be terminated by sending + an EOF character. Waiting for the terminaton is recommended in this case too. + ''' + print('terminate_eof') + + # Start cat as child process + child = wexpect.spawn('cat') + + # Exit by sending EOF + child.sendeof() + + # Waiting for cmd termination. + child.wait() + + + def terminate_terminate(): + '''Terminate child program by sending kill signal. Some application requires sending SIGTERM to kill + the child process. `terminate()` call `kill()` function, which sends SIGTERM to child process. + Waiting for the terminaton is not required explicitly in this case. The wait is included in + `terminate()` function. + ''' + print('terminate_terminate') + + # Start cmd as child process + child = wexpect.spawn('cmd.exe') + + # Wait for prompt when cmd becomes ready. + child.expect('>') + + # Exit from cmd + child.terminate() + + + terminate_programmatically() + terminate_eof() + terminate_terminate() diff --git a/doc/source/index.rst b/doc/source/index.rst index 2bd3c0c..5ea1113 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -56,6 +56,7 @@ Contents: api/index history + examples Wexpect is developed `on Github `_. Please report `issues `_ there as well. diff --git a/examples/termination.py b/examples/termination.py new file mode 100644 index 0000000..1247b58 --- /dev/null +++ b/examples/termination.py @@ -0,0 +1,68 @@ +''' This script shows three method to terminate your application. `terminate_programmatically()` +shows the recommended way, which kills the child by sending the application specific exit command. +After that waiting for the terminaton is recommended. +`terminate_eof()` shows how to terminate child program by sending EOF character. Some program can be +terminated by sending EOF character. Waiting for the terminaton is recommended in this case too. +`terminate_terminate()` shows how to terminate child program by sending kill signal. Some +application requires sending SIGTERM to kill the child process. `terminate()` call `kill()` +function, which sends SIGTERM to child process. Waiting for the terminaton is not required +explicitly in this case. The wait is included in `terminate()` function. +''' + +import wexpect + +def terminate_programmatically(): + '''Terminate child program by command. This is the recommended method. Send your application's + exit command to quit the child's process. After that wait for the terminaton. + ''' + print('terminate_programmatically') + + # Start cmd as child process + child = wexpect.spawn('cmd.exe') + + # Wait for prompt when cmd becomes ready. + child.expect('>') + + # Exit from cmd + child.sendline('exit') + + # Waiting for cmd termination. + child.wait() + +def terminate_eof(): + '''Terminate child program by sending EOF character. Some program can be terminated by sending + an EOF character. Waiting for the terminaton is recommended in this case too. + ''' + print('terminate_eof') + + # Start cmd as child process + child = wexpect.spawn('cat') + + # Exit from cmd + child.sendeof() + + # Waiting for cmd termination. + child.wait() + + +def terminate_terminate(): + '''Terminate child program by sending kill signal. Some application requires sending SIGTERM to kill + the child process. `terminate()` call `kill()` function, which sends SIGTERM to child process. + Waiting for the terminaton is not required explicitly in this case. The wait is included in + `terminate()` function. + ''' + print('terminate_terminate') + + # Start cmd as child process + child = wexpect.spawn('cmd.exe') + + # Wait for prompt when cmd becomes ready. + child.expect('>') + + # Exit from cmd + child.terminate() + + +terminate_programmatically() +terminate_eof() +terminate_terminate()