Skip to content

Commit 4e6e468

Browse files
zachcamara-hpezachcamara-hpe
committed
docs: 📝 Update docs structure and new example documentation
1 parent a88c07c commit 4e6e468

10 files changed

Lines changed: 521 additions & 224 deletions

File tree

‎docs/source/code_formatting.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
=========================
2+
Code Formatting
3+
=========================
4+
5+
6+
Flake8 is run on the codebase according to parameters in the .flake8
7+
file following PEP8 conventions where possible.
8+
9+
Naming Conventions
10+
^^^^^^^^^^^^^^^^^^
11+
12+
* Classes are named in CamelCase, e.g. HttpCommon, Orchestrator,
13+
EdgeConnect
14+
* Functions are variables are named in snake_case, e.g. get_appliances()
15+
* Private functions begin with ``_`` e.g. ``_get()`` or ``_req_post()``
16+
17+
Docstrings and comments
18+
^^^^^^^^^^^^^^^^^^^^^^^
19+
* Docstrings follow Sphinx/reStructured Text Formatting
20+
* Short initial description
21+
* Reference to where to find this function in Swagger UI
22+
* Longer description, notes, examples if applicable
23+
* parameter and return descriptions and types
24+
* All functions have docstrings outlining parameters and returns
25+
* Code in a function begins the line immediately following the docstring
26+
27+
**Example:**
28+
29+
.. code::
30+
31+
"""<Short description here>
32+
33+
.. list-table::
34+
:header-rows: 1
35+
36+
* - Swagger Section
37+
- Method
38+
- Endpoint
39+
* - <swagger section> -> e.g. login
40+
- <method> -> e.g. GET
41+
- <endpoint> -> e.g. /logout
42+
43+
<longer description>
44+
45+
.. note::
46+
47+
an optional note
48+
49+
.. warning::
50+
51+
an optional warning
52+
53+
:param <param name>: <param description>
54+
:type <param name>: <param type>
55+
:return: <return description>
56+
:rtype: <return type>
57+
"""
58+
<code begins here>
59+
60+
Maximum Line Length
61+
^^^^^^^^^^^^^^^^^^^
62+
* All comments and docstrings have a maximum line length of 72
63+
characters
64+
* All functional code has a maximum line length of 79 characters
65+
* In the rare case when a string or docstring can't be wrapped over
66+
multiple lines (e.g. specifying a long API endpoint in docstring)
67+
use ``# noqa:`` at the end of the docstring with ``E501``
68+
for extending past 79 and ``W505`` for extending past 72, or just
69+
``W505`` if past 72 but within 79.
70+
71+
**Example:**
72+
73+
.. code::
74+
75+
"""docstring
76+
77+
.. list-table::
78+
:header-rows: 1
79+
80+
* - Swagger Section
81+
- Method
82+
- Endpoint
83+
* - login
84+
- GET
85+
- /long_endpoint/path/{that_cannot}/be/wrapped/over_multiple_lines
86+
...
87+
""" # noqa: W505
88+
89+
90+
Type Hinting (PEP585)
91+
^^^^^^^^^^^^^^^^^^^^^
92+
* All parameters for functions have type hinting following PEP585
93+
(Python 3.9+) formatting with generic types.
94+
95+
.. code::
96+
97+
def my_func(my_var: str) -> dict:
98+
...
99+
# or
100+
def my_func(my_var: list[int]) -> list:
101+
...
102+

