Skip to content

Commit 851961f

Browse files
remingtoncremingtonc
authored
Merge pull request #4 from cisco-ie/develop
Implement Capabilities, Get, Set, Subscribe RPCs and IOS XR convenience functions
2 parents 5b0b69f + aaf3401 commit 851961f

File tree

18 files changed

+3740
-2
lines changed

18 files changed

+3740
-2
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
## Custom
2+
.vscode/
3+
14
# Byte-compiled / optimized / DLL files
25
__pycache__/
36
*.py[cod]

‎.gitmodules

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[submodule "github.com/openconfig/gnmi"]
2+
path = github.com/openconfig/gnmi
3+
url = https://github.com/openconfig/gnmi
4+
branch = master

‎Pipfile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[[source]]
2+
url = "https://pypi.org/simple"
3+
verify_ssl = true
4+
name = "pypi"
5+
6+
[dev-packages]
7+
grpcio-tools = "*"
8+
googleapis-common-protos = "*"
9+
pylint = "*"
10+
black = "==19.3b0"
11+
twine = "*"
12+
setuptools = "*"
13+
wheel = "*"
14+
15+
[packages]
16+
grpcio = "*"
17+
protobuf = "*"
18+
19+
[requires]
20+
python_version = "3.6"

‎Pipfile.lock

