Packaging (#9)

* Initial commit for packaging

* Fix examples to import pip package

* Update Readme

* Fix README.md issues

Fix some grammar and structural issues.

Author: Karthik Kumaravel

.gitignore

@@ -1,2 +1,5 @@
 *.pyc
 __pycache__
+dist/
+*.egg
+*.egg-info

README.md

@@ -1,78 +1,95 @@
-Grpc for Cisco IOS-XR in python
---
+## gRPC for Cisco IOS-XR in Python
+
 Author: Karthik Kumaravel
 
-Contact: kkumara3@cisco.com
+This package contains a library with the methods that are available to use over gRPC with IOS-XR boxes after 6.0.0. The API has several methods which allows a user to send simple RPC commands such as ```get``` and ```push``` using YANG and JSON.
 
-This is a small repo showing how to use GRPC in python for the IOS-XR end node.The repo is consisted of three main componenets, the compiled pb2 file from the IDL, a python client accessing the pb2 file, and an example python file. The example is a small python file showing how to set up the connection and use one of the rpc calls. Please look at the unit-testing and client page for more rpc calls. At the bottom of the repo, there is a walkthrough of how to create your own client. 
+The repo consists of two main components:
+1. The compiled pb2 file from the proto definition.
+2. A Python module accessing the pb2 file with the library bindings.
 
-If you find any problems with this repo, please file a bug so I can fix it. If you need help, feel free to contact me. 
+The repo also includes examples on how to use the library to interact with an IOS-XR device. If you want to create your own client, there is a walkthrough [at the bottom of this page](#creating-your-own-client).
 
+If you find any problems or need help, create an issue!
 
-GRPC Calls
---
-The file is called example_grpc.py. This file has an excamples of the different rpc calls. This configuration shows how to get things started with self signed certs.
+## Installation
+Either download this repository or install with ```pip install iosxr_grpc```
 
-- Download the repository
-- Install grpc
+It is always recommended to work in a virtual environment with something like [virtualenv](https://virtualenv.pypa.io/en/stable/) or [pipenv](http://docs.pipenv.org/en/latest/).
 
-```
-pip install grpcio
-```
-(sudo may be required)
-- ssh into the router and turn on grpc and tls on the router, below is an example configuration.
 
+## gRPC Calls
+
+### Enable gRPC
+
+SSH in to the router and turn on gRPC, below is an example configuration:
 ```
 interface GigabitEthernet 0/0/0/0
  ipv4 address 192.168.1.2 255.255.255.0
  no shut
 
 grpc
- tls
  port 57777
  !
 !
 ```
 
-- Copy the autogenerated .pem file to the 'keys' folder in the client directory.
+Note: Default port is 57400, and IPv4 only.
 
+#### Using TLS
+
+1. Enable TLS in configuration, example:
 ```
-scp cisco@192.168.1.2:/misc/config/grpc/ems.pem ./
+grpc
+  tls
+  port 57777
+  !
+!
 ```
 
-(note if you don't want to use TLS, don't pass the cred and options)
+2. Copy the autogenerated .pem file to the 'keys' folder in the client directory.
 
-- If you are using your own box, change the parameters in the example.py file to have the proper authentication credentials.
-- Run the program
+```
+scp cisco@192.168.1.2:/misc/config/grpc/ems.pem ./
+```
+
+### Usage
+```from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient```
 
 ```
-python grpc_example.py
+from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
+client = CiscoGRPCClient(
+    <ip address>,
+    <port>,
+    <timeout>,
+    <username>,
+    <password>,
+    <optional: tls key>,
+    <optional: tls server name ('ems.cisco.com')>)
+path = <yang path> # '{"openconfig-interfaces:interfaces": [null]}')
+err, result = client.<operation>(path) # client.getconfig(path)
 ```
-For a more in-depth look, check out the wiki https://github.com/cisco-grpc-connection-libs/ios-xr-grpc-python/wiki
 
-Getting here from the beginning
---
+For a more in-depth look, [check out the wiki](https://github.com/cisco-grpc-connection-libs/ios-xr-grpc-python/wiki)!
+
+## Creating your own Client
+
 To create a client of your own there are a few steps to follow.
 
 - Download the proto file for IOS-XR's grpc: https://github.com/CiscoDevNet/grpc-getting-started
 - Follow the instructions to generate the client/server code in python using the grpc-getting-started's proto file: http://www.grpc.io/docs/tutorials/basic/python.html#generating-client-and-server-code
 - From here create a client, an example can be found here: http://www.grpc.io/docs/tutorials/basic/python.html#creating-the-client
- -  At this point you should have a client similar to the one in this repo
+- At this point you should have a client similar to the one in this repo
+
+## Useful Links
 
-Other Useful Links
---
 If you would like to test this all out with IOS-XRv, use the following link to request access to the vagrant box.
 
 https://xrdocs.github.io/
 
-Projects that use the python client
---
-[Solenoid](https://github.com/ios-xr/Solenoid)
-
-To be done
---
-Here is a list of current work to be done
-- Add example vagrant setup
-- Examples of all the different tests
-- More unit testing
-- Documentation around MDT telemetry
+## Projects that use the python client
+
+[Solenoid](https://github.com/ios-xr/Solenoid) - App that injects routes directly into Cisco's IOS-XR RIB table.
+
+[Pipedown](https://github.com/cisco-ie/Pipedown) - CDN router monitoring tool for data center connectivity.
+

examples/cli.py

@@ -21,13 +21,11 @@
 Note: Version 1.0 supports get-oper, get-config, and merge-config RPCs, replace-config hopefully coming soon
 """
 
-import json
 from grpc.framework.interfaces.face.face import AbortionError
-import sys
-sys.path.insert(0, '../')
-from lib.cisco_grpc_client import CiscoGRPCClient
+from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
 from docopt import docopt
 
+
 def main():
 
     __version__ = 'GRPC_Client 1.0'
@@ -50,17 +48,15 @@ def main():
         else:
             path = 'Error'
             print(
-                'get-oper argument must include --file option and json file to filter yang operational namespace'
-                )
+                'get-oper argument must include --file option and json file to filter yang operational namespace')
         try:
             err, result = client.getoper(path)
             if err:
                 print(err)
             print(result)
         except AbortionError:
             print(
-                'Unable to connect to local box, check your gRPC destination.'
-                )
+                'Unable to connect to local box, check your gRPC destination.')
 
     if RPC == "get-config":
 
@@ -78,8 +74,7 @@ def main():
             print(result)
         except AbortionError:
             print(
-                'Unable to connect to local box, check your gRPC destination.'
-                )
+                'Unable to connect to local box, check your gRPC destination.')
 
     if RPC == "merge-config":
 
@@ -89,17 +84,15 @@ def main():
         else:
             path = 'Error'
             print(
-                'get-oper argument must include --file option and json file to filter yang operational namespace'
-                )
+                'get-oper argument must include --file option and json file to filter yang operational namespace')
         try:
             err = client.mergeconfig(path)
             if err:
                 print(err)
-            #print result
+            # print result
         except AbortionError:
             print(
-                'Unable to connect to local box, check your gRPC destination.'
-                )
+                'Unable to connect to local box, check your gRPC destination.')
 
     if RPC == "replace-config":
 
@@ -109,16 +102,15 @@ def main():
         else:
             path = 'Error'
             print(
-                'get-oper argument must include --file option and json file to filter yang operational namespace'
-                )
+                'get-oper argument must include --file option and json file to filter yang operational namespace')
         try:
             err = client.replaceconfig(path)
             if err:
                 print(err)
         except AbortionError:
             print(
-                'Unable to connect to local box, check your gRPC destination.'
-                )
+                'Unable to connect to local box, check your gRPC destination.')
+
 
 if __name__ == '__main__':
     main()

examples/grpc_cfg.py

@@ -5,10 +5,7 @@
 '''
 from grpc.framework.interfaces.face.face import AbortionError
 import json
-from time import sleep
-import sys
-sys.path.insert(0, '../')
-from lib.cisco_grpc_client import CiscoGRPCClient
+from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
 
 
 class Example(object):

examples/grpc_cfgclireplace.py

@@ -3,9 +3,7 @@
     """
     import json
     from grpc.framework.interfaces.face.face import AbortionError
-    import sys
-    sys.path.insert(0, '../')
-    from lib.cisco_grpc_client import CiscoGRPCClient
+    from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
 
     def main():
             '''

examples/grpc_example.py

@@ -3,9 +3,7 @@
 """
 import json
 from grpc.framework.interfaces.face.face import AbortionError
-import sys
-sys.path.insert(0, '../')
-from lib.cisco_grpc_client import CiscoGRPCClient
+from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
 
 def main():
     '''

examples/route_policy.py

@@ -10,15 +10,13 @@
     from collections import OrderedDict
 except ImportError:
     from ordereddict import OrderedDict
-import sys
-sys.path.insert(0, '../')
-from lib.cisco_grpc_client import CiscoGRPCClient
+from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
 
 
 class RoutePolicy(object):
     """Class to manipulate route policy and bgp neighbors using openconfig
     """
-    def __init__(self, host, port, username, password):
+    def __init__(, host, port, username, password):
         """This class creates a grpc client for the functions to use.
             :param host: The ip address for the device.
             :param port: The port for the device.

examples/telemetry_collector.py

@@ -3,13 +3,13 @@
 and output to display. Converts from protobuf to JSON for display.
 """
 
-import sys
-sys.path.insert(0, '../')
-from lib.cisco_grpc_client import CiscoGRPCClient
+from iosxr_grpc.cisco_grpc_client import CiscoGRPCClient
 import json
 
+
 def print_connectivity(connectivity):
-	print connectivity
+    print connectivity
+
 
 # Change client details to match your environment.
 client = CiscoGRPCClient('localhost', 57777, 10, 'vagrant', 'vagrant')
@@ -21,8 +21,7 @@ def print_connectivity(connectivity):
 for segment in client.getsubscription(subscription_id, unmarshal=True):
     # unmarshal is an optional argument, default is unmarshal = True
     # If unmarshal is false, out is in gpb k/v
-	recv_count += 1
-	print(json.dumps(segment, indent=4, separators=(',', ': ')))
-	print('End Telemetry Segment')
-	print(str(recv_count) + ' Segments Received')
-
+    recv_count += 1
+    print(json.dumps(segment, indent=4, separators=(',', ': ')))
+    print('End Telemetry Segment')
+    print(str(recv_count) + ' Segments Received')