General refactoring and code quality improvement (#54)

- Introduced a new sub-module called "clients" and moved all clients to
it, namely CompassClient, CompassParserClient, and CompassRootClient.
- Moved RBAC-related models (previously under `types.py`) under the
`models` module and renamed it accordingly.
- Introduced ruff for code formatting, instead of black. Ruff is getting
increased traction from the community to its features and efficiency.
- Reformatted the files to ensure code and docstrings are wrapped at 88
chars as suggested by Ruff.
- Removed the Logger and LoggerLevel classes and used `getLogger`
instead to rely on the customer to configure their logging.
- Move models from `__init__.py` to `models` module
- Updated README.md file.

.pre-commit-config.yaml

@@ -1,16 +1,9 @@
 repos:
-  - repo: https://github.com/pycqa/isort
-    rev: "5.13.2"
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.1
     hooks:
-      - id: isort
-        args: ["--profile", "black", "--filter-files", "--line-length", "120", "--py", "39"]
-  - repo: https://github.com/psf/black
-    rev: "24.4.0"
-    hooks:
-      - id: black
-        args: ["--line-length=120", "--target-version=py39"]
-  - repo: https://github.com/pycqa/autoflake
-    rev: "v2.3.1"
-    hooks:
-      - id: autoflake
-        args: ["--in-place", "--remove-all-unused-imports", "--expand-star-imports", "--ignore-init-module-imports", "-r"]
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format

README.md

@@ -1,32 +1,62 @@
-# Cohere Compass SDK 
+# Cohere Compass SDK
 
-The Compass SDK is a Python library that allows you to parse documents and insert them into a Compass index.
+The Compass SDK is a Python library that allows you to parse documents and insert them
+into a Compass index.
 
-In order to parse documents, the Compass SDK relies on the Compass Parser API, which is a RESTful API that
-receives files and returns parsed documents. This requires a hosted Compass server.
+In order to parse documents, the Compass SDK relies on the Compass Parser API, which is
+a RESTful API that receives files and returns parsed documents. This requires a hosted
+Compass server.
 
-The Compass SDK provides a `CompassParserClient` that allows to interact with the parser API from your
-Python code in a convenient manner. The `CompassParserClient` provides methods to parse single and multiple
-files, as well as entire folders, and supports multiple file types (e.g., `pdf`, `docx`, `json`, `csv`, etc.) as well
-as different file systems (e.g., local, S3, GCS, etc.).
+The Compass SDK provides a `CompassParserClient` that allows to interact with the parser
+API from your Python code in a convenient manner. The `CompassParserClient` provides
+methods to parse single and multiple files, as well as entire folders, and supports
+multiple file types (e.g., `pdf`, `docx`, `json`, `csv`, etc.) as well as different file
+systems (e.g., local, S3, GCS, etc.).
 
-To insert parsed documents into a `Compass` index, the Compass SDK provides a `CompassClient` class that
-allows to interact with a Compass API server. The Compass API is also a RESTful API that allows to create,
-delete and search documents in a Compass index. To install a Compass API service, please refer to the
-[Compass documentation](https://github.com/cohere-ai/compass)
+To insert parsed documents into a `Compass` index, the Compass SDK provides a
+`CompassClient` class that allows to interact with a Compass API server. The Compass API
+is also a RESTful API that allows to create, delete and search documents in a Compass
+index. To install a Compass API service, please refer to the [Compass
+documentation](https://github.com/cohere-ai/compass)
 
-## Quickstart Snippet 
+## Table of Contents
 
-Fill in your URL, username, password, and path to test data below for an end to end run of parsing and searching. 
+<!--
+Do NOT remove the line below; it is used by markdown-toc to automatically generate the
+Table of Contents.
 
-```
-from compass_sdk.compass import CompassClient
-from compass_sdk.parser import CompassParserClient
+To update the Table Of Contents, execute the following command in the repo root dir:
+
+markdown-toc -i README.md
+
+If you don't have the markdown-toc tool, you can install it with:
+
+npm i -g markdown-toc # use sudo if you use a system-wide node installation.
+>
+
+<!-- toc -->
+
+- [Getting Started](#getting-started)
+- [Local Development](#local-development)
+  - [Create Python Virtual Environment](#create-python-virtual-environment)
+  - [Running Tests Locally](#running-tests-locally)
+    - [VSCode Users](#vscode-users)
+  - [Pre-commit](#pre-commit)
+
+<!-- tocstop -->
+
+## Getting Started
+
+Fill in your URL, username, password, and path to test data below for an end to end run
+of parsing and searching.
+
+```Python
+from compass_sdk.clients import CompassClient, CompassParserClient
 from compass_sdk import MetadataStrategy, MetadataConfig
 
 # Using cohere_web_test folder for data
 url = "<COMPASS_URL>"
-username = "<COMPASS_USERNAME>" 
+username = "<COMPASS_USERNAME>"
 password = "<COMPASS_PASSWORD>"
 
 index = "test-index"
@@ -49,5 +79,42 @@ compass_client.create_index(index_name=index)
 results = compass_client.insert_docs(index_name=index, docs=docs_to_index)
 
 results = compass_client.search(index_name=index, query="test", top_k=1)
-print(f"Results preview: \n {results.result['hits'][-1]} ... \n \n ") 
+print(f"Results preview: \n {results.result['hits'][-1]} ... \n \n ")
+```
+
+## Local Development
+
+### Create Python Virtual Environment
+
+We use Poetry to manage our Python environment. To create the virtual environment use
+the following command:
+
+```
+poetry install
+```
+
+### Running Tests Locally
+
+We use `pytest` for testing. So, you can simply run tests using the following command:
+
+```
+poetry run python -m pytest
+```
+
+#### VSCode Users
+
+We provide `.vscode` folder for those developers who prefer to use VSCode. You just need
+to open the folder in VSCode and VSCode should pick our settings.
+
+### Pre-commit
+
+We love and appreciate Coding Standards and so we enforce them in our code base.
+However, without automation, enforcing Coding Standards usually result in a lot of
+frustration for developers when they publish Pull Requests and our linters complain. So,
+we automate our formatting and linting with [pre-commit](https://pre-commit.com/). All
+you need to do is install our `pre-commit` hook so the code gets formatted automatically
+when you commit your changes locally:
+
+```bash
+pip install pre-commit
 ```