samples directory now passes the missing-function-docstring linter (#640)

* updated files with docstrings to pass pylint

Signed-off-by: Mark Cohen <markcoh@amazon.com>

* updated samples to prepare for enabling missing-docstring linter; will continue to work on this before committing setup.cfg

Signed-off-by: Mark Cohen <markcoh@amazon.com>

* removed missing-function-docstring from setup.cfg so the linter doesn't fail while work on docstrings continues

Signed-off-by: Mark Cohen <markcoh@amazon.com>

* corrected unnecessary return docstring values

Signed-off-by: Mark Cohen <markcoh@amazon.com>

* fixing failure in 'black' on reformatting

Signed-off-by: Mark Cohen <markcoh@amazon.com>

---------

Signed-off-by: Mark Cohen <markcoh@amazon.com>

benchmarks/bench_async.py

@@ -17,6 +17,7 @@ from opensearchpy import AsyncHttpConnection, AsyncOpenSearch
 
 
 async def index_records(client: Any, index_name: str, item_count: int) -> None:
+    """asynchronously bulk index item_count records into the index (index_name)"""
     await asyncio.gather(
         *[
             client.index(
@@ -34,6 +35,10 @@ async def index_records(client: Any, index_name: str, item_count: int) -> None:
 
 
 async def test_async(client_count: int = 1, item_count: int = 1) -> None:
+    """
+    asynchronously index with item_count records and run client_count clients. This function can be used to
+    test balancing the number of items indexed with the number of documents.
+    """
     host = "localhost"
     port = 9200
     auth = ("admin", "admin")
@@ -74,6 +79,7 @@ async def test_async(client_count: int = 1, item_count: int = 1) -> None:
 
 
 def test(item_count: int = 1, client_count: int = 1) -> None:
+    """sets up and executes the asynchronous tests"""
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
     loop.run_until_complete(test_async(item_count, client_count))
@@ -84,26 +90,32 @@ ITEM_COUNT = 100
 
 
 def test_1() -> None:
+    """run a test for one item and 32*ITEM_COUNT clients"""
     test(1, 32 * ITEM_COUNT)
 
 
 def test_2() -> None:
+    """run a test for two items and 16*ITEM_COUNT clients"""
     test(2, 16 * ITEM_COUNT)
 
 
 def test_4() -> None:
+    """run a test for two items and 8*ITEM_COUNT clients"""
     test(4, 8 * ITEM_COUNT)
 
 
 def test_8() -> None:
+    """run a test for four items and 4*ITEM_COUNT clients"""
     test(8, 4 * ITEM_COUNT)
 
 
 def test_16() -> None:
+    """run a test for 16 items and 2*ITEM_COUNT clients"""
     test(16, 2 * ITEM_COUNT)
 
 
 def test_32() -> None:
+    """run a test for 32 items and ITEM_COUNT clients"""
     test(32, ITEM_COUNT)
 
 

benchmarks/bench_info_sync.py

@@ -21,6 +21,7 @@ from opensearchpy import OpenSearch
 
 
 def get_info(client: Any, request_count: int) -> float:
+    """get info from client"""
     tt: float = 0
     for n in range(request_count):
         start = time.time() * 1000
@@ -31,6 +32,7 @@ def get_info(client: Any, request_count: int) -> float:
 
 
 def test(thread_count: int = 1, request_count: int = 1, client_count: int = 1) -> None:
+    """test to index with thread_count threads, item_count records and run client_count clients"""
     host = "localhost"
     port = 9200
     auth = ("admin", "admin")
@@ -79,22 +81,27 @@ REQUEST_COUNT = 250
 
 
 def test_1() -> None:
+    """testing 1 threads"""
     test(1, 32 * REQUEST_COUNT, 1)
 
 
 def test_2() -> None:
+    """testing 2 threads"""
     test(2, 16 * REQUEST_COUNT, 2)
 
 
 def test_4() -> None:
+    """testing 4 threads"""
     test(4, 8 * REQUEST_COUNT, 3)
 
 
 def test_8() -> None:
+    """testing 8 threads"""
     test(8, 4 * REQUEST_COUNT, 8)
 
 
 def test_32() -> None:
+    """testing 32 threads"""
     test(32, REQUEST_COUNT, 32)
 
 

benchmarks/bench_sync.py

@@ -22,6 +22,7 @@ from opensearchpy import OpenSearch, Urllib3HttpConnection
 
 
 def index_records(client: Any, index_name: str, item_count: int) -> Any:
+    """bulk index item_count records into index_name"""
     tt = 0
     for n in range(10):
         data: Any = []
@@ -48,6 +49,7 @@ def index_records(client: Any, index_name: str, item_count: int) -> Any:
 
 
 def test(thread_count: int = 1, item_count: int = 1, client_count: int = 1) -> None:
+    """test to index with thread_count threads, item_count records and run client_count clients"""
     host = "localhost"
     port = 9200
     auth = ("admin", "admin")
@@ -118,22 +120,27 @@ ITEM_COUNT = 1000
 
 
 def test_1() -> None:
+    """testing 1 threads"""
     test(1, 32 * ITEM_COUNT, 1)
 
 
 def test_2() -> None:
+    """testing 2 threads"""
     test(2, 16 * ITEM_COUNT, 2)
 
 
 def test_4() -> None:
+    """testing 4 threads"""
     test(4, 8 * ITEM_COUNT, 3)
 
 
 def test_8() -> None:
+    """testing 8 threads"""
     test(8, 4 * ITEM_COUNT, 8)
 
 
 def test_32() -> None:
+    """testing 32 threads"""
     test(32, ITEM_COUNT, 32)
 
 

samples/advanced_index_actions/advanced_index_actions_sample.py

@@ -18,6 +18,10 @@ from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    demonstrates various functions to operate on the index (e.g. clear different levels of cache, refreshing the
+    index)
+    """
     # Set up
     client = OpenSearch(
         hosts=["https://localhost:9200"],

samples/aws/search_requests.py

@@ -20,6 +20,12 @@ from opensearchpy import OpenSearch, RequestsAWSV4SignerAuth, RequestsHttpConnec
 
 
 def main() -> None:
+    """
+    connects to a cluster specified in environment variables, creates an index, inserts documents,
+    searches the index, deletes the document, deletes the index.
+    the environment variables are "ENDPOINT" for the cluster endpoint, AWS_REGION for the region in which the cluster
+    is hosted, and SERVICE to indicate if this is an ES 7.10.2 compatible cluster
+    """
     # verbose logging
     logging.basicConfig(format="%(levelname)s:%(message)s", level=logging.INFO)
 

samples/aws/search_urllib3.py

@@ -20,10 +20,18 @@ from opensearchpy import OpenSearch, Urllib3AWSV4SignerAuth, Urllib3HttpConnecti
 
 
 def main() -> None:
+    """
+    1. connects to an OpenSearch cluster on AWS defined by environment variables (i.e. ENDPOINT - cluster endpoint like
+    my-test-domain.us-east-1.es.amazonaws.com; AWS_REGION like us-east-1, us-west-2; and SERVICE like es which
+    differentiates beteween serverless and the managed service.
+    2. creates an index called "movies" and adds a single document
+    3. queries for that document
+    4. deletes the document
+    5. deletes the index
+    """
     # verbose logging
     logging.basicConfig(format="%(levelname)s:%(message)s", level=logging.INFO)
 
-    # cluster endpoint, for example: my-test-domain.us-east-1.es.amazonaws.com
     url = urlparse(environ["ENDPOINT"])
     region = environ.get("AWS_REGION", "us-east-1")
     service = environ.get("SERVICE", "es")

samples/bulk/bulk_array.py

@@ -17,6 +17,7 @@ from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """demonstrates how to bulk load data into an index"""
     # connect to an instance of OpenSearch
 
     host = os.getenv("HOST", default="localhost")

samples/bulk/bulk_helpers.py

@@ -17,6 +17,10 @@ from opensearchpy import OpenSearch, helpers
 
 
 def main() -> None:
+    """
+    demonstrates how to bulk load data using opensearchpy.helpers including examples of serial, parallel, and streaming
+    bulk load
+    """
     # connect to an instance of OpenSearch
 
     host = os.getenv("HOST", default="localhost")

samples/bulk/bulk_ld.py

@@ -17,6 +17,9 @@ from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    bulk index 100 items and then delete the index
+    """
     # connect to an instance of OpenSearch
 
     host = os.getenv("HOST", default="localhost")

samples/document_lifecycle/document_lifecycle_sample.py

@@ -17,6 +17,9 @@ from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    provides samples for different ways to handle documents including indexing, searching, updating, and deleting
+    """
     # Connect to OpenSearch
     client = OpenSearch(
         hosts=["https://localhost:9200"],

samples/hello/hello.py

@@ -16,6 +16,10 @@ from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    an example showing how to create an synchronous connection to OpenSearch, create an index, index a document
+    and search to return the document
+    """
     host = "localhost"
     port = 9200
     auth = ("admin", "admin")  # For testing only. Don't store credentials in code.

samples/hello/hello_async.py

@@ -16,6 +16,10 @@ from opensearchpy import AsyncOpenSearch
 
 
 async def main() -> None:
+    """
+    an example showing how to create an asynchronous connection to OpenSearch, create an index, index a document
+    and search to return the document
+    """
     # connect to OpenSearch
     host = "localhost"
     port = 9200

samples/index_template/index_template_sample.py

@@ -12,6 +12,20 @@ from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    1. connects to an OpenSearch instance running on localhost
+    2. Create an index template named `books` with default settings and mappings for indices of
+    the `books-*` pattern. You can create an index template to define default settings and mappings for indices
+    of certain patterns.
+    3. When creating an index that matches the `books-*` pattern, OpenSearch will automatically apply the template's
+    settings and mappings to the index. Create an index named books-nonfiction and verify that its settings and mappings
+     match those of the template
+    4. If multiple index templates match the index's name, OpenSearch will apply the template with the highest
+    `priority`. In the example, two templates are created with different priorities.
+    5. Composable index templates are a new type of index template that allow you to define multiple component templates
+     and compose them into a final template. The last part of the example before cleaning up creates a component
+     template named `books_mappings` with default mappings for indices of the `books-*` and `books-fiction-*` patterns.
+    """
     # Create a client instance
     client = OpenSearch(
         hosts=["https://localhost:9200"],
@@ -20,8 +34,7 @@ def main() -> None:
         http_auth=("admin", "admin"),
     )
 
-    # You can create an index template to define default settings and mappings for indices of certain patterns.
-    # The following example creates an index template named `books` with default settings and mappings for indices of the `books-*` pattern:
+    # create an index template
     client.indices.put_index_template(
         name="books",
         body={
@@ -41,13 +54,10 @@ def main() -> None:
         },
     )
 
-    # Now, when you create an index that matches the `books-*` pattern, OpenSearch will automatically apply the template's settings and mappings to the index.
-    # Let's create an index named books-nonfiction and verify that its settings and mappings match those of the template:
+    # create the index which applies the index template settings matched by pattern
     client.indices.create(index="books-nonfiction")
     print(client.indices.get(index="books-nonfiction"))
 
-    # If multiple index templates match the index's name, OpenSearch will apply the template with the highest `priority`.
-    # The following example creates two index templates named `books-*` and `books-fiction-*` with different settings:
     client.indices.put_index_template(
         name="books",
         body={
@@ -74,8 +84,6 @@ def main() -> None:
     client.indices.create(index="books-fiction-romance")
     print(client.indices.get(index="books-fiction-romance"))
 
-    # Composable index templates are a new type of index template that allow you to define multiple component templates and compose them into a final template.
-    # The following example creates a component template named `books_mappings` with default mappings for indices of the `books-*` and `books-fiction-*` patterns:
     client.cluster.put_component_template(
         name="books_mappings",
         body={
@@ -92,6 +100,7 @@ def main() -> None:
         },
     )
 
+    # composable index templates
     client.indices.put_index_template(
         name="books",
         body={

samples/json/json_hello.py

@@ -14,6 +14,9 @@ from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    demonstrates how to index a document using a dict
+    """
     # connect to OpenSearch
 
     host = "localhost"

samples/json/json_hello_async.py

@@ -16,6 +16,10 @@ from opensearchpy import AsyncOpenSearch
 
 
 async def main() -> None:
+    """
+    this sample uses asyncio and AsyncOpenSearch to asynchronously connect to local OpenSearch cluster, create an index,
+    index data, search the index, delete the document, delete the index
+    """
     # connect to OpenSearch
     host = "localhost"
     port = 9200

samples/knn/knn_async_basics.py

@@ -18,6 +18,9 @@ from opensearchpy import AsyncHttpConnection, AsyncOpenSearch, helpers
 
 
 async def main() -> None:
+    """
+    asynchronously create, bulk index, and query kNN. then delete the index
+    """
     # connect to an instance of OpenSearch
     host = os.getenv("HOST", default="localhost")
     port = int(os.getenv("PORT", 9200))

samples/knn/knn_basics.py

@@ -17,6 +17,9 @@ from opensearchpy import OpenSearch, helpers
 
 
 def main() -> None:
+    """
+    create, bulk index, and query kNN. then delete the index
+    """
     # connect to an instance of OpenSearch
 
     host = os.getenv("HOST", default="localhost")

samples/knn/knn_boolean_filter.py

@@ -17,6 +17,9 @@ from opensearchpy import OpenSearch, helpers
 
 
 def main() -> None:
+    """
+    create, query, and delete a kNN index
+    """
     # connect to an instance of OpenSearch
 
     host = os.getenv("HOST", default="localhost")

samples/knn/knn_efficient_filter.py

@@ -16,6 +16,9 @@ from opensearchpy import OpenSearch, helpers
 
 
 def main() -> None:
+    """
+    create a kNN index using Lucene kNN and query it using filters
+    """
     # connect to an instance of OpenSearch
 
     host = os.getenv("HOST", default="localhost")

samples/logging/log_collection_sample.py

@@ -23,6 +23,10 @@ urllib3.disable_warnings()
 
 
 def main() -> None:
+    """
+    sample for custom logging; this shows how to create a console handler, connect to OpenSearch, define a custom
+    logger and log to an OpenSearch index
+    """
     print("Collecting logs.")
 
     # Create a console handler
@@ -47,15 +51,22 @@ def main() -> None:
     # Add console handler to the logger
     os_logger.addHandler(console_handler)
 
-    # Define a custom handler that logs to OpenSearch
     class OpenSearchHandler(logging.Handler):
+        """
+        define a custom handler that logs to opensearch
+        """
+
         # Initializer / Instance attributes
         def __init__(self, opensearch_client: Any) -> None:
             super().__init__()
             self.os_client = opensearch_client
 
-        # Build index name (e.g., "logs-YYYY-MM-DD")
         def _build_index_name(self) -> str:
+            """
+            Build index name (e.g., "logs-YYYY-MM-DD")
+            :rtype: bool
+            :return: a str with date formatted as 'logs-YYYY-MM-DD'
+            """
             return f"logs-{datetime.date(datetime.now())}"
 
         # Emit logs to the OpenSearch cluster

samples/security/roles.py

@@ -9,13 +9,13 @@
 # Modifications Copyright OpenSearch Contributors. See
 # GitHub history for details.
 
-
-# A basic OpenSearch sample that create and manage roles.
-
 from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    A basic OpenSearch sample that create and manage roles.
+    """
     # connect to OpenSearch
 
     host = "localhost"

samples/security/users.py

@@ -9,13 +9,13 @@
 # Modifications Copyright OpenSearch Contributors. See
 # GitHub history for details.
 
-
-# A basic OpenSearch sample that create and manage users.
-
 from opensearchpy import OpenSearch
 
 
 def main() -> None:
+    """
+    A basic OpenSearch sample that create and manage users.
+    """
     # connect to OpenSearch
 
     host = "localhost"