Cisco provides a Python module that provides access to run EXEC and configuration commands. You can display the details of the Cisco Python module by entering the help() command. The help() command displays the properties of the Cisco CLI module.

The following example displays information about the Cisco Python module:

Device# guestshell run python
                  
Python 2.7.5 (default, Jun 17 2014, 18:11:42) 
[GCC 4.8.2 20140120 (Red Hat 4.8.2-16)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> >>> from cli import cli,clip,configure,configurep, execute, executep 
>>> help(configure) 
Help on function configure in module cli:

configure(configuration)
Apply a configuration (set of Cisco IOS CLI config-mode commands) to the device 
and return a list of results.

configuration = '''interface gigabitEthernet 0/0
no shutdown'''

# push it through the Cisco IOS CLI.
try:
results = cli.configure(configuration)
print "Success!"
except CLIConfigurationError as e:
print "Failed configurations:"
for failure in e.failed:
print failure

Args:
configuration (str or iterable): Configuration commands, separated by newlines.

Returns:
list(ConfigResult): A list of results, one for each line.

Raises:
CLISyntaxError: If there is a syntax error in the configuration.

>>> help(configurep) 
Help on function configurep in module cli:

configurep(configuration)
Apply a configuration (set of Cisco IOS CLI config-mode commands) to the device 
and prints the result.

configuration = '''interface gigabitEthernet 0/0
no shutdown'''

# push it through the Cisco IOS CLI.
configurep(configuration)

Args:
configuration (str or iterable): Configuration commands, separated by newlines.
>>> help(execute) 
Help on function execute in module cli:

execute(command)
Execute Cisco IOS CLI exec-mode command and return the result.

command_output = execute("show version")

Args:
command (str): The exec-mode command to run.

Returns:
str: The output of the command.

Raises:
CLISyntaxError: If there is a syntax error in the command.

>>> help(executep) 
Help on function executep in module cli:

executep(command)
Execute Cisco IOS CLI exec-mode command and print the result.

executep("show version")

Args:
command (str): The exec-mode command to run.


>>> help(cli) 
Help on function cli in module cli:
 
cli(command)
    Execute Cisco IOS CLI command(s) and return the result.
   
    A single command or a delimited batch of commands may be run. The
    delimiter is a space and a semicolon, " ;". Configuration commands must be
    in fully qualified form.
   
    output = cli("show version")
    output = cli("show version ; show ip interface brief")
    output = cli("configure terminal ; interface gigabitEthernet 0/0 ; no shutdown")
   
    Args:
        command (str): The exec or config CLI command(s) to be run.
   
    Returns:
        string: CLI output for show commands and an empty string for
            configuration commands.
   
    Raises:
        errors.cli_syntax_error: if the command is not valid.
        errors.cli_exec_error: if the execution of command is not successful.
 
 
>>> help(clip) 
Help on function clip in module cli:
 
clip(command)
    Execute Cisco IOS CLI command(s) and print the result.
   
    A single command or a delimited batch of commands may be run. The
    delimiter is a space and a semicolon, " ;". Configuration commands must be
    in fully qualified form.
   
    clip("show version")
    clip("show version ; show ip interface brief")
    clip("configure terminal ; interface gigabitEthernet 0/0 ; no shutdown")
   
    Args:
        command (str): The exec or config CLI command(s) to be run.
 

Note	Guest Shell must be enabled for Python to run. For more information, see the Guest Shell chapter.

The Python programming language uses six functions that can execute CLI commands. These functions are available from the Python CLI module. To use these functions, execute the import cli command.

Arguments for these functions are strings of CLI commands. To execute a CLI command through the Python interpreter, enter the CLI command as an argument string of one of the following six functions:

• cli.cli(command) —This function takes an IOS command as an argument, runs the command through the IOS parser, and returns the resulting text. If this command is malformed, a Python exception is raised. The following is sample output from the cli.cli(command) function:

  
  >>> import cli 
  >>> cli.clip('configure terminal; interface loopback 10; ip address 10.10.10.10 255.255.255.255') 
  *Mar 13 18:39:48.518: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback10, changed state to up
  >>> cli.clip('show clock') 
  '\n*18:11:53.989 UTC Mon Mar 13 2017\n'
  >>> output=cli.cli('show clock') 
  >>> print(output) 
  *18:12:04.705 UTC Mon Mar 13 2017
  
  

• cli.clip(command) —This function works exactly the same as the cli.cli(command) function, except that it prints the resulting text to stdout rather than returning it. The following is sample output from the cli.clip(command) function:

  
  >>> cli 
  >>> cli.clip('configure terminal; interface loopback 11; ip address 10.11.11.11 255.255.255.255') 
  *Mar 13 18:42:35.954: %LINEPROTO-5-UPDOWN: Line protocol on Interface Loopback11, changed state to up
  *Mar 13 18:42:35.954: %LINK-3-UPDOWN: Interface Loopback11, changed state to up
  >>> cli.clip('show clock') 
  *18:13:35.313 UTC Mon Mar 13 2017
  >>> output=cli.clip('show clock') 
  *18:19:26.824 UTC Mon Mar 13 2017
  >>> print (output) 
  None
  
  

• cli.execute(command) —This function executes a single EXEC command and returns the output; however, does not print the resulting text No semicolons or newlines are allowed as part of this command. Use a Python list with a for-loop to execute this function more than once. The following is sample output from the cli.execute(command)

  function:

  
  >>> cli.execute("show clock") 
  '15:11:20.816 UTC Thu Jun 8 2017'
  >>>
  >>> cli.execute('show clock'; 'show ip interface brief') 
    File "<stdin>", line 1
      cli.execute('show clock'; 'show ip interface brief') 
                            ^
  SyntaxError: invalid syntax
  >>> 
  
  

• cli.executep(command) —This function executes a single command and prints the resulting text to stdout rather than returning it. The following is sample output from the cli.executep(command) function:

  
  >>> cli.executep('show clock') 
  *18:46:28.796 UTC Mon Mar 13 2017
  >>> output=cli.executep('show clock') 
  *18:46:36.399 UTC Mon Mar 13 2017
  >>> print(output)
  None
  
  

• cli.configure(command) —This function configures the device with the configuration available in commands. It returns a list of named tuples that contains the command and its result as shown below:

   [Think: result = (bool(success), original_command, error_information)]
  
  

  The command parameters can be in multiple lines and in the same format that is displayed in the output of the show running-config command. The following is sample output from the cli.configure(command) function:

  
  >>>cli.configure(["interface GigabitEthernet1/0/7", "no shutdown", "end"]) 
  [ConfigResult(success=True, command='interface GigabitEthernet1/0/7', 
  line=1, output='', notes=None), ConfigResult(success=True, command='no shutdown', 
  line=2, output='', notes=None), ConfigResult(success=True, command='end', 
  line=3, output='', notes=None)]
  
  

• cli.configurep(command) —This function works exactly the same as the cli.configure(command) function, except that it prints the resulting text to stdout rather than returning it. The following is sample output from the cli.configurep(command) function:

  
  >>> cli.configurep(["interface GigabitEthernet1/0/7", "no shutdown", "end"]) 
  Line 1 SUCCESS: interface GigabitEthernet1/0/7
  Line 2 SUCCESS: no shut
  Line 3 SUCCESS: end
  
  

Python run in a virtualized Linux-based environment, Guest Shell. For more information, see the Guest Shell chapter. Cisco provides a Python module that allows user’s Python scripts to run IOS CLI commands on the host device.

Embedded Event Manager (EEM) policies support Python scripts. You can register Python scripts as EEM policies, and execute the registered Python scripts when a corresponding event occurs. The EEM Python script has the same event specification syntax as the EEM TCL policy.

Configured EEM policies run within the Guest Shell. Guest Shell is a virtualized Linux-based environment, designed to run custom Linux applications, including Python for automated control and management of Cisco devices. The Guest Shell container provides a Python interpreter.

The EEM Python package can be imported to Python scripts for running EEM-specific extensions.

Note	The EEM Python package is available only within the EEM Python script (The package can be registered with EEM, and has the EEM event specification in the first line of the script.) and not in the standard Python script (which is run using the Python script name).

The Python package includes the following application programming interfaces (APIs):

• Action APIs—Perform EEM actions and have default parameters.

• CLI-execution APIs—Run IOS commands, and return the output. The following are the list of CLI-execution APIs:

  • eem_cli_open()

  • eem_cli_exec()

  • eem_cli_read()

  • eem_cli_read_line()

  • eem_cli_run()

  • eem_cli_run_interactive()

  • eem_cli_read_pattern()

  • eem_cli_write()

  • eem_cli_close()

• Environment variables-accessing APIs—Get the list of built-in or user-defined variables. The following are the environment variables-accessing APIs:

  • eem_event_reqinfo ()-Returns the built-in variables list.

  • eem_user_variables()-Returns the current value of an argument.

The Python package (is available only within the EEM script, and not available for the standard Python script) supports the following EEM actions:

• Syslog message printing

• Send SNMP traps

• Reload the box

• Switchover to the standby device

• Run a policy

• Track Object read

• Track Object Set

• Cisco Networking Services event generation

The EEM Python package exposes the interfaces for executing EEM actions. You can use the Python script to call these actions, and they are forwarded from the Python package via Cisco Plug N Play (PnP) to the action handler.

An EEM policy can have the following types of variables:

• Event-specific built-in variables—A set of predefinied variables that are populated with details about the event that triggered the policy. The eem_event_reqinfo () API returns the builtin variables list. These variables can be stored in the local machine and used as local variables. Changes to local variables do not reflect in builtin variables.

• User-defined variables—Variables that can be defined and used in policies. The value of these variables can be referred in the Python script. While executing the script, ensure that the latest value of the variable is available. The eem_user_variables() API returns the current value of the argument that is provided in the API.

The following CLI library commands are available within EEM for the Python script to work:

• eem_cli_close()—Closes the EXEC process and releases the VTY and the specified channel handler connected to the command.

• eem_cli_exec—Writes the command to the specified channel handler to execute the command. Then reads the output of the command from the channel and returns the output.

• eem_cli_open—Allocates a VTY, creates an EXEC CLI session, and connects the VTY to a channel handler. Returns an array including the channel handler.

• eem_cli_read()—Reads the command output from the specified CLI channel handler until the pattern of the device prompt occurs in the contents read. Returns all the contents read up to the match.

• eem_cli_read_line()—Reads one line of the command output from the specified CLI channel handler. Returns the line read.

• eem_cli_read_pattern()—Reads the command output from the specified CLI channel handler until the pattern that is to be matched occurs in the contents read. Returns all the contents read up to the match.

• eem_cli_run()—Iterates over the items in the clist and assumes that each one is a command to be executed in the enable mode. On success, returns the output of all executed commands and on failure, returns error.

• eem_cli_run_interactive()—Provides a sublist to the clist which has three items. On success, returns the output of all executed commands and on failure, returns the error. Also uses arrays when possible as a way of making things easier to read later by keeping expect and reply separated.

• eem_cli_write()—Writes the command that is to be executed to the specified CLI channel handler. The CLI channel handler executes the command.