Merge pull request #3 from SPOpenSource/release/0.15.0-a1

Release/0.15.0 a1

Author: zachcamara-hpe

.gitignore

@@ -29,6 +29,7 @@ wheels/
 tests/
 docs/build/
 docs/source/_build
+examples/generate_preconfig/preconfig_outputs
 
 # dotenv
 *.env

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools
+build:
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -1,5 +1,6 @@
 # Aruba Edge Connect Python SDK
 
+[![Downloads](https://static.pepy.tech/personalized-badge/pyedgeconnect?period=total&units=none&left_color=grey&right_color=orange&left_text=PyPI%20Downloads)](https://pepy.tech/project/pyedgeconnect)
 
 This package is a python wrapper for leveraging the API for Aruba
 Orchestrator and Edge Connect SDWAN systems.
@@ -10,12 +11,8 @@ Edge Connect web interfaces under "Support > Rest API"
 Many, but not all API functions have been implemented yet. Development
 is underway to continue to add further functions.
 
-As of 0.14.0+ 64% of non-deprecated Swagger functions are covered.
-
-
 ## Install
 
-
 ### Python Version
 
 > **Note:** Requires Python 3.9.0+ (due to PEP585 type-hinting e.g. ``def my_func(var1 = list[str]``)
@@ -59,7 +56,7 @@ Now you can install the package and run your python code
 ### Install from PyPI
 
 ```bash
-    $ pip install pyedgeconnect
+    pip install pyedgeconnect
 ```
 
 ### Install from GitHub
@@ -70,13 +67,13 @@ interactive shell and run:
 > **Note:** These commands assume you're within a Python 3.9 venv, or Python 3.9 is the exclusive Python version installed in regard to referencing the use of ``pip``. If that is not the case, you can specifically append ``python3.9 -m`` ahead of the ``pip install ...``
 
 ```bash
-    $ pip install git+https://github.com/SPOpenSource/edgeconnect-python
+    pip install git+https://github.com/SPOpenSource/edgeconnect-python
 ```
 
 To install a specific branch use the @branch syntax
 
 ```bash
-    $ pip install git+https://github.com/SPOpenSource/edgeconnect-python@<branch_name>
+    pip install git+https://github.com/SPOpenSource/edgeconnect-python@<branch_name>
 ```
 
 ### Install dev options
@@ -91,7 +88,7 @@ following syntax:
 ```bash
     $ pip install pyedgeconnect[dev]
     or
-    $ pip install  -e git+https://github.com/SPOpenSource/edgeconnect-python#egg=pyedgeconnect[dev]
+    $ pip install -e git+https://github.com/SPOpenSource/edgeconnect-python#egg=pyedgeconnect[dev]
 ```
 
 ## Docs
@@ -104,11 +101,11 @@ To build the documentation locally, clone the repository, install with ``[dev]``
 to include sphinx and related packages, then in the docs directory run ``make html``
 
 ```bash
-    $ git clone https://github.com/SPOpenSource/edgeconnect-python.git
-    $ cd pyedgeconnect
-    $ pip install .[dev]
-    $ cd docs
-    $ make html
+    git clone https://github.com/SPOpenSource/edgeconnect-python.git
+    cd edgeconnect-python
+    pip install .[dev]
+    cd docs
+    make html
 ```
 
 ## Usage
@@ -213,15 +210,17 @@ In the [Examples](/examples) directory you can find scripts leveraging
 the Orchestrator class demonstrating some uses
 
 * [create_user.py](/examples/create_user.py)
-    * creates a new read-only user on Orchestrator and returns the
+  * creates a new read-only user on Orchestrator and returns the
       configured details
 * [print_appliance_info.py](/examples/print_appliance_info.py)
-    * retrieves all appliances, retrieves detailed attributes of the
+  * retrieves all appliances, retrieves detailed attributes of the
       appliances, and prints details in a table format
 * [run_packet_capture.py](/examples/run_packet_capture.py)
-    * runs a tcpdump packet capture on a specified appliance, once
+  * runs a tcpdump packet capture on a specified appliance, once
       completed, uploads to Orchestrator for user retrieval
-
+* [preconfig.py](/examples/generate_preconfig/preconfig.py)
+  * uses a CSV file as source data to generate Edge Connect YAML
+      preconfig from a Jinja template
 
 ## This is an alpha product
 
@@ -255,7 +254,6 @@ See contribution details at [Contributing](CONTRIBUTING.md)
 
 Release notes are located in ``docs/source/release-notes`` directory [here](docs/source/release-notes)
 
-
 ## Authors
 
 Authored by Zach Camara, email at <zachary.camara@hpe.com>

_version.py

@@ -1 +1 @@
-version = "0.14.0a2.dev1"
+version = "0.15.0a2.dev0"

docs/source/code_formatting.rst

@@ -0,0 +1,102 @@
+=========================
+Code Formatting
+=========================
+
+
+Flake8 is run on the codebase according to parameters in the .flake8
+file following PEP8 conventions where possible.
+
+Naming Conventions
+^^^^^^^^^^^^^^^^^^
+
+* Classes are named in CamelCase, e.g. HttpCommon, Orchestrator,
+  EdgeConnect
+* Functions are variables are named in snake_case, e.g. get_appliances()
+* Private functions begin with ``_`` e.g. ``_get()`` or ``_req_post()``
+
+Docstrings and comments
+^^^^^^^^^^^^^^^^^^^^^^^
+* Docstrings follow Sphinx/reStructured Text Formatting
+    * Short initial description
+    * Reference to where to find this function in Swagger UI
+    * Longer description, notes, examples if applicable
+    * parameter and return descriptions and types
+* All functions have docstrings outlining parameters and returns
+* Code in a function begins the line immediately following the docstring
+
+**Example:**
+
+.. code::
+
+    """<Short description here>
+
+    .. list-table::
+        :header-rows: 1
+
+        * - Swagger Section
+          - Method
+          - Endpoint
+        * - <swagger section> -> e.g. login
+          - <method> -> e.g. GET
+          - <endpoint> -> e.g. /logout
+
+    <longer description>
+
+    .. note::
+
+        an optional note
+
+    .. warning::
+
+        an optional warning
+
+    :param <param name>: <param description>
+    :type <param name>: <param type>
+    :return: <return description>
+    :rtype: <return type>
+    """
+    <code begins here>
+
+Maximum Line Length
+^^^^^^^^^^^^^^^^^^^
+* All comments and docstrings have a maximum line length of 72
+  characters
+* All functional code has a maximum line length of 79 characters
+* In the rare case when a string or docstring can't be wrapped over
+  multiple lines (e.g. specifying a long API endpoint in docstring)
+  use ``# noqa:`` at the end of the docstring with ``E501``
+  for extending past 79 and ``W505`` for extending past 72, or just
+  ``W505`` if past 72 but within 79.
+
+**Example:**
+
+.. code::
+
+    """docstring
+
+    .. list-table::
+        :header-rows: 1
+
+        * - Swagger Section
+          - Method
+          - Endpoint
+        * - login
+          - GET
+          - /long_endpoint/path/{that_cannot}/be/wrapped/over_multiple_lines
+    ...
+    """ # noqa: W505
+
+
+Type Hinting (PEP585)
+^^^^^^^^^^^^^^^^^^^^^
+* All parameters for functions have type hinting following PEP585
+  (Python 3.9+) formatting with generic types.
+
+  .. code::
+
+    def my_func(my_var: str) -> dict:
+    ...
+    # or
+    def my_func(my_var: list[int]) -> list:
+    ...
+

docs/source/conf.py

@@ -10,13 +10,13 @@
 # -- Project information -----------------------------------------------------
 
 project = "pyedgeconnect"
-copyright = "2021 Hewlett Packard Enterprise Development LP"
+copyright = "2022 Hewlett Packard Enterprise Development LP"
 author = "Zach Camara"
 
 # Main version number
-version = "0.14"
+version = "0.15"
 # The full version, including alpha/beta/rc tags
-release = "0.14.0-a2"
+release = "0.15.0-a1"
 
 
 # -- General configuration ---------------------------------------------------

docs/source/examples/auth_example.rst

@@ -0,0 +1,112 @@
+.. auth_example:
+
+============================
+ Authentication
+============================
+
+The following code snippet is an example of handling multiple authentication
+methods when connecting to an Aruba Orchestrator instance with pyedgeconnect.
+
+The example scripts provided in the repository use this process in
+addition to any other required logic for a particular use-case.
+
+
+
+Environment variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The example script will also look for the following environment variables
+related to authenticating to Orchestrator
+
+``ORCH_URL``
+``ORCH_API_KEY``
+``ORCH_USER``
+``ORCH_PASSWORD``
+
+If ORCH_URL is specified, it will take precedence, otherwise user will
+be prompted for input to enter the Orchestrator IP or FQDN
+
+If ORCH_API_KEY is specified it will take precedence for an authentication
+method over user/password authentication. If not found, the user will be
+prompted for entering an API key.
+
+.. code-block:: python
+
+    import argparse
+    import getpass
+    import os
+
+    from pyedgeconnect import Orchestrator
+
+    # Parse runtime arguments to specify an Orchestrator IP or FQDN
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-o",
+        "--orch",
+        help="specify Orchestrator URL",
+        type=str,
+    )
+    args = parser.parse_args()
+
+    # Set Orchestrator FQDN/IP via arguments, environment variable,
+    # or user input if neither in argument or environment variable
+    if vars(args)["orch"] is not None:
+        orch_url = vars(args)["orch"]
+    elif os.getenv("ORCH_URL") is not None:
+        orch_url = os.getenv("ORCH_URL")
+    else:
+        orch_url = input("Orchstrator IP or FQDN: ")
+
+    # Set Orchestrator API Key via environment variable or user input
+    # Skipping will fallback to user/password authentication
+    if os.getenv("ORCH_API_KEY") is not None:
+        orch_api_key = os.getenv("ORCH_API_KEY")
+    else:
+        orch_api_key_input = input("Orchstrator API Key (enter to skip): ")
+        if len(orch_api_key_input) == 0:
+            orch_api_key = None
+            # Set user and password if present in environment variable
+            orch_user = os.getenv("ORCH_USER")
+            orch_pw = os.getenv("ORCH_PASSWORD")
+        else:
+            orch_api_key = orch_api_key_input
+
+    # Instantiate Orchestrator with ``log_console`` enabled for
+    # printing log messages to terminal, and ``verify_ssl`` to False
+    # which will not verify the web https certificate on Orchestrator
+    orch = Orchestrator(
+        orch_url,
+        api_key=orch_api_key,
+        log_console=True,
+        verify_ssl=False,
+    )
+
+    # If not using API key, login to Orchestrator with username/password
+    if orch_api_key is None:
+        # If username/password not in environment variables, prompt user
+        if orch_user is None:
+            orch_user = input("Enter Orchestrator username: ")
+            orch_pw = getpass.getpass("Enter Orchestrator password: ")
+        # Check if multi-factor authentication required
+        mfa_prompt = input("Are you using MFA for this user (y/n)?: ")
+        if mfa_prompt == "y":
+            orch.send_mfa(orch_user, orch_pw, temp_code=False)
+            token = input("Enter MFA token: ")
+        else:
+            token = ""
+        # Login to Orchestrator with user/password to check auth before
+        # proceeding
+        confirm_auth = orch.login(orch_user, orch_pw, mfacode=token)
+        if confirm_auth:
+            pass
+        else:
+            print("Authentication to Orchestrator Failed")
+            exit()
+    # If API key specified, check that key is valid before proceeding
+    else:
+        confirm_auth = orch.get_orchestrator_hello()
+        if confirm_auth != "There was an internal server error.":
+            pass
+        else:
+            print("Authentication to Orchestrator Failed")
+            exit()