switch docstrings to pydoc/docusaurus format (#169)

Author: sserrata

pan_cortex_data_lake/adapters/adapter.py

@@ -1,6 +1,10 @@
 # -*- coding: utf-8 -*-
 
-"""Base adapter class."""
+"""
+:::info
+Base adapter class.
+:::
+"""
 from __future__ import absolute_import
 
 from abc import ABCMeta, abstractmethod
@@ -42,7 +46,9 @@ def remove_profile(self, profile=None):
     def write_credentials(self, credentials=None, profile=None, cache_token=None):
         """Write credentials.
 
+        :::info
         Write credentials to store.
+        :::
 
         Args:
             cache_token (bool): If ``True``, stores ``access_token`` in token store. Defaults to ``True``.

pan_cortex_data_lake/adapters/tinydb_adapter.py

@@ -1,6 +1,10 @@
 # -*- coding: utf-8 -*-
 
-"""TinyDB storage adapter."""
+"""
+:::info
+TinyDB storage adapter.
+:::
+"""
 from __future__ import absolute_import
 
 import os
@@ -74,7 +78,9 @@ def remove_profile(self, profile=None):
     def write_credentials(self, credentials=None, profile=None, cache_token=None):
         """Write credentials.
 
+        :::info
         Write credentials to credentials file. Performs ``upsert``.
+        :::
 
         Args:
             cache_token (bool): If ``True``, stores ``access_token`` in token store. Defaults to ``True``.

pan_cortex_data_lake/credentials.py

@@ -1,6 +1,11 @@
 # -*- coding: utf-8 -*-
 
-"""Access, store and refresh credentials."""
+"""
+:::info
+The Credentials object can be used to access, store and refresh credentials.
+:::
+
+"""
 from __future__ import absolute_import
 
 import os
@@ -56,18 +61,20 @@ def __init__(
         token_url=None,
         **kwargs
     ):
-        """Persist Session() and credentials attributes.
+        """Persist ``Session()`` and credentials attributes.
 
+        :::info
         The ``Credentials`` class is an abstraction layer for accessing,
         storing and refreshing credentials needed for interacting with
         the Application Framework.
 
         ``Credentials`` resolves credentials from the following locations,
         in the following order:
 
-            1) Class instance variables
-            2) Environment variables
-            3) Credentials store
+            1. Class instance variables
+            2. Environment variables
+            3. Credentials store
+        :::
 
         Args:
             access_token (str): OAuth2 access token. Defaults to ``None``.