Lines changed: 424 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,72 @@
1-
# gnmi-python
2-
gNMI Python connectivity library.
1+
# cisco-gnmi-python
2+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
3+
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
4+
5+
This library wraps gNMI functionality to ease usage with Cisco implementations in Python programs. Derived from [openconfig/gnmi](https://github.com/openconfig/gnmi/tree/master/proto).
6+
7+
## Usage
8+
```bash
9+
pip install cisco-gnmi
10+
python -c "import cisco_gnmi; print(cisco_gnmi)"
11+
```
12+
13+
This library covers the gNMI defined `capabilities`, `get`, `set`, and `subscribe` RPCs, and helper clients provide OS-specific recommendations. As commonalities and differences are identified this library will be refactored as necessary.
14+
15+
It is *highly* recommended that users of the library learn [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) syntax to significantly ease usage. Understanding how to read Protocol Buffers, and reference [`gnmi.proto`](https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto), will be immensely useful for utilizing gNMI and any other gRPC interface.
16+
17+
### Client
18+
`Client` is a very barebones class simply implementing `capabilities`, `get`, `set`, and `subscribe` methods. It provides some context around the expectation for what should be supplied to these RPC functions and helpers for validation.
19+
20+
Methods are documented in [`src/cisco_gnmi/client.py`](src/cisco_gnmi/client.py).
21+
22+
### XRClient
23+
`XRClient` inherets from `Client` and provides several wrapper methods which aid with IOS XR-specific behaviors of the gNMI implementation. These are `delete_xpaths`, `get_xpaths`, `set_json`, and `subscribe_xpaths`. These methods make several assumptions about what kind of information will be supplied to them in order to simplify usage of the gNMI RPCs.
24+
25+
Methods are documented in [`src/cisco_gnmi/xr.py`](src/cisco_gnmi/xr.py).
26+
27+
## gNMI
28+
gRPC Network Management Interface (gNMI) is a service defining an interface for a network management system (NMS) to interact with a network element. It may be thought of as akin to NETCONF or other control protocols which define operations and behaviors. The scope of gNMI is relatively simple - it seeks to "[[define](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md)] a gRPC-based protocol for the modification and retrieval of configuration from a target device, as well as the control and generation of telemetry streams from a target device to a data collection system. The intention is that a single gRPC service definition can cover both configuration and telemetry - allowing a single implementation on the target, as well as a single NMS element to interact with the device via telemetry and configuration RPCs".
29+
30+
gNMI is a specification developed by [OpenConfig](https://openconfig.net), an operator-driven working-group. It is important to note that gNMI only defines a protocol of behavior - not data models. This is akin to SNMP/MIBs and NETCONF/YANG. SNMP and NETCONF are respectively decoupled from the data itself in MIBs and YANG modules. gNMI is a control protocol, not a standardization of data. OpenConfig does develop standard data models as well, and does have some specialized behavior with OpenConfig originating models, but the data models themselves are out of the scope of gNMI.
31+
32+
## Development
33+
Requires Python and utilizes `pipenv` for environment management. Manual usage of `pip`/`virtualenv` is not covered. Uses `black` for code formatting and `pylint` for code linting.
34+
35+
### Get Source
36+
```bash
37+
git clone https://github.com/cisco-ie/cisco-gnmi-python.git
38+
cd cisco-gnmi-python
39+
# If pipenv not installed, install!
40+
pip install --user pipenv
41+
# Now use pipenv
42+
pipenv --three install
43+
# Enter virtual environment
44+
pipenv shell
45+
# Do your thing.
46+
exit
47+
```
48+
49+
### Code Hygiene
50+
We use [`black`](https://github.com/ambv/black) for code formatting and [`pylint`](https://www.pylint.org/) for code linting. `hygiene.sh` will run `black` against all of the code under `gnmi/` except for `protoc` compiled protobufs, and run `pylint` against Python files directly under `gnmi/`. They don't totally agree, so we're not looking for perfection here.
51+
52+
```bash
53+
./hygiene.sh
54+
```
55+
56+
### Recompile Protobufs
57+
If a new `gnmi.proto` definition is released, use `update_protos.sh` to recompile. If breaking changes are introduced the wrapper library must be updated.
58+
59+
```bash
60+
./update_protos.sh
61+
```
62+
63+
## Licensing
64+
`cisco-gnmi-python` is licensed as [Apache License, Version 2.0](LICENSE).
65+
66+
## Issues
67+
Open an issue :)
68+
69+
## Related Projects
70+
1. [openconfig/gnmi](https://github.com/openconfig/gnmi)
71+
2. [google/gnxi](https://github.com/google/gnxi)
72+
3. [Telegraf Cisco gNMI Plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/cisco_telemetry_gnmi)

‎github.com/openconfig/gnmi

Submodule gnmi added at 89b2bf2

‎hygiene.sh

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/usr/bin/env bash
2+
# Script which autoformats (black) and lints (pylint) code
3+
pipenv run black --safe --verbose --exclude proto src/cisco_gnmi
4+
# Many disabled to accomodate black disagreements...
5+
# Many failures due to protos being runtime-functional and difficult to lint.
6+
pipenv run pylint --disable line-too-long --disable pointless-string-statement --disable no-member --disable wrong-import-position --disable bad-continuation src/cisco_gnmi/*.py

‎setup.py

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
"""Derived from Flask
2+
https://github.com/pallets/flask/blob/master/setup.py
3+
"""
4+
5+
import io
6+
import re
7+
8+
from setuptools import find_packages
9+
from setuptools import setup
10+
11+
with io.open("README.md", "rt", encoding="utf8") as f:
12+
readme = f.read()
13+
14+
with io.open("src/cisco_gnmi/__init__.py", "rt", encoding="utf8") as f:
15+
version = re.search(r'__version__ = "(.*?)"', f.read()).group(1)
16+
17+
setup(
18+
name="cisco_gnmi",
19+
version=version,
20+
url="https://github.com/cisco-ie/cisco-gnmi-python",
21+
project_urls={
22+
"Code": "https://github.com/cisco-ie/cisco-gnmi-python",
23+
"Issue Tracker": "https://github.com/cisco-ie/cisco-gnmi-python/issues",
24+
},
25+
license="Apache License (2.0)",
26+
author="Cisco Innovation Edge",
27+
author_email="cisco-ie@cisco.com",
28+
maintainer="Cisco Innovation Edge",
29+
maintainer_email="cisco-ie@cisco.com",
30+
description="This library wraps gNMI functionality to ease usage with Cisco implementations.",
31+
long_description=readme,
32+
long_description_content_type="text/markdown",
33+
classifiers=[
34+
"Development Status :: 5 - Production/Stable",
35+
"Topic :: System :: Networking",
36+
"Topic :: System :: Networking :: Monitoring",
37+
"Intended Audience :: Developers",
38+
"License :: OSI Approved :: Apache Software License",
39+
"Operating System :: OS Independent",
40+
"Programming Language :: Python",
41+
"Programming Language :: Python :: 2",
42+
"Programming Language :: Python :: 2.7",
43+
"Programming Language :: Python :: 3",
44+
"Programming Language :: Python :: 3.5",
45+
"Programming Language :: Python :: 3.6",
46+
"Programming Language :: Python :: 3.7",
47+
],
48+
packages=find_packages("src"),
49+
package_dir={"": "src"},
50+
include_package_data=True,
51+
python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4",
52+
install_requires=[
53+
"grpcio",
54+
"protobuf",
55+
],
56+
extras_require={
57+
"dev": [
58+
"grpcio-tools",
59+
"googleapis-common-protos",
60+
"pylint",
61+
"black==19.3b0",
62+
"twine",
63+
"setuptools",
64+
"wheel",
65+
],
66+
},
67+
)

‎src/cisco_gnmi/__init__.py

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
"""Copyright 2019 Cisco Systems
2+
All rights reserved.
3+
4+
Redistribution and use in source and binary forms, with or without
5+
modification, are permitted provided that the following conditions are
6+
met:
7+
8+
* Redistributions of source code must retain the above copyright
9+
notice, this list of conditions and the following disclaimer.
10+
11+
The contents of this file are licensed under the Apache License, Version 2.0
12+
(the "License"); you may not use this file except in compliance with the
13+
License. You may obtain a copy of the License at
14+
15+
http://www.apache.org/licenses/LICENSE-2.0
16+
17+
Unless required by applicable law or agreed to in writing, software
18+
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
19+
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
20+
License for the specific language governing permissions and limitations under
21+
the License.
22+
"""
23+
24+
"""This library wraps gNMI functionality to ease usage in Python programs."""
25+
26+
27+
from .client import Client
28+
from .xr import XRClient
29+
30+
__version__ = "0.0.1"

0 commit comments

Comments
 (0)