v0.0.9

* Fixed issue mentioned in (#19) * Added version pinning for all dependencies * Added tox integration for testing new releases * Added cache option for costly getbyid operations using cache flag * Added sessions so tcp connections are being reused for subsequent api calls * Added better error handling and better retrying for rate limiting exception * Added prefilterpolicy related crud operations * Added minimum version requirements to api calls * Rewrote tests with pytest instead of unittest * Restructured project and moved default, exceptions and utils into their own files * Renamed accesscontrolpolicy related crud operations
kaisero · Apr 12, 2020 · d33b4d2 · d33b4d2
1 parent a0a16cf
commit d33b4d2
Show file tree

Hide file tree

Showing 21 changed files with 1,551 additions and 886 deletions.
diff --git a/.flake8 b/.flake8
@@ -1,5 +1,12 @@
 [flake8]
 ignore = E203, E266, E501, W503, F403, F401
 max-line-length = 120
-max-complexity = 18
+max-complexity = 16
 select = B,C,E,F,W,T4,B9
+exclude =
+    .*,
+    __pycache__,
+    docs/source/conf.py,
+    old,
+    build,
+    dist
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,6 @@
+# test files
+test.py
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -13,6 +13,6 @@ repos:
       - id: flake8
       - id: double-quote-string-fixer
   - repo: https://github.com/psf/black
-    rev: 19.3b0
+    rev: 19.10b0
     hooks:
       - id: black
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,14 +1,33 @@
-# 0.0.4
+# 0.0.9
+
+## Bugfixes
+
+Fixed issue mentioned in (#19)
 
 ## Enhancements
 
-* Add api calls for hapair monitoredinterfaces (read, update)
-* Add helper function to get primary device id from hapair
-* Add expandable option for get_depoyable_deployable_devices
-* Default paging change from 25 to 100
+Added version pinning for all dependencies
+Added tox integration for testing new releases
+Added cache option for costly getbyid operations using cache flag
+Added sessions so tcp connections are being reused for subsequent api calls
+Added better error handling and better retrying for rate limiting exception
+Added prefilterpolicy related crud operations
+Added minimum version requirements to api calls
+Rewrote tests with pytest instead of unittest
+Restructured project and moved default, exceptions and utils into their own files
+Renamed accesscontrolpolicy related crud operations
+
+# 0.0.4
 
 ## Bugfixes
 
 * getbyid operations fails due to incorrect limit param
 * api calls for ftd ipv4/ipv6 static routing fails due to incorrect URLs
 * update ftd sub interface fails due to missing param
+
+## Enhancements
+
+* Add api calls for hapair monitoredinterfaces (read, update)
+* Add helper function to get primary device id from hapair
+* Add expandable option for get_depoyable_deployable_devices
+* Default paging change from 25 to 100
diff --git a/Pipfile b/Pipfile
@@ -5,20 +5,26 @@ name = "pypi"
 
 [packages]
 requests = "==2.23.0"
-PyYAML = "==5.3"
+retry = "==0.9.2"
 urllib3 = "==1.25.8"
 
 [dev-packages]
-black = "*"
-pytest = "*"
-pytest-runner = "*"
-mypy = "*"
-pep8 = "*"
-pycodestyle = "*"
-flake8 = "*"
-autopep8 = "*"
-pre-commit = "*"
-twine = "*"
+black = "==19.10b0"
+flake8 = "==3.7.9"
+flake8-bandit = "==2.1.2"
+flake8-bugbear = "==20.1.4"
+flake8-import-order = "==0.18.1"
+flake8-builtins = "==1.5.2"
+flake8-docstrings = "==1.5.0"
+flake8-logging-format = "==0.6.0"
+flake8-print = "==3.1.4"
+mypy = "==0.770"
+pre-commit = "==2.2.0"
+pytest = "==5.4.1"
+pytest-cov = "==2.8.1"
+pytest-runner = "==5.2"
+tox = "==3.14.6"
+twine = "==3.1.1"
 
 [requires]
 python_version = "3.7"
diff --git a/README.md b/README.md
@@ -1,30 +1,40 @@
-# What is FireREST
+[![python3](https://img.shields.io/badge/python-3.7+-blue.svg)](https://github.com/kaisero/fireREST/) [![pypi](https://img.shields.io/pypi/v/fireREST)](https://pypi.org/project/fireREST/) [![license](https://img.shields.io/badge/license-GPL%20v3.0-brightgreen.svg)](https://github.com/kaisero/fireREST/blob/master/LICENSE) [![status](https://img.shields.io/badge/status-alpha-blue.svg)](https://github.com/kaisero/fireREST/) [![published](https://static.production.devnetcloud.com/codeexchange/assets/images/devnet-published.svg)](https://developer.cisco.com/codeexchange/github/repo/kaisero/fireREST)
 
-FireREST is a simple wrapper for Cisco Firepower Management Center REST API. It exposes various api calls
-as functions and takes care of authentication, token refresh and paging for large datasets.
 
-## Requirements 
+# FireREST
+
+A simple wrapper for firepower management center restful api.
+
+## Features
+
+* Authentication and automatic session refresh
+* Rate-limit handling with automatic retry operation
+* Automatic squashing of paginated api payloads
+* Sanitization of api payloads received via GET operations and used for PUT/POST operations
+* Debug logging for api calls using logger module
+* Result caching for various operations
+
+## Requirements
 
 * Python >= 3.7
 
-## Installation
+## Quickstart
+
+### Installation
 
 ```bash
-$ pip install fireREST
+pip install fireREST
 ```
 
-## Usage
-
-### Import API Client
+### Import api client
 
 ```python
 from fireREST import Client
 ```
 
 ### Authentication
 
-FireREST uses basic authentication to authenticate to FMC. You may also provide a session dictionary
-to re-use an existing authentication token. In case your authentication token times out the api client
+FireREST uses basic authentication to authenticate with fmc. In case your authentication token times out the api client
 will automatically try to re-authenticate 3 times and handle any intermediate authentication exceptions.
 
 #### Basic Authentication
@@ -33,27 +43,16 @@ will automatically try to re-authenticate 3 times and handle any intermediate au
 client = Client(hostname='fmc.example.com', username='firerest', password='Cisco123')
 ```
 
-#### Re-using an existing session
-
-```python
-auth_session = {
-  'X-auth-access-token': 'c26c28a0-c871-454f-b8e0-18c60c00562e',
-  'X-auth-refresh-token': '9d381948-2fde-47d0-a28b-f4b0bb21fe81',
-  'DOMAINS': '[{"name":"Global","uuid":"e276abec-e0f2-11e3-8169-6d9ed49b625f"}, {"name":"Global/Devel","uuid":"61e913a3-4bd6-7bde-54b6-000000000000"}]',
-}
-client = Client(hostname='fmc.example.com', session=auth_session)
-```
-
 ### Helper
 
-A variety of helper functions can be used to translate object names to their respective UUID values. Since FMC REST API uses UUID values this is neccessary
-to find pre-existing objects by the name defined in FMC UI.
+A variety of helper functions can be used to translate object names to their respective UUID values. Since fmc rest api uses uuid values this is neccessary
+to find pre-existing objects by the name defined in fmc.
 
 #### Object Name to ID
 
 ```python
 name = 'NET_OBJ'
-uuid = client.get_object_id_by_name('networks', name)
+uuid = client.get_object_id_by_name('network', name)
 ```
 
 #### Access Control Policy Name to ID
@@ -66,63 +65,62 @@ uuid = client.get_acp_id_by_name(name)
 #### Access Control Policy Rule Name to ID
 
 ```python
-policy_name = 'DEV-ACCESS-CONTROL-POLICY'
-rule_name = 'PERMIT-INTERNET-ACCESS'
-uuid = client.get_object_id_by_name(policy_name, rule_name)
+acp = 'DEV-ACCESS-CONTROL-POLICY'
+acp_rule = 'PERMIT-INTERNET-ACCESS'
+uuid = client.get_object_id_by_name(acp, acp_rule)
 ```
 
 ### Objects
 
 #### Create Network Object
 
 ```python
-net_obj = { 
+net_obj = {
     'name': 'NetObjViaAPI',
     'value': '198.18.1.0/24',
 }
 
-objects = client.create_object('networks', net_obj)
+response = client.create_object('network', net_obj)
 ```
 
 #### Get Network Object
 
 ```python
 obj_name = 'NetObjViaAPI'
-obj_id = client.get_object_id_by_name('networks', 'NetObjViaAPI')
-obj_payload = client.get_object('networks', obj_id)[0].json()
+obj_id = client.get_object_id_by_name('network', 'NetObjViaAPI')
+obj_payload = client.get_object('network', obj_id)
 ```
 
 #### Update Network Object
 
 ```python
 obj_name = 'NetObjViaAPI'
-obj_id = client.get_object_id_by_name('networks', 'NetObjViaAPI')
+obj_id = client.get_object_id_by_name('network', 'NetObjViaAPI')
 
 net_obj = {
     'id': obj_id,
     'name': 'NetObjViaAPI',
     'value': '198.18.2.0/24',
 }
 
-response = client.update_object('networks', obj_id, net_obj)
+response = client.update_object('network', obj_id, net_obj)
 ```
 
 #### Delete Network Object
 
 ```python
-obj_name = 'NetObjViaAPI
-obj_id = client.get_object_id_by_name('networks', 'NetObjViaAPI')
-response = client.delete_object('networks', obj_id)
+obj_name = 'NetObjViaAPI'
+obj_id = client.get_object_id_by_name('network', 'NetObjViaAPI')
+response = client.delete_object('network', obj_id)
 ```
-## Development
 
-Cisco provides a sandbox for Firepower Management Center. To checkout FireREST you can go ahead and enroll a
-development lab using this [link](https://devnetsandbox.cisco.com/RM/Diagram/Index/1228cb22-b2ba-48d3-a70a-86a53f4eecc0?diagramType=Topology)
 
-## Authors 
+## Authors
 
 Oliver Kaiser (oliver.kaiser@outlook.com)
 
 ## License
 
-GNU General Public License v3.0
+GNU General Public License v3.0 or later.
+
+See [LICENSE](LICENSE) for the full text.