X-Git-Url: https://osm.etsi.org/gitweb/?a=blobdiff_plain;f=README.md;h=c8ec7e8352e982b84b8c8f5a5efca199bf91b2b2;hb=HEAD;hp=b742339d730e1fb2f6d13733f443fe10e305f037;hpb=eeb2c002b1ee84406f22a64e1cea69cc0687d63c;p=osm%2Fosmclient.git

diff --git a/README.md b/README.md
index b742339..c8ec7e8 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,68 @@
+<!--
+Copyright 2020 ETSI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied.
+See the License for the specific language governing permissions and
+limitations under the License
+-->
 # python-osmclient
-A python client for osm orchestration
 
+OSM client library and console script
 
-# Installation
+## Installation
 
-## Install dependencies
 ```bash
-sudo apt-get install python-dev libcurl4-gnutls-dev python-pip libgnutls-dev python-prettytable   
-sudo pip install pycurl
+# Ubuntu pre-requirements
+sudo apt-get install python3-pip
+# Centos pre-requirements
+# sudo yum install python3-pip
 ```
 
-## Install python-osmclient
-    sudo pip install git+https://github.com/mfmarche/python-osmclient
+Clone the osmclient repo:
+
+```bash
+git clone https://osm.etsi.org/gerrit/osm/osmclient
+cd osmclient
+```
 
-# Setup
-Set the OSM_HOSTNAME variable to the host of the osm server.
+Finally install osmclient with pip. For development, you should install osmclient in editable mode (`--user -e`):
 
-Example
 ```bash
-localhost$ export OSM_HOSTNAME=<hostname>:8008
+# Install osmclient
+python3 -m pip install --user . -r requirements.txt -r requirements-dev.txt
+# Install osmclient in editable mode (-e)
+# python3 -m pip install --user -e . -r requirements.txt -r requirements-dev.txt
+# logout and login so that PATH can be updated. Executable osm will be found in /home/ubuntu/.local/bin
 ```
 
-# Examples 
+After logging out and in, you can check that osm is running with:
+
+```bash
+which osm
+osm version
+```
+
+## Setup
+
+Set the OSM_HOSTNAME variable to the host of the OSM server (default: localhost).
+
+```bash
+localhost$ export OSM_HOSTNAME=<hostname>
+```
+
+## Examples
+
+### upload vnfd
 
-## upload vnfd
 ```bash
 localhost$ osm upload-package ubuntu_xenial_vnf.tar.gz
 {'transaction_id': 'ec12af77-1b91-4c84-b233-60f2c2c16d14'}
@@ -35,7 +74,8 @@ localhost$ osm vnfd-list
 +--------------------+--------------------+
 ```
 
-## upload nsd
+### upload nsd
+
 ```bash
 localhost$ osm upload-package ubuntu_xenial_ns.tar.gz
 {'transaction_id': 'b560c9cb-43e1-49ef-a2da-af7aab24ce9d'}
@@ -46,7 +86,8 @@ localhost$ osm nsd-list
 | ubuntu_xenial_nsd | ubuntu_xenial_nsd |
 +-------------------+-------------------+
 ```
-## vim-list
+
+### vim-list
 
 ```bash
 localhost$ osm vim-list
@@ -57,8 +98,8 @@ localhost$ osm vim-list
 +-------------+-----------------+--------------------------------------+
 ```
 
+### instantiate ns
 
-## instantiate ns
 ```bash
 localhost$ osm ns-create ubuntu_xenial_nsd testns openstack-site
 {'success': ''}
@@ -70,8 +111,66 @@ localhost$ osm ns-list
 +------------------+--------------------------------------+-------------------+--------------------+---------------+
 ```
 
-# Bash Completion
-python-osmclient uses [click](http://click.pocoo.org/5/).  You can setup bash completion by putting this in your .bashrc:
-    
-    eval "$(_OSM_COMPLETE=source osm)"
+## Using osmclient as a library to interact with OSM
+
+Assuming that you have installed python-osmclient package, it's pretty simple to write some Python code to interact with OSM.
+
+### Simple Python code to get the list of NS packages
+
+```python
+from osmclient import client
+from osmclient.common.exceptions import ClientException
+hostname = "127.0.0.1"
+myclient = client.Client(host=hostname, sol005=True)
+resp = myclient.nsd.list()
+print yaml.safe_dump(resp, indent=4, default_flow_style=False)
+```
+
+### Simple Python code to get the list of VNF packages from a specific user and project
+
+The code will print for each package a pretty table, then the full details in yaml
+
+```python
+from osmclient import client
+from osmclient.common.exceptions import ClientException
+import yaml
+from prettytable import PrettyTable
+hostname = "127.0.0.1"
+user = admin
+password = admin
+project = admin
+kwargs = {}
+if user is not None:
+    kwargs['user']=user
+if password is not None:
+    kwargs['password']=password
+if project is not None:
+   kwargs['project']=project
+myclient = client.Client(host=hostname, sol005=True, **kwargs)
+resp = myclient.vnfd.list()
+print yaml.safe_dump(resp, indent=4, default_flow_style=False)
+```
+
+## Enable autocompletion
+
+You can enable autocompletion in OSM client by creating a file osm-complete.sh in the following way:
+
+```bash
+mkdir -p $HOME/.bash_completion.d
+_OSM_COMPLETE=source osm > $HOME/.bash_completion.d/osm-complete.sh
+```
+
+Then you can add the following to your $HOME/.bashrc file:
+
+```bash
+. .bash_completion.d/osm-complete.sh
+```
+
+## Future work
+
+- Option `-c` for list and show operations to filter output and show only selected columns
+- Option `-o <FORMAT>` to adapt output format (table, csv, yaml, json, jsonpath)
+- Command ns-status to show the deployment status (RO) and configuration status (VCA) in an appealing format
+- See how to deprecate commands and options: <https://stackoverflow.com/questions/50366719/correct-way-to-deprecate-parameter-alias-in-click>
+- Evaluate the possibility to re-structure code to uniform all commands: `check`, `table_headers`, `run`, `output`