Python

The pySROS libraries are delivered and preinstalled on SR OS nodes. This libraries can be installed on another device, such as a PC or UNIX workstation.

Use one of the following methods to install the pySROS libraries:

1. from the Python Package Index (PyPI) using the pip tool (preferred method)

   To do this, execute the pip install pysros command on the device.

2. from source code delivered from github.com

   To do this, clone the source code repository to your device by executing the git clone https://github.com/nokia/pysros command.

   The source code can then be compiled and installed by executing python3 setup.py install.

3. from source code delivered from the Nokia online support portal

   To do this, obtain the source code from the Nokia online support portal. This is the same location where the SR OS software resides.

   The source code can then be compiled and installed by executing python3 setup.py install.

The pySROS libraries must be imported to use the provided API in developed applications.

The libraries may be imported using the import pysros command, or only specific elements of the API may be imported; for example, from pysros.management import connect.

This chapter provides a high-level overview about how to connect to the model-driven interfaces of an SR OS device and manipulate simple data structures. Detailed technical documentation for the pySROS API is provided within the source code bundle in the docs directory.

The API documentation is provided as source code and should be built as needed. To compile the API documentation, run the following commands from the docs directory:

• pip install -r requirements.txt

• make html

The API documentation is compiled into the build/html folder in HTML format.

To enable access to an SR OS device, the user must create a Connection object, which is a Python object that references the application’s connection to a specific SR OS node.

The underlying connection transport protocol is NETCONF.

The connect() API method is provided to create this Connection object.

The following example shows the creation of a connection named connection_object to a device with the IP address 192.168.168.1.

from pysros.management import connect
connection_object = connect(host='192.168.168.1', username='admin', password='admin')

The following table describes the arguments available for the connect() API method.

When a Python application makes a connection to an SR OS device using the connect() method, the application performs the following actions.

• The device is queried to identify a set of modules required to manage the device. This is performed by identifying the module-set-id (yang-library:1.0) or content-id (yang-library:1.1) from the devices advertised capabilities.

• The set of modules are queried using /modules-state from the IETF YANG library RFC 8525.

• The local schema cache is checked to determine whether a model-driven management schema is already generated for the same set of YANG modules. If no identical local schema cache exists, or if the rebuild argument is set to True, the following occurs.

  • If the yang_directory argument is not provided to the connect() API method, each YANG module listed by the SR OS node is downloaded directly from the node.

  • If the yang_directory argument is provided to the connect() API method, the YANG module files from this directory that correspond to the list of required modules obtained from the router are used.

• The YANG modules are compiled into a schema cache for use by the developer and the pySROS libraries.

The local model-driven schema cache is stored in the .pysros directory within the developer’s local home directory. If this directory is deleted or modified, the cache is rebuilt on the next connect() API call.

Use the get() API method to obtain modeled data from an SR OS device.

The get() API method accepts as inputs a JSON instance identifier path and a datastore. The method returns a Python data structure, which uses the pySROS format to provide modeled data to the developer. See The pySROS data structure for more information.

A JSON instance path is obtained from an SR OS node using the pwc json-instance-path command. See the 7450 ESS, 7750 SR, 7950 XRS, and VSR MD-CLI User Guide for more information.

The following example obtains data from an SR OS node Connection object.

my_data = connection_object.running.get('/nokia-state:state/system/oper-name')

In addition to device configuration and state information collection, operators can perform the following types of node operations:

• a YANG-modeled operation (defined as an 'action' in a YANG model), which uses structured data for both input and output
• an MD-CLI command, which provides semi-structured input and unstructured output

Nokia recommends using the action() API method when performing operations with SR OS. Some cases may require using an unmodeled MD-CLI command, which can be performed using the cli() API method and manipulating the resulting string output.

Python data structures, in pySROS format, and specific values within the data structures can be configured on an SR OS device.

The set() API method is provided to configure a node. The set() API method aggregates several model-driven transactional operations into a single method:

• configuration of the node (performed in private candidate configuration mode)

• update, validate, and commit

The set() API method accepts as input a JSON instance path, a datastore, and a payload. The payload may be a single value, a key and value pair, a crafted Python data structure following the pySROS data-structure format, or a pySROS data structure object received from a get() API method call.

The following examples show how to set the system name to ‟hostname”.

connection_object.candidate.set("/nokia-conf:configure/system/name", "hostname")
connection_object.candidate.set("/nokia-conf:configure/system", {‛name’:‛hostname’})
connection_object.candidate.set("/nokia-
conf:configure", {‛system’: {‛name’: ‛hostname’}})

The pyexec command can accept a maximum of ten input arguments provided using the MD-CLI command line. The Python application developer must handle these as standard input (STDIN) arguments.

Python applications can be entered as an output modifier to the MD-CLI commands.

The following is an example output from an info command that is processed by a Python application, which capitalizes the output.

(ex)[/]
A:admin@node-2# file show cf3:\capitals.py
File: capitals.py
-------------------------------------------------------------------------------
import sys
def main():
  for line in sys.stdin:
    print(line.upper(), end="")
main()
===============================================================================
(ex)[/]
A:admin@node-2# show version | pyexec capitals.py
TIMOS-B-21.7.B1-9 BOTH/X86_64 NOKIA 7750 SR COPYRIGHT (C) 2000-2021 NOKIA.
ALL RIGHTS RESERVED. ALL USE SUBJECT TO APPLICABLE LICENSE AGREEMENTS.
BUILT ON THU JUN 12 18:35:55 PDT 2021 BY BUILDER IN /BUILDS/C/217B/B1-9/PANOS/MAIN/SROS

The pyexec command supports chaining multiple applications on the command line. Python applications called with the pyexec command can produce data on the standard output (STDOUT) stream and consume data on the standard input (STDIN) stream. Multiple Python applications can then be chained together.

Python applications executed using the pyexec command use the built-in MD-CLI pager to display the output one page at a time. This behavior can be disabled per Python application using the no-more output modifier, or globally by setting the MD-CLI environment more option to false, as required.

When the MD-CLI display output is paused by the pager while executing a Python application, pressing q closes the pager and resumes executing the Python application. Pressing Ctrl-c closes the pager and terminates the Python application.

To make a connection to the model-driven interface of an SR OS device, user authentication is required.

User authentication is deemed to have already occurred if the Python application is executed directly on the SR OS node.

If the Python application is executed remotely, user credentials must be provided to the connect() API call.

To successfully use a Python application, the authenticated user must have authorization to both execute the application and perform each of the model-driven operations contained within the Python application.