Merge pull request #255 from digitalocean/docs

Docs

Author: Zach Moody

docs/advanced.rst

@@ -0,0 +1,75 @@
+Custom Sessions
+===============
+
+Custom sessions can be used to modify the default HTTP behavior. Below are a few examples, most of them from `here <https://hodovi.ch/blog/advanced-usage-python-requests-timeouts-retries-hooks/>`_.
+
+Headers
+*******
+
+To set a custom header on all requests. These headers are automatically merged with headers pynetbox sets itself.
+
+:Example:
+
+>>> import pynetbox
+>>> import requests
+>>> session = requests.Session()
+>>> session.headers = {"mycustomheader": "test"}
+>>> nb = pynetbox.api(
+...     'http://localhost:8000',
+...     private_key_file='/path/to/private-key.pem',
+...     token='d6f4e314a5b5fefd164995169f28ae32d987704f'
+... )
+>>> nb.http_session = session
+
+
+SSL Verification
+****************
+
+To disable SSL verification. See `the docs <https://requests.readthedocs.io/en/stable/user/advanced/#ssl-cert-verification>`_.
+
+:Example:
+
+>>> import pynetbox
+>>> import requests
+>>> session = requests.Session()
+>>> session.verify = False
+>>> nb = pynetbox.api(
+...     'http://localhost:8000',
+...     private_key_file='/path/to/private-key.pem',
+...     token='d6f4e314a5b5fefd164995169f28ae32d987704f'
+... )
+>>> nb.http_session = session
+
+
+Timeouts
+********
+
+Setting timeouts requires the use of Adapters.
+
+:Example:
+
+.. code-block:: python
+
+    from requests.adapters import HTTPAdapter
+
+    class TimeoutHTTPAdapter(HTTPAdapter):
+        def __init__(self, *args, **kwargs):
+            self.timeout = kwargs.get("timeout", 5)
+            super().__init__(*args, **kwargs)
+
+        def send(self, request, **kwargs):
+            kwargs['timeout'] = self.timeout
+            return super().send(request, **kwargs)
+
+    adapter = TimeoutHTTPAdapter()
+    session = requests.Session()
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+
+    nb = pynetbox.api(
+        'http://localhost:8000',
+        private_key_file='/path/to/private-key.pem',
+        token='d6f4e314a5b5fefd164995169f28ae32d987704f'
+    )
+    nb.http_session = session
+

docs/index.rst

@@ -14,13 +14,13 @@ Instantiate the :py:class:`.Api`. Use the methods available on :py:class:`.Endpo
 API
 ===
 
-.. autoclass:: pynetbox.api.Api
+.. autoclass:: pynetbox.core.api.Api
   :members:
 
 App
 ===
 
-.. autoclass:: pynetbox.api.App
+.. autoclass:: pynetbox.core.app.App
   :members:
 
 Indices and tables

pynetbox/__init__.py

@@ -1,7 +1,7 @@
 from pkg_resources import get_distribution, DistributionNotFound
 
 from pynetbox.core.query import RequestError, AllocationError, ContentError
-from pynetbox.api import Api as api
+from pynetbox.core.api import Api as api
 
 try:
     __version__ = get_distribution(__name__).version

pynetbox/api.py renamed to pynetbox/core/api.py

@@ -22,7 +22,7 @@
 
 
 class Api(object):
-    """ The API object is the point of entry to pynetbox.
+    """The API object is the point of entry to pynetbox.
 
     After instantiating the Api() with the appropriate named arguments
     you can specify which app and endpoint you wish to interact with.
@@ -39,6 +39,13 @@ class Api(object):
     Calling any of these attributes will return
     :py:class:`.App` which exposes endpoints as attributes.
 
+    **Additional Attributes**:
+        *  **http_session(requests.Session)**:
+                Override the default session with your own. This is used to control
+                a number of HTTP behaviors such as SSL verification, custom headers,
+                retires, and timeouts.
+                See `custom sessions <advanced.html#custom-sessions>`__ for more info.
+
     :param str url: The base URL to the instance of NetBox you
         wish to connect to.
     :param str token: Your NetBox token.
@@ -77,8 +84,7 @@ def __init__(
         self.http_session = requests.Session()
         if threading and sys.version_info.major == 2:
             raise NotImplementedError(
-                "Threaded pynetbox calls not supported \
-                in Python 2"
+                "Threaded pynetbox calls not supported                 in Python 2"
             )
         self.threading = threading
 
@@ -97,7 +103,7 @@ def __init__(
 
     @property
     def version(self):
-        """ Gets the API version of NetBox.
+        """Gets the API version of NetBox.
 
         Can be used to check the NetBox API version if there are
         version-dependent features or syntaxes in the API.
@@ -121,7 +127,7 @@ def version(self):
         return version
 
     def openapi(self):
-        """ Returns the OpenAPI spec.
+        """Returns the OpenAPI spec.
 
         Quick helper function to pull down the entire OpenAPI spec.