‎docs/source/examples/auth_example.rst‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
.. auth_example:
2+
3+
============================
4+
Authentication
5+
============================
6+
7+
The following code snippet is an example of handling multiple authentication
8+
methods when connecting to an Aruba Orchestrator instance with pyedgeconnect.
9+
10+
The example scripts provided in the repository use this process in
11+
addition to any other required logic for a particular use-case.
12+
13+
14+
15+
Environment variables
16+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17+
18+
The example script will also look for the following environment variables
19+
related to authenticating to Orchestrator
20+
21+
``ORCH_URL``
22+
``ORCH_API_KEY``
23+
``ORCH_USER``
24+
``ORCH_PASSWORD``
25+
26+
If ORCH_URL is specified, it will take precedence, otherwise user will
27+
be prompted for input to enter the Orchestrator IP or FQDN
28+
29+
If ORCH_API_KEY is specified it will take precedence for an authentication
30+
method over user/password authentication. If not found, the user will be
31+
prompted for entering an API key.
32+
33+
.. code-block:: python
34+
35+
import argparse
36+
import getpass
37+
import os
38+
39+
from pyedgeconnect import Orchestrator
40+
41+
# Parse runtime arguments to specify an Orchestrator IP or FQDN
42+
parser = argparse.ArgumentParser()
43+
parser.add_argument(
44+
"-o",
45+
"--orch",
46+
help="specify Orchestrator URL",
47+
type=str,
48+
)
49+
args = parser.parse_args()
50+
51+
# Set Orchestrator FQDN/IP via arguments, environment variable,
52+
# or user input if neither in argument or environment variable
53+
if vars(args)["orch"] is not None:
54+
orch_url = vars(args)["orch"]
55+
elif os.getenv("ORCH_URL") is not None:
56+
orch_url = os.getenv("ORCH_URL")
57+
else:
58+
orch_url = input("Orchstrator IP or FQDN: ")
59+
60+
# Set Orchestrator API Key via environment variable or user input
61+
# Skipping will fallback to user/password authentication
62+
if os.getenv("ORCH_API_KEY") is not None:
63+
orch_api_key = os.getenv("ORCH_API_KEY")
64+
else:
65+
orch_api_key_input = input("Orchstrator API Key (enter to skip): ")
66+
if len(orch_api_key_input) == 0:
67+
orch_api_key = None
68+
# Set user and password if present in environment variable
69+
orch_user = os.getenv("ORCH_USER")
70+
orch_pw = os.getenv("ORCH_PASSWORD")
71+
else:
72+
orch_api_key = orch_api_key_input
73+
74+
# Instantiate Orchestrator with ``log_console`` enabled for
75+
# printing log messages to terminal, and ``verify_ssl`` to False
76+
# which will not verify the web https certificate on Orchestrator
77+
orch = Orchestrator(
78+
orch_url,
79+
api_key=orch_api_key,
80+
log_console=True,
81+
verify_ssl=False,
82+
)
83+
84+
# If not using API key, login to Orchestrator with username/password
85+
if orch_api_key is None:
86+
# If username/password not in environment variables, prompt user
87+
if orch_user is None:
88+
orch_user = input("Enter Orchestrator username: ")
89+
orch_pw = getpass.getpass("Enter Orchestrator password: ")
90+
# Check if multi-factor authentication required
91+
mfa_prompt = input("Are you using MFA for this user (y/n)?: ")
92+
if mfa_prompt == "y":
93+
orch.send_mfa(orch_user, orch_pw, temp_code=False)
94+
token = input("Enter MFA token: ")
95+
else:
96+
token = ""
97+
# Login to Orchestrator with user/password to check auth before
98+
# proceeding
99+
confirm_auth = orch.login(orch_user, orch_pw, mfacode=token)
100+
if confirm_auth:
101+
pass
102+
else:
103+
print("Authentication to Orchestrator Failed")
104+
exit()
105+
# If API key specified, check that key is valid before proceeding
106+
else:
107+
confirm_auth = orch.get_orchestrator_hello()
108+
if confirm_auth != "There was an internal server error.":
109+
pass
110+
else:
111+
print("Authentication to Orchestrator Failed")
112+
exit()

docs/source/examples.rst renamed to docs/source/examples/basic_examples.rst

Lines changed: 4 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,10 @@
1-
.. examples:
1+
.. basic_examples:
22
33
4-
================
5-
Example Usage
6-
================
7-
84
The following examples are also included as individual .py files in the
9-
repository in the `examples` directory.
10-
11-
Each example file begins with the following code for setting up initial
12-
connection details for Orchestrator:
13-
14-
.. code-block:: python
15-
:linenos:
16-
17-
from getpass import getpass
18-
19-
from pyedgeconnect import Orchestrator
20-
21-
# set value for Orchestrator URL/IP address
22-
orchestrator_url = input("Enter Orchestrator URL or IP address: ")
23-
# set value for Orchestrator API key
24-
orchestrator_api_key = input(
25-
"Enter API key for Orchestrator (leave blank to use username/password): "
26-
)
27-
28-
# obtain username password if not using API Key
29-
if orchestrator_api_key == "":
30-
orch_user = input("Enter Orchestrator username: ")
31-
orch_password = getpass("Enter Orchestrator password: ")
32-
else:
33-
pass
34-
35-
# instantiate Orchestrator with debug enabled
36-
# for printing log messages to terminal
37-
orch = Orchestrator(
38-
orchestrator_url,
39-
api_key=orchestrator_api_key,
40-
log_console=True,
41-
verify_ssl=False,
42-
)
43-
44-
# if not using API key, login to Orchestrator
45-
if orchestrator_api_key == "":
46-
orch.login(orch_user, orch_password)
47-
else:
48-
pass
49-
50-
5+
repository in the `examples` directory. Each example script contains
6+
logic to authenticate to the Orchestrator as documented in the
7+
authentication example.
518

529

5310
Print Appliance Information
@@ -58,7 +15,6 @@ and then prints the appliances and certain attributes into a table in
5815
the terminal output.
5916

6017
.. code-block:: python
61-
:linenos:
6218
6319
# retrieve Orchestrator system information
6420
orch_info = orch.get_orchestrator_server_info()
@@ -131,7 +87,6 @@ appliance and then upload the file to Orchestrator so that it can be
13187
downloaded by the user or uploaded to support.
13288

13389
.. code-block:: python
134-
:linenos:
13590
13691
# get appliance and filter information from user
13792
ne_pk = input("Appliance NePk (e.g. 77.NE) to run packet capture on: ")
@@ -208,7 +163,6 @@ locally on Orchestrator.
208163

209164

210165
.. code-block:: python
211-
:linenos:
212166
213167
# set user password details
214168
username = "API_CREATED_USER"

0 commit comments

Comments
 (0)