[CCI] Added Poetry Management for Testing

CHANGELOG.md

@@ -42,6 +42,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Improved CI performance of integration with unreleased OpenSearch ([#318](https://github.com/opensearch-project/opensearch-py/pull/318))
 - Added k-NN guide and samples ([#449](https://github.com/opensearch-project/opensearch-py/pull/449))
 - Added the ability to run tests matching a pattern to `.ci/run-tests` ([#454](https://github.com/opensearch-project/opensearch-py/pull/454))
+- Added a guide for taking snapshots ([#486](https://github.com/opensearch-project/opensearch-py/pull/429))
 ### Changed
 - Moved security from `plugins` to `clients` ([#442](https://github.com/opensearch-project/opensearch-py/pull/442))
 - Updated Security Client APIs ([#450](https://github.com/opensearch-project/opensearch-py/pull/450))

DEVELOPER_GUIDE.md

@@ -1,8 +1,10 @@
 - [Developer Guide](#developer-guide)
   - [Prerequisites](#prerequisites)
-  - [Docker Image Installation](#docker-setup)
+    - [Install Docker Image](#docker-setup)
+    - [Poetry](#poetry-setup)
+    - [Install Dependencies](#dependencies)
   - [Running Tests](#running-tests)
-  - [Integration Tests](#integration-tests)
+  - [Linter](#linter)
   - [Documentation](#documentation)
   - [Running Python Client Generator](#running-python-client-generator)
 
@@ -25,7 +27,7 @@ Install [Nox](https://nox.thea.codes/en/stable/) for task management.
 $ python -m pip install nox
 ```
 
-## Install Docker Image
+### Install Docker Image
 
 Integration tests require [docker](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/docker/).
 
@@ -40,45 +42,52 @@ Integration tests will auto-start the docker image. To start it manually:
 ```
 docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:latest
 ```
+### Poetry 
 
-## Running Tests
-
-Tests require a live instance of OpenSearch running in docker.
+This project uses [poetry](https://python-poetry.org/docs/), a modern Python dependency management tool. Poetry provides a simplified and efficient way to manage your project's dependencies, virtual environments, and packaging. It also generates the ever-important `poetry.lock`, which is used to produce deterministic builds. Here's how to get started with Poetry:
 
-This will start a new instance and run tests against the latest version of OpenSearch.
-
-```
-./.ci/run-tests
 ```
+$ pip install poetry
 
-If your OpenSearch docker instance is running, you can execute the test suite directly.
-
-```
-$ nox -rs test
+$ poetry --version
+Poetry (version 1.6.1)
 ```
 
-To run tests against different versions of OpenSearch, use `run-tests [with/without security] [version]`:
+### Install Dependencies
+
+Install dependencies.
 
 ```
-./.ci/run-tests true 1.3.0
+$ poetry install
+Installing dependencies
+Resolving dependencies...
+
+Writing lock file
 ```
+## Running Tests
 
-The first argument tells whether to run server with security plugin enabled or not. The second argument specifies the version of OpenSearch the tests should run against, if not specified, the tests run against the latest version. You can also run tests against a current SNAPSHOT.
+Tests require a live instance of OpenSearch running in docker.
+
+This will start a new instance and run tests against the latest version of OpenSearch.
 
-The following example runs tests against the latest SNAPSHOT build of OpenSearch without security.
+Run the following while on the ```./opensearch-py``` directory.
 
 ```
-./.ci/run-tests opensearch false SNAPSHOT
+$ poetry run pytest
 ```
 
 You can also run individual tests matching a pattern (`pytest -k [pattern]`). 
 
 ```
-./.ci/run-tests true 1.3.0 test_no_http_compression
+$ poetry run pytest test_opensearchpy/test_async/test_server/test_helpers/test_search.py
+============================================ test session starts ====================================================
+platform win32 -- Python 3.9.7, pytest-7.4.2, pluggy-0.13.1
+configfile: setup.cfg
+plugins: anyio-2.2.0, asyncio-0.21.1, cov-4.1.0
+asyncio: mode=auto
+collected 8 items
 
-test_opensearchpy/test_connection.py::TestUrllib3Connection::test_no_http_compression PASSED [ 33%]
-test_opensearchpy/test_connection.py::TestRequestsConnection::test_no_http_compression PASSED [ 66%]
-test_opensearchpy/test_async/test_connection.py::TestAIOHttpConnection::test_no_http_compression PASSED [100%]
+test_opensearchpy\test_async\test_server\test_helpers\test_search.py ........                                 [100%]
 ```
 
 Note that integration tests require docker to be installed and running, and downloads quite a bit of data from over the internet and hence take few minutes to complete.

USER_GUIDE.md

@@ -153,6 +153,7 @@ print(response)
 - [Search](guides/search.md)
 - [Point in Time](guides/point_in_time.md)
 - [Using a Proxy](guides/proxy.md)
+- [Taking a Snapshot](guides/snapshot.md)
 
 ## Plugins
 

guides/snapshot.md

@@ -0,0 +1,144 @@
+# Table of Contents
+- [Snapshot Actions](#snapshot-actions)
+  - [Setup](#setup)
+  - [API Actions](#api-actions)
+    - [Create Snapshot Repository](#create-snapshot-repository)
+    - [Create Snapshot](#create-snapshot)
+    - [Verify Snapshot Repository](#verify-snapshot-repository)
+    - [Delete Snapshot](#delete-snapshot)
+    - [Restore Snapshot](#restore-snapshot)
+    - [Get Snapshot Status](#get-snapshot-status)
+    - [Clone Snapshot](#clone-snapshot)
+    - [Get Snapshot](#get-snapshot)
+    - [Get Repository](#get-repository)
+    - [Repository Analyze](#repository-analyze)
+  - [Cleanup](#cleanup)
+
+# Snapshot Actions
+In this guide, we will look at some snapshot actions that allow you to manage and work with snapshots of your indices.
+
+
+## Setup
+Let's create a client instance, and an index named `movies`:
+```python
+from opensearchpy import OpenSearch
+
+host = 'localhost'
+port = 9200
+auth = ('admin', 'admin') # For testing only. Don't store credentials in code.
+
+client = OpenSearch(
+    hosts = [{'host': host, 'port': port}],
+    http_auth = auth,
+    use_ssl = True,
+    verify_certs = False,
+    ssl_show_warn = False
+)
+
+print(client.info())  # Check server info and make sure the client is connected
+client.indices.create(index='movies')
+```
+## API Actions
+### Create Snapshot Repository
+Before taking a snapshot, you need to create a snapshot repository to store the snapshots. You can use the `create_repository` API action for this purpose. The following example creates a snapshot repository named `my_repository`:
+
+```python
+repo_body = {
+    "type": "fs",  # Replace 'fs' with the appropriate repository type
+    "settings": {
+        "location": "/path/to/repo", 
+    }
+}
+
+# Create the snapshot repository and capture the response
+response = client.snapshot.create_repository(repository='my_repository', body=repo_body)
+
+# Print the response to see the result
+print(response)
+```
+
+### Create Snapshot
+To create a snapshot of an index, you can use the `create` method from the `snapshot` API. The following example creates a snapshot named `my_snapshot` for the movies index:
+
+```python
+client.snapshot.create(repository='my_repository', snapshot='my_snapshot', body={"indices": "movies"})
+```
+
+### Verify Snapshot Repository
+The `verify_repository` API action allows you to verify a snapshot repository. Verifying a repository ensures that it is accessible and operational, but it does not validate the integrity of the snapshots stored within the repository. The following example verifies `my_repository`:
+
+```python
+response = client.snapshot.verify_repository(repository='my_repository')
+
+# Print the HTTP status code
+print("HTTP Status Code:", response.status_code)
+
+# Print the response content
+print("Response Content:", response.content)
+```
+
+### Delete Snapshot
+To delete a specific snapshot, use the `delete` API action:
+
+```python
+client.snapshot.delete(repository='my_repository', snapshot='my_snapshot')
+```
+### Restore Snapshot
+To restore a snapshot and recreate the indices, mappings, and data, you can use the `restore` method. The following example restores the `my_snapshot` snapshot:
+
+```python
+response = client.snapshot.restore(repository='my_repository', snapshot='my_snapshot')
+```
+
+### Get Snapshot Status
+To check the status of a snapshot, you can use the `status` method.
+
+```python
+response = client.snapshot.status(repository='my_repository', snapshot='my_snapshot')
+```
+
+### Clone Snapshot
+You can clone an existing snapshot to create a new snapshot with the same contents. The `clone` operation allows you to create multiple copies of a snapshot, which can be useful for backup retention or creating snapshots for different purposes. The following example clones a snapshot named `my_snapshot` to create a new snapshot named `my_snapshot_clone`:
+
+```python
+client.snapshot.clone(
+    repository='my_repository',
+    snapshot='my_snapshot',
+    target_snapshot='my_snapshot_clone'
+)
+```
+## Get Snapshot
+To retrieve information about a specific snapshot, you can use the `get` API action. It provides metadata such as the snapshot's status, indices included in the snapshot, and the timestamp when the snapshot was taken. The following example retrieves information about the `my_snapshot`:
+
+```python
+response = client.snapshot.get(
+    repository='my_repository',
+    snapshot='my_snapshot'
+)
+
+# Print the response to see the result
+print(response)
+```
+
+## Get Repository
+To retrieve information about a snapshot repository, you can use the `get_repository` API action. It provides details about the configured repository, including its type and settings. The following example retrieves information about the `my_repository`:
+
+```python
+response = client.snapshot.get_repository(repository='my_repository')
+```
+
+## Repository Analyze
+The `repository_analyze` API action allows you to analyze a snapshot repository for correctness and performance. It checks for any inconsistencies or corruption in the repository. The following example performs a repository analysis on `my_repository`:
+
+```python
+response = client.snapshot.repository_analyze(repository='my_repository')
+```
+
+## Cleanup
+
+Finally, let's delete the `movies` index and clean up all the snapshots and the repository:
+```python
+client.indices.delete(index='movies')
+client.snapshot.delete(repository='my_repository', snapshot='my_snapshot')
+client.snapshot.delete_repository(repository='my_repository')
+```