resources/tools/papi/doc/python_api_hld.rst

   1 Python API high level description
   2 =================================
   3
   4 Overview
   5 --------
   6
   7 `Python API <https://wiki.fd.io/view/VPP/Python_API>`_ provides python binding
   8 for VPP API via vpp-papi module in ``vpp-api/python/``.
   9
  10 Each Python API call uses arguments as specified in the API definitions file
  11 (e.g. vpe.api). The "client_index" and "context" fields are handled by the
  12 module itself.
  13
  14 ::
  15
  16     vpp.api.show_version()
  17     vpp.api.sw_interface_dump(name_filter_valid=1,
  18         name_filter="GigabitEthernet0/10/0")
  19
  20
  21 A call returns a named tuple or a list of named tuples.
  22
  23 ::
  24
  25     show_version_reply(_0=832, context=1, retval=0, program='vpe\x00\x00\x00\x00
  26         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  27         \x00\x00\x00\x00\x00\x00\x00', version='18.10-rc0~593-gb7620fd~b5386\x00
  28         \x00\x00\x00', build_date='Fri Oct  5 18:40:55 UTC 2018\x00\x00\x00
  29         \x00',build_directory='/w/workspace/vpp-merge-master-ubuntu1604\x00\x00
  30         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  31         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  32         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  33         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  34         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  35         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  36         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  37         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  38         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  39         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  40         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  41         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
  42     [sw_interface_details(_0=86, context=5, sw_if_index=3, sup_sw_if_index=3,
  43         l2_address_length=6, l2_address="\x08\x00'\x1f\xdf\xf5\x00\x00",
  44         interface_name='GigabitEthernet0/10/0\x00\x00\x00\x00\x00\x00\x00\x00
  45         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  46         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00',
  47         admin_up_down=0, link_up_down=0, link_duplex=2, link_speed=4,
  48         link_mtu=9202, mtu=[9000, 0, 0, 0], sub_id=0, sub_dot1ad=0,
  49         sub_dot1ah=0, sub_number_of_tags=0, sub_outer_vlan_id=0,
  50         sub_inner_vlan_id=0, sub_exact_match=0, sub_default=0,
  51         sub_outer_vlan_id_any=0, sub_inner_vlan_id_any=0, vtr_op=0,
  52         vtr_push_dot1q=0, vtr_tag1=0, vtr_tag2=0, tag='\x00\x00\x00\x00\x00\x00
  53         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  54         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  55         \x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
  56         \x00\x00\x00\x00', outer_tag=0, b_dmac='\x00\x00\x00\x00\x00\x00',
  57         b_smac='\x00\x00\x00\x00\x00\x00', b_vlanid=0, i_sid=0)]
  58
  59
  60 Implementation in CSIT
  61 ----------------------
  62
  63 Usage of Python API in CSIT requires splitting the implementation into two
  64 parts:
  65
  66 1) Executable python script that will run on remote host (DUT) where VPP is
  67    installed and running.
  68
  69 2) Papi library that will be used on local host (e.g. jenkins slave) where Robot
  70    Framework is running.
  71
  72 Executable python script provides:
  73
  74 - creation of VPP API object,
  75 - connection to / disconnection from VPP API object,
  76 - execution of API functions and returning the reply message(s).
  77
  78 PAPI library is responsible for:
  79
  80 - providing necessary API data (API name, API arguments),
  81 - processing of received reply message(s).
  82
  83 Data between executable python script and PAPI library is exchanged in JSON
  84 format.
  85
  86 JSON data in direction from Robot framework executor library to remote python
  87 script running on DUT (API request) consist of list of dictionaries with APIs
  88 and their arguments:
  89
  90 ::
  91
  92     [
  93         {
  94             "api_name": "show_version",
  95             "api_args": {}
  96         },
  97         {
  98             "api_name": "sw_interface_dump",
  99             "api_args": {
 100                 "name_filter_valid": 1,
 101                 "name_filter": "GigabitEthernet0/10/0"
 102                         }
 103         }
 104     ]
 105
 106
 107 where
 108
 109 - api_name is the name of the command to be executed,
 110 - api_args is the dictionary of input arguments with their values for command.
 111
 112 JSON data in direction from remote python script running on DUT to Robot
 113 framework executor library (API reply) consist of list of dictionaries with
 114 API names and replies to these APIs:
 115
 116 ::
 117
 118     [
 119         {
 120             "api_name": "show_version",
 121             "api_reply": show_version_reply(_0=832, context=1, retval=0, program='vpe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', version='18.10-rc0~593-gb7620fd~b5386\x00\x00\x00\x00', build_date='Fri Oct  5 18:40:55 UTC 2018\x00\x00\x00\x00', build_directory='/w/workspace/vpp-merge-master-ubuntu1604\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
 122         },
 123         {
 124             "api_name": "sw_interface_dump",
 125             "api_reply": [sw_interface_details(_0=86, context=2, sw_if_index=3, sup_sw_if_index=3, l2_address_length=6, l2_address="\x08\x00'\x1f\xdf\xf5\x00\x00", interface_name='GigabitEthernet0/10/0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', admin_up_down=0, link_up_down=0, link_duplex=2, link_speed=4, link_mtu=9202, mtu=[9000, 0, 0, 0], sub_id=0, sub_dot1ad=0, sub_dot1ah=0, sub_number_of_tags=0, sub_outer_vlan_id=0, sub_inner_vlan_id=0, sub_exact_match=0, sub_default=0, sub_outer_vlan_id_any=0, sub_inner_vlan_id_any=0, vtr_op=0, vtr_push_dot1q=0, vtr_tag1=0, vtr_tag2=0, tag='\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', outer_tag=0, b_dmac='\x00\x00\x00\x00\x00\x00', b_smac='\x00\x00\x00\x00\x00\x00', b_vlanid=0, i_sid=0)]
 126         }
 127     ]
 128
 129
 130 where
 131
 132 - api_name is the name of executed command,
 133 - api_reply is named tuple or a list of named tuples for executed command.