Exec_proxy

Exec_proxy is a Python module for remotely executing arbitrary programs. In addition, the module provides some basic functions for creating directories, up- and downloading files, etc.
The module can be used for handling remote scripting tasks, encountered in many areas ranging from system administration to remote execution of a simulation program.

The module uses standard available programs like ssh or rsh to bridge the network, and the Python interpreter at the remote machine.

Example

>>> import os,exec_proxy

>>> # open a connection to 'localhost'
>>> ep = exec_proxy.Exec_proxy('localhost')

>>> print ep.listdir('/')
( ['lost+found', 'dev', 'var', 'tmp', 'etc', 'usr', 'bin', 'lib' ], [ ])

The ep object is available locally, but runs commands at the remote system. Results become available locally for use in the script.

Download

Being a Unix user, the module is mainly oriented towards Unix systems. However, since it is entirely written in Pythonese, it may also be useful for other operating systems.

The module assumes presence of a remote shell program like ssh or rsh, a Python interpreter with the exec_proxy module installed at both the local and the remote system (the module definitely works with Python 2, but may also work with previous versions). For ease of installation, distutils is assumed to be present.

The module can be downloaded in source form: exec_proxy-0.4.0.tar.gz

January 2007: Development has ceased.

Doumentation

The documentation shown below is also included as postscript file with the module.

The exec_proxy module defines the following global variables:

connection_program: The program at the local machine used to set up the network connection. Default value is 'ssh -x'. Should be set before instances of Exec_proxy are created. (The -x prevents X11-forwarding.)
remote_program: The full path of the Python program remote.py (supplied with this package) at the remote machine. The path is assumed to be executable. Default value is `python2 -c "from exec_proxy.remote import run ; run()"', which starts the exec_proxy.run() function. Alternatively, the file remote.py can be started. Should be set before instances of Exec_proxy are created.

The main part of the module becomes available after instantiating the Exec_proxy class:

Exec_proxy(host[, host_is_cmd]): Set up a network connection to host. If host_is_cmd is not specified or 0, and host does not contain a space-character, the connection is set up using the command 'exec_proxy.connection_program+" "+host+" "+exec_proxy.remote_program'. Otherwise (that is, host_is_cmd is non-zero or host contains a space-character), the connection is set up using the command 'host'. In the latter case, the global variables exec_proxy.connection_program and exec_proxy.remote_program are ignored, and the host variable is assumed to contain the entire command to set up a connection.

Exec_proxy Objects

Exec_proxy objects have a lot of methods available. Most of them are related to performing actions at the remote machine. There are also a number of methods related to error handling. Below, first the commands are discussed, followed by an explanation of how errors are handled.

newdir(): Construct a new unique directory at the remote machine for temporarily storing data. Returns the name of the new directory, or the empty string if an error occurred.
mkdir(new_dir): Create the directory new_dir at the remote machine. Returns 0 if the operation succeeded, and a negative number if the operation failed.
chdir(dir_path): Change the current working directory to dir_path at the remote machine. Returns 0 if the operation succeeded, and a negative number if the operation failed.
rmdir(dir_path): Remove the empty directory dir_path from the remote machine. Returns 0 if the operation succeeded, and a negative number if the operation failed.
getcwd(): Return the current working directory at the remote machine. Returns the current working directory, or the empty string if an error occurred.
isdir(path): Tests whether path is an existing directory at the remote machine. Returns 1 if the directory exists, 0 if the directory does not exist, and a negative number if an error occurred.
isfile(path): Tests whether path is an existing file at the remote machine. Returns 1 if the file exists, 0 if the file does not exist, and a negative number if an error occurred.
exists(path): Tests whether path is an existing path at the remote machine. Returns 1 if the path exists, 0 if the path does not exist, and a negative number if an error occurred.
listdir(path): Return the list of files and directories at path at the remote machine. Returns a two-tuple, containing a list of directories and a list of files, or the value None if an error occurred.
chmod(file_path[, mode]): Set the access rights of file_path to mode at the remote machine. If mode is not specified, octal 0600 will be used. Returns 0 if the operation succeeded, and a negative number if the operation failed.
stat(file_path): Return stat info about file_path at the remote machine. Returns None if the operation failed. Interpreting the returned information can be done using the stat module.
mkfifo(file_path[, mode]): Create a FIFO (named pipe) at the remote machine called file_path. If mode is specified, set the mode of the FIFO to its value. If mode is not specified, use octal value 0600. Returns 0 if the operation succeeded, and a negative number if the operation failed.
symlink(old_file_path, new_file_path): Create a symbolic link from old_file_path to new_file_path at the remote machine. Returns 0 if the operation succeeded, and a negative number if the operation failed.
unlink(file_path): Delete file file_path at the remote machine. Returns 0 if the operation succeeded, and a negative number if the operation failed.
upload(local_file, file_path[, overwrite]): Copy the contents of file local_file at the local machine to file file_path at the remote machine. By default, the command will not overwrite existing files. By setting overwrite to 1, you can force the proxy class to copy the file, even if it already exists. Returns 0 if the operation succeeded, and a negative number if the operation failed.
download(file_path, local_file[, overwrite]): Copy the contents of file file_path at the remote machine to file local_file at the local machine. By default, the command will not overwrite existing files. By setting overwrite to 1, you can force the proxy class to copy the file, even if it already exists. Returns 0 if the operation succeeded, and a negative number if the operation failed.
write(data, file_path[, overwrite]): Store the contents of the string data into a file file_path at the remote machine. The operation will not overwrite existing files, except when overwrite is explicitly set to non-zero. Returns 0 if the operation succeeded, and a negative number if the operation failed.
read(file_path): Return the contents of the file file_path from the remote machine. Returns the value None if an error occurred.
run(cmd[, input]): Run command cmd at the remote machine. If input is specified, this data is offered to the command at its stdin. Returns a three-tuple, containing the exit code, the stdout stream, and the stderr stream respectively, if the command could be started. Returns the value None if the execution could not start. Note: If cmd can be started at the remote machine, the command is considered to be succesful (that is, a three-tuple will be returned), even if the started command fails. Be sure to check the exit code and the output streams of the command before concluding that the command ran successfully.

Error handling

When a command fails, a human-readable description of the error becomes available which can be queried using get_error(). Also, the Exec_proxy object switches to error state. Once in error state, every next command will also fail without attempting to execute the command at the remote machine. In this way, the script preserves the state of the remote machine at the time of the error. Also, this behaviour ensures that the first reported error is not overwritten, which may be useful in finding the source of the error. The is_ok() can be used to query whether or not the proxy object is in error state. Finally, returning to normal state is done by using the reset_error() method. To deal with the error state, and to switch back to normal operation, the Exec_proxy object has the following methods:

is_ok(): Returns 1 if no error occurred since the last reset or startup (if reset_error() has never been called). Returns 0 if an error occurred since the last reset or since startup.
get_error(): Returns a human-readable description of the last error. Returns the empty string if no error has occurred.
reset_error(): Resets the error condition. The Exec_proxy object will switch back to normal operation, and all commands will be executed again (until another error occurs).