@@ -83,7 +90,7 @@ def __init__(
             region (str): Region. Defaults to ``None``.
             refresh_token (str): OAuth2 refresh token. Defaults to ``None``.
             scope (str): OAuth2 scope. Defaults to ``None``.
-            storage_adapter (str): Namespace path to storage adapter module. Defaults to "pan_cortex_data_lake.adapters.tinydb_adapter.TinyDBStore". 
+            storage_adapter (str): Namespace path to storage adapter module. Defaults to "pan_cortex_data_lake.adapters.tinydb_adapter.TinyDBStore".
             storage_params (dict) = Storage adapter parameters. Defaults to ``None``.
             token_url (str): Refresh URL. Defaults to ``None``.
             token_revoke_url (str): Revoke URL. Defaults to ``None``.
@@ -134,7 +141,8 @@ def __repr__(self):
             if args[k] is not None:
                 args[k] = "*" * 6
         return "{}({})".format(
-            self.__class__.__name__, ", ".join("%s=%r" % x for x in args.items()),
+            self.__class__.__name__,
+            ", ".join("%s=%r" % x for x in args.items()),
         )
 
     @property
@@ -599,7 +607,9 @@ def revoke_refresh_token(self, **kwargs):
     def write_credentials(self):
         """Write credentials.
 
+        :::info
         Write credentials to credentials store.
+        :::
 
         Returns:
             Return value of self.storage.write_credentials()

pan_cortex_data_lake/exceptions.py

@@ -1,10 +1,11 @@
 # -*- coding: utf-8 -*-
 
-"""Exceptions raised by PAN Cloud library.
-
+"""
+:::info
 This module provides base classes for all errors raised by the PAN Cloud
 library. All other exceptions are raised and maintained by Python
 standard or nonstandard libraries.
+:::
 
 """
 

pan_cortex_data_lake/httpclient.py

@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 
-"""HTTP client wrapper for the **excellent** ``requests`` library."""
-
 from __future__ import absolute_import
 
 import logging
@@ -34,28 +32,31 @@ class HTTPClient(object):
     """HTTP client for the Cortex™ REST API"""
 
     def __init__(self, **kwargs):
-        """Persist Session() attributes and implement connection-pooling.
+        """Persist ``Session()`` attributes and implement connection-pooling.
 
+        :::info
         Built on top of the ``Requests`` library, ``HTTPClient`` is an
         abstraction layer for preparing and sending HTTP `requests` to the
         Application Framework REST APIs and handling `responses`. All
         ``Requests`` are prepared as ``Session`` objects, with the option
         to persist certain attributes such as ``cert``, ``headers``,
         ``proxies``, etc. ``HTTPAdapter`` is implemented to enable more
         granular performance and reliability tuning.
+        :::
 
         Parameters:
             auto_refresh (bool): Perform token refresh prior to request if ``access_token`` is ``None`` or expired. Defaults to ``True``.
             auto_retry (bool): Retry last failed HTTP request following a token refresh. Defaults to ``True``.
-            credentials (Credentials): :class:`~pan_cortex_data_lake.credentials.Credentials` object. Defaults to ``None``.
-            enforce_json (bool): Require properly-formatted JSON or raise :exc:`~pan_cortex_data_lake.exceptions.CortecError`. Defaults to ``False``.
+            credentials (Credentials): [Credentials](credentials.md#credentials) object. Defaults to ``None``.
+            enforce_json (bool): Require properly-formatted JSON or raise [CortexError](exceptions.md#cortexerror). Defaults to ``False``.
             force_trace (bool): If ``True``, forces trace and forces ``x-request-id`` to be returned in the response headers. Defaults to ``False``.
             port (int): TCP port to append to URL. Defaults to ``443``.
-            raise_for_status (bool): If ``True``, raises :exc:`~pan_cortex_data_lake.exceptions.HTTPError` if status_code not in 2XX. Defaults to ``False``.
-            url (str): URL to send API requests to - gets combined with ``port`` and :meth:`~request` ``path`` parameter. Defaults to ``None``.
+            raise_for_status (bool): If ``True``, raises [HTTPError](exceptions.md#httperror) if status_code not in 2XX. Defaults to ``False``.
+            url (str): URL to send API requests to - gets combined with ``port`` and ``endpoint`` parameter. Defaults to ``None``.
 
         Args:
-            **kwargs: Supported :class:`~requests.Session` and :class:`~requests.adapters.HTTPAdapter` parameters.
+            **kwargs: Supported [Session](https://github.com/psf/requests/blob/main/requests/sessions.py#L337) and
+            [HTTPAdapter](https://github.com/psf/requests/blob/main/requests/adapters.py#L85) parameters.
 
         """
         self.kwargs = kwargs.copy()  # used for __repr__
@@ -157,9 +158,9 @@ def _send_request(self, enforce_json, method, raise_for_status, url, **kwargs):
         """Send HTTP request.
 
         Args:
-             enforce_json (bool): Require properly-formatted JSON or raise :exc:`~pan_cortex_data_lake.exceptions.CortecError`. Defaults to ``False``.
+             enforce_json (bool): Require properly-formatted JSON or raise [CortexError](exceptions.md#cortexerror). Defaults to ``False``.
              method (str): HTTP method.
-             raise_for_status (bool): If ``True``, raises :exc:`~pan_cortex_data_lake.exceptions.HTTPError` if status_code not in 2XX. Defaults to ``False``.
+             raise_for_status (bool): If ``True``, raises [HTTPError](exceptions.md#httperror) if status_code not in 2XX. Defaults to ``False``.
              url (str): Request URL.
              **kwargs (dict): Re-packed key-word arguments.
 
@@ -182,18 +183,21 @@ def _send_request(self, enforce_json, method, raise_for_status, url, **kwargs):
     def request(self, **kwargs):
         """Generate HTTP request using given parameters.
 
+        :::info
         The request method prepares HTTP requests using class or
         method-level attributes/variables. Class-level attributes may be
         overridden by method-level variables offering greater
         flexibility and efficiency.
+        :::
 
         Parameters:
-            enforce_json (bool): Require properly-formatted JSON or raise :exc:`~pan_cortex_data_lake.exceptions.HTTPError`. Defaults to ``False``.
+            enforce_json (bool): Require properly-formatted JSON or raise [HTTPError](exceptions.md#httperror). Defaults to ``False``.
             path (str): URI path to append to URL. Defaults to ``empty``.
-            raise_for_status (bool): If ``True``, raises :exc:`~pan_cortex_data_lake.exceptions.HTTPError` if status_code not in 2XX. Defaults to ``False``.
+            raise_for_status (bool): If ``True``, raises [HTTPError](exceptions.md#httperror) if status_code not in 2XX. Defaults to ``False``.
 
         Args:
-            **kwargs: Supported :class:`~requests.Session` and :class:`~requests.adapters.HTTPAdapter` parameters.
+            **kwargs: Supported [Session](https://github.com/psf/requests/blob/main/requests/sessions.py#L337) and
+            [HTTPAdapter](https://github.com/psf/requests/blob/main/requests/adapters.py#L85) parameters.
 
         Returns:
             requests.Response: Requests Response() object

pan_cortex_data_lake/query.py

@@ -1,16 +1,17 @@
 # -*- coding: utf-8 -*-
 
-"""Interact with the Cortex Query Service API.
-
+"""
+:::info
 The Query Service is a Palo Alto Networks cloud service which allows
 for the storage and retrieval of data stored in the Cortex Data Lake.
 Any type of textual data can be stored in the Cortex Data Lake. Palo
 Alto Networks firewalls and software can write data to this service, as
 can the software and services created by Palo Alto Network's various
 partners.
+:::
 
 Examples:
-    Refer to the examples provided with this library.
+    Refer to the [examples provided with this library](https://github.com/PaloAltoNetworks/pan-cortex-data-lake-python/tree/master/examples).
 
 """
 
@@ -30,11 +31,11 @@ def __init__(self, **kwargs):
         """
 
         Parameters:
-            session (HTTPClient): :class:`~cortex.httpclient.HTTPClient` object. Defaults to ``None``.
-            url (str): URL to send API requests to. Later combined with ``port`` and :meth:`~request` ``endpoint`` parameter.
+            session (HTTPClient): [HTTPClient](httpclient.md#httpclient) object. Defaults to ``None``.
+            url (str): URL to send API requests to. Later combined with ``port`` and ``endpoint`` parameter.
 
         Args:
-            **kwargs: Supported :class:`~cortex.httpclient.HTTPClient` parameters.
+            **kwargs: Supported [HTTPClient](httpclient.md#httpclient) parameters.
 
         """
         self.kwargs = kwargs.copy()  # used for __repr__
@@ -77,7 +78,7 @@ def cancel_job(self, job_id=None, **kwargs):
 
         Args:
             job_id (str): Specifies the ID of the query job.
-            **kwargs: Supported :meth:`~pan_cortex_data_lake.httpclient.HTTPClient.request` parameters.
+            **kwargs: Supported [HTTPClient.request()](httpclient.md#request) parameters.
 
         Returns:
             requests.Response: Requests Response() object.
@@ -93,14 +94,16 @@ def cancel_job(self, job_id=None, **kwargs):
     def create_query(self, job_id=None, query_params=None, **kwargs):
         """Create a search request.
 
-        When submission is successful, http status code of 201 (Created)
+        :::info
+        When submission is successful, http status code of ``201`` (Created)
         is returned with a 'jobId' in response. Specifying a 'jobId' is
         optional.
+        :::
 
         Args:
             job_id (str): Specifies the ID of the query job. (optional)
             query_params (dict): Query parameters.
-            **kwargs: Supported :meth:`~pan_cortex_data_lake.httpclient.HTTPClient.request` parameters.
+            **kwargs: Supported [HTTPClient.request()](httpclient.md#request) parameters.
 
         Returns:
             requests.Response: Requests Response() object.
@@ -129,7 +132,7 @@ def get_job(self, job_id=None, **kwargs):
         Args:
             job_id (str): Specifies the ID of the query job.
             params (dict): Payload/request dictionary.
-            **kwargs: Supported :meth:`~pan_cortex_data_lake.httpclient.HTTPClient.request` parameters.
+            **kwargs: Supported [HTTPClient.request()](httpclient.md#request) parameters.
 
         Returns:
             requests.Response: Requests Response() object.
@@ -163,7 +166,7 @@ def get_job_results(
             page_number (int): Return the nth page from the result set as specified by this parameter.
             page_size (int): If specified, limits the size of a batch of results to the specified value. If un-specified, backend picks a size that may provide best performance.
             result_format (str): valuesArray or valuesJson.
-            **kwargs: Supported :meth:`~pan_cortex_data_lake.httpclient.HTTPClient.request` parameters.
+            **kwargs: Supported [HTTPClient.request()](httpclient.md#request) parameters.
 
         Returns:
             requests.Response: Requests Response() object.
@@ -213,7 +216,7 @@ def iter_job_results(
             page_number (int): Return the nth page from the result set as specified by this parameter.
             page_size (int): If specified, limits the size of a batch of results to the specified value. If un-specified, backend picks a size that may provide best performance.
             result_format (str): valuesArray or valuesJson.
-            **kwargs: Supported :meth:`~pan_cortex_data_lake.httpclient.HTTPClient.request` parameters.
+            **kwargs: Supported [HTTPClient.request()](httpclient.md#request) parameters.
 
         Yields:
             requests.Response: Requests Response() object.
@@ -271,7 +274,7 @@ def list_jobs(
             state (str): Job state, e.g. 'RUNNING', 'PENDING', 'FAILED', 'DONE'.
             job_type (str): Query type hint.
             tenant_id (str): Tenant ID.
-            **kwargs: Supported :meth:`~pan_cortex_data_lake.httpclient.HTTPClient.request` parameters.
+            **kwargs: Supported [HTTPClient.request()](httpclient.md#request) parameters.
 
         Returns:
             requests.Response: Requests Response() object.

pan_cortex_data_lake/utils.py

@@ -1,6 +1,11 @@
 # -*- coding: utf-8 -*-
 
-"""PAN Cloud Python SDK utilities."""
+"""
+:::info
+PAN Cloud Python SDK utilities.
+:::
+
+"""
 
 from __future__ import absolute_import