mapepire-python 0.1.4__tar.gz → 0.1.6__tar.gz

{mapepire_python-0.1.4 → mapepire_python-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mapepire-python
-Version: 0.1.4
+Version: 0.1.6
 Author-email: Allen Institute for Artificial Intelligence <contact@allenai.org>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -217,12 +217,18 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: dataclasses-json>=0.6.4
 Requires-Dist: websocket-client>=1.2.1
+Requires-Dist: websockets
+Requires-Dist: pyee
+Requires-Dist: pep249abc
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: mypy<1.5,>=1.0; extra == "dev"
 Requires-Dist: black<24.0,>=23.0; extra == "dev"
 Requires-Dist: isort<5.13,>=5.12; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pyee; extra == "dev"
+Requires-Dist: pep249abc; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: pytest-sphinx; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: twine>=1.11.0; extra == "dev"
@@ -252,26 +258,49 @@ Requires-Dist: pre-commit; extra == "dev"
 <br/>
 </div>
 
-- [Overview](#overview)
-- [Setup](#setup)
-  - [Install with `pip`](#install-with-pip)
-  - [Server Component Setup (Forthcoming)](#server-component-setup-forthcoming)
-- [Example usage](#example-usage)
+<details>
+  <summary> Table of Contents </summary>
+
+- [mapepire-python](#mapepire-python)
+  - [Overview](#overview)
+  - [Setup](#setup)
+    - [Install with `pip`](#install-with-pip)
+    - [Server Component Setup](#server-component-setup)
+- [Connection options](#connection-options)
+  - [1. Using the `DaemonServer` object](#1-using-the-daemonserver-object)
+  - [2. Passing the connection details as a dictionary](#2-passing-the-connection-details-as-a-dictionary)
+  - [3. Using a config file (`.ini`) to store the connection details](#3-using-a-config-file-ini-to-store-the-connection-details)
+- [Usage](#usage)
+  - [1. Using the `SQLJob` object to run queries synchronously](#1-using-the-sqljob-object-to-run-queries-synchronously)
+    - [Query and run](#query-and-run)
+  - [2. Using the `PoolJob` object to run queries asynchronously](#2-using-the-pooljob-object-to-run-queries-asynchronously)
+  - [3. Using the `Pool` object to run queries "concurrently"](#3-using-the-pool-object-to-run-queries-concurrently)
+  - [4. Using PEP 249 Implementation](#4-using-pep-249-implementation)
+    - [`fetchmany()` and `fetchall()` methods](#fetchmany-and-fetchall-methods)
+  - [PEP 249 Asynchronous Implementation](#pep-249-asynchronous-implementation)
 - [Development Setup](#development-setup)
   - [Setup python virtual environment with pip and venv](#setup-python-virtual-environment-with-pip-and-venv)
     - [Create a new virtual environment](#create-a-new-virtual-environment)
       - [Unix/macOS](#unixmacos)
       - [Windows](#windows)
     - [Activate the virtual environment:](#activate-the-virtual-environment)
+      - [Unix.macOS](#unixmacos-1)
+      - [Windows](#windows-1)
+      - [Unix/macOS](#unixmacos-2)
+      - [Windows](#windows-2)
     - [Prepare pip](#prepare-pip)
+      - [Unix/macOS](#unixmacos-3)
+      - [Windows](#windows-3)
     - [Install Dependencies using `requirements-dev.txt`](#install-dependencies-using-requirements-devtxt)
+      - [Unix/macOS](#unixmacos-4)
+      - [Windows](#windows-4)
   - [Setup Python virtual environment with Conda](#setup-python-virtual-environment-with-conda)
     - [Create an environment from an environment-dev.yml file](#create-an-environment-from-an-environment-devyml-file)
       - [1. Activate the new environment:](#1-activate-the-new-environment)
       - [2. Verify the new environment was installed:](#2-verify-the-new-environment-was-installed)
-- [Run local test suite](#run-local-test-suite)
-
+  - [Run local test suite](#run-local-test-suite)
 
+</details>
 
 ## Overview
 
@@ -284,7 +313,7 @@ Requires-Dist: pre-commit; extra == "dev"
 
 ## Setup
 
-`mapepire-python` requires Python 3.9 or later.
+`mapepire-python` requires Python 3.10 or later.
 
 ### Install with `pip`
 
@@ -297,28 +326,116 @@ pip install mapepire-python
 ### Server Component Setup
 To use mapire-python, you will need to have the Mapepire Server Component running on your IBM i server. Follow these instructions to set up the server component: [Mapepire Server Installation](https://mapepire-ibmi.github.io/guides/sysadmin/)
 
-## Example usage
+   
+# Connection options
+
+There are three ways to configure mapepire server connection details using `mapepire-python`:
+
+1. Using the `DaemonServer` object
+2. Passing the connection details as a dictionary
+3. Using a config file (`.ini`) to store the connection details
+
+## 1. Using the `DaemonServer` object
+
+to use the `DaemonServer` object, you will need to import the `DaemonServer` class from the `mapepire_python.data_types` module:
+
+```python
+from mapepire_python.data_types import DaemonServer
+
+creds = DaemonServer(
+    host="SERVER",
+    port="PORT",
+    user="USER",
+    password="PASSWORD",
+    ignoreUnauthorized=True
+)
+```
 
-The following script sets up a `DaemonServer` object that will be used to connect with the Server Component. Then a single `SQLJob` is created to facilitate the connection from the client side. 
+Once you have created the `DaemonServer` object, you can pass it to the `SQLJob` object to connect to the mapepire server:
 
 ```python
 from mapepire_python.client.sql_job import SQLJob
-from mapepire_python.types import DaemonServer
+from mapepire_python.data_types import DaemonServer
 
 creds = DaemonServer(
-    host="localhost",
-    port=8085,
+    host="SERVER",
+    port="PORT",
     user="USER",
     password="PASSWORD",
     ignoreUnauthorized=True
 )
 
+job = SQLJob(creds)
+```
+
+## 2. Passing the connection details as a dictionary
+
+You can also use a dictionary to configure the connection details:
+
+```python
+from mapepire_python.client.sql_job import SQLJob
+
+creds = {
+  "host": "SERVER",
+  "port": "port",
+  "user": "USER",
+  "password": "PASSWORD",
+}
+
+job = SQLJob(creds)
+```
+
+this is a convenient way to pass the connection details to the mapepire server.
+
+## 3. Using a config file (`.ini`) to store the connection details
 
-job = SQLJob()
-res = job.connect(creds)
-query = job.query("select * from sample.employee")
-result = query.run(rows_to_fetch=3)
-print(result)
+
+If you use a config file (`.ini`), you can pass the path to the file as an argument:
+
+First create a `mapepire.ini` file in the root of your project with the following required fields:
+
+```ini title=mapepire.ini
+[mapepire]
+SERVER="SERVER"
+PORT="PORT"
+USER="USER"
+PASSWORD="PASSWORD"
+```
+
+Then you can create a `SQLJob` object by passing the path to the `.ini` file which will handle the connection details
+
+
+```python
+from mapepire_python.client.sql_job import SQLJob
+
+job = SQLJob("./mapepire.ini", section="mapepire")
+```
+
+The `section` argument is optional and allows you to specify a specific section in the `.ini` file where the connection details are stored. This allows you to store multiple connection details to different systems in the same file. If you do not specify a `section`, the first section in the file will be used. 
+
+
+# Usage
+
+Depending on your setup and use case, you can choose the most convenient way to configure the connection details. The following usage examples are compatible with all three connection options detailed above. For simplicity, we assume there is a `mapepire.ini` file in the root of the project with the connection details.
+
+
+There are four main ways to run queries using `mapepire-python`:
+1.  Using the `SQLJob` object to run queries synchronously
+2.  Using the `PoolJob` object to run queries asynchronously
+3.  Using the `Pool` object to run queries "concurrently"
+4.  Using PEP 249 Implementation
+
+
+
+## 1. Using the `SQLJob` object to run queries synchronously
+
+```python
+from mapepire_python.client.sql_job import SQLJob
+
+with SQLJob("./mapepire.ini") as sql_job:
+    with sql_job.query("select * from sample.employee") as query:
+        result = query.run(rows_to_fetch=1)
+        print(result)
 ```
 
 Here is the output from the script above:
@@ -441,6 +558,152 @@ Here is the output from the script above:
 }
 
 ```
+The results object is a JSON object that contains the metadata and data from the query. Here are the different fields returned:
+- `id` field contains the query ID
+- `has_results` field indicates whether the query returned any results
+- `update_count` field indicates the number of rows updated by the query (-1 if the query did not update any rows)
+- `metadata` field contains information about the columns returned by the query
+- `data` field contains the results of the query 
+- `is_done` field indicates whether the query has finished executing
+- `success` field indicates whether the query was successful. 
+
+In the ouput above, the query was successful and returned one row of data.
+
+### Query and run 
+
+To create and run a query in a single step, use the `query_and_run` method: 
+
+```python
+from mapepire_python.client.sql_job import SQLJob
+
+with SQLJob("./mapepire.ini") as sql_job:
+    # query automatically closed after running
+    results = sql_job.query_and_run("select * from sample.employee", rows_to_fetch=1)
+    print(result)
+```
+
+## 2. Using the `PoolJob` object to run queries asynchronously
+
+The `PoolJob` object can be used to create and run queries asynchronously:
+
+```python
+import asyncio
+from mapepire_python.pool.pool_job import PoolJob
+
+async def main():
+    async with PoolJob("./mapepire.ini") as pool_job:
+        async with pool_job.query('select * from sample.employee') as query:
+          res = await query.run(rows_to_fetch=1)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+
+```
+
+To run a create and run a query asynchronously in a single step, use the `query_and_run` method:
+
+```python
+import asyncio
+from mapepire_python.pool.pool_job import PoolJob
+
+async def main():
+    async with PoolJob("./mapepire.ini") as pool_job:
+        res = await pool_job.query_and_run("select * from sample.employee", rows_to_fetch=1)
+        print(res)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+
+```
+
+
+## 3. Using the `Pool` object to run queries "concurrently"
+
+The `Pool` object can be used to create a pool of `PoolJob` objects to run queries concurrently. 
+
+```python
+import asyncio
+from mapepire_python.pool.pool_client import Pool, PoolOptions
+
+async def main():
+    async with Pool(
+        options=PoolOptions(
+            creds="./mapepire.ini",
+            opts=None,
+            max_size=5,
+            starting_size=3
+        )
+    ) as pool:
+      job_names = []
+      resultsA = await asyncio.gather(
+          pool.execute('values (job_name)'),
+          pool.execute('values (job_name)'),
+          pool.execute('values (job_name)')
+      )
+      job_names = [res['data'][0]['00001'] for res in resultsA]
+
+      print(job_names)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+This script will create a pool of 3 `PoolJob` objects and run the query `values (job_name)` concurrently. The results will be printed to the console.
+
+```bash
+['004460/QUSER/QZDASOINIT', '005096/QUSER/QZDASOINIT', '005319/QUSER/QZDASOINIT']
+```
+
+## 4. Using PEP 249 Implementation
+
+PEP 249 is the Python Database API Specification v2.0. The `mapepire-python` client provides a PEP 249 implementation that allows you to use the `Connection` and `Cursor` objects to interact with the Mapepire server. Like the examples above, we can pass the `mapepire.ini` file to the `connect` function to create a connection to the server:
+
+```python
+from mapepire_python import connect
+
+with connect("./mapepire.ini") as conn:
+    with conn.execute("select * from sample.employee") as cursor:
+        result = cursor.fetchone()
+        print(result)
+```
+
+### `fetchmany()` and `fetchall()` methods
+
+The `Cursor` object provides the `fetchmany()` and `fetchall()` methods to fetch multiple rows from the result set:
+
+```python
+with connect("./mapepire.ini") as conn:
+    with conn.execute("select * from sample.employee") as cursor:
+        results = cursor.fetchmany(size=2)
+        print(results)
+```
+---
+
+```python
+with connect("./mapepire.ini") as conn:
+    with conn.execute("select * from sample.employee") as cursor:
+        results = cursor.fetchall()
+        print(results)
+```
+
+## PEP 249 Asynchronous Implementation
+
+The PEP 249 implementation also provides an asynchronous interface for running queries. The `connect` function returns an asynchronous context manager that can be used with the `async with` statement:
+
+```python
+import asyncio
+from mapepire_python.asycnio import connect
+
+async def main():
+    async with connect("./mapepire.ini") as conn:
+        async with await conn.execute("select * from sample.employee") as cursor:
+            result = await cursor.fetchone()
+            print(result)
+            
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
 
 # Development Setup
 
@@ -454,7 +717,7 @@ This guide provides instructions for setting up a Python virtual environment usi
 
 ### Create a new virtual environment
 
-**Note**: This applies to supported versions of Python 3.8 and higher
+**Note**: This applies to supported versions of Python 3.10 and higher
 
 navigate to the project's directory and run the following command. This will create a new virtual environment in a local folder named `.venv`