mapepire-python 0.1.5__tar.gz → 0.1.7__tar.gz

{mapepire_python-0.1.5 → mapepire_python-0.1.7}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: mapepire-python
-Version: 0.1.5
-Author-email: Allen Institute for Artificial Intelligence <contact@allenai.org>
+Version: 0.1.7
+Author-email: Adam Shedivy <adam.shedivy@ibm.com>, Irfan Sharif <IrfanSharif@ibm.com>
 License:                                  Apache License
                                    Version 2.0, January 2004
                                 https://www.apache.org/licenses/
@@ -212,19 +212,22 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 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"
@@ -255,15 +258,26 @@ Requires-Dist: pre-commit; extra == "dev"
 <br/>
 </div>
 
+<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)
-  - [Example usage](#example-usage)
+- [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)
-    - [Asynchronous Query Execution](#asynchronous-query-execution)
-  - [Pooling (beta)](#pooling-beta)
+  - [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)
@@ -286,7 +300,7 @@ Requires-Dist: pre-commit; extra == "dev"
       - [2. Verify the new environment was installed:](#2-verify-the-new-environment-was-installed)
   - [Run local test suite](#run-local-test-suite)
 
-
+</details>
 
 ## Overview
 
@@ -299,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`
 
@@ -312,11 +326,75 @@ 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
 
-Setup the server credentials used to connect to the server. One way to do this is to create a `mapepire.ini` file in the root of your project with the following content:
+There are three ways to configure mapepire server connection details using `mapepire-python`:
 
-```ini
+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
+)
+```
+
+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.data_types import DaemonServer
+
+creds = DaemonServer(
+    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
+
+
+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"
@@ -324,25 +402,37 @@ USER="USER"
 PASSWORD="PASSWORD"
 ```
 
-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.
+Then you can create a `SQLJob` object by passing the path to the `.ini` file which will handle the connection details
+
 
 ```python
-import configparser
 from mapepire_python.client.sql_job import SQLJob
-from mapepire_python.types import DaemonServer
 
-config = configparser.ConfigParser()
-config.read('mapepire.ini')
+job = SQLJob("./mapepire.ini", section="mapepire")
+```
 
-creds = DaemonServer(
-    host=config['mapepire']['SERVER'],
-    port=config['mapepire']['PORT'],
-    user=config['mapepire']['USER'],
-    password=config['mapepire']['PASSWORD'],
-    ignoreUnauthorized=True
-)
+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.
 
-with SQLJob(creds) as sql_job:
+
+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)
@@ -484,50 +574,24 @@ In the ouput above, the query was successful and returned one row of data.
 To create and run a query in a single step, use the `query_and_run` method: 
 
 ```python
-import configparser
 from mapepire_python.client.sql_job import SQLJob
-from mapepire_python.types import DaemonServer
-
-config = configparser.ConfigParser()
-config.read('mapepire.ini')
-
-creds = DaemonServer(
-    host=config['mapepire']['SERVER'],
-    port=config['mapepire']['PORT'],
-    user=config['mapepire']['USER'],
-    password=config['mapepire']['PASSWORD'],
-    ignoreUnauthorized=True
-)
 
-with SQLJob(creds) as sql_job:
+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)
 ```
 
-### Asynchronous Query Execution
+## 2. Using the `PoolJob` object to run queries asynchronously
 
 The `PoolJob` object can be used to create and run queries asynchronously:
 
 ```python
 import asyncio
-import configparser
 from mapepire_python.pool.pool_job import PoolJob
-from mapepire_python.types import DaemonServer
-
-config = configparser.ConfigParser()
-config.read('mapepire.ini')
-
-creds = DaemonServer(
-    host=config['mapepire']['SERVER'],
-    port=config['mapepire']['PORT'],
-    user=config['mapepire']['USER'],
-    password=config['mapepire']['PASSWORD'],
-    ignoreUnauthorized=True
-)
 
 async def main():
-    async with PoolJob(creds=creds) as pool_job:
+    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)
 
@@ -540,24 +604,11 @@ To run a create and run a query asynchronously in a single step, use the `query_
 
 ```python
 import asyncio
-import configparser
 from mapepire_python.pool.pool_job import PoolJob
-from mapepire_python.types import DaemonServer
-
-config = configparser.ConfigParser()
-config.read('mapepire.ini')
-
-creds = DaemonServer(
-    host=config['mapepire']['SERVER'],
-    port=config['mapepire']['PORT'],
-    user=config['mapepire']['USER'],
-    password=config['mapepire']['PASSWORD'],
-    ignoreUnauthorized=True
-)
 
 async def main():
-    async with PoolJob(creds=creds) as pool_job:
-        res = await pool_job.query_and_run(rows_to_fetch=1)
+    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__':
@@ -566,32 +617,18 @@ if __name__ == '__main__':
 ```
 
 
-## Pooling (beta)
+## 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
-import configparser
 from mapepire_python.pool.pool_client import Pool, PoolOptions
-from mapepire_python.types import DaemonServer
-
-config = configparser.ConfigParser()
-config.read('mapepire.ini')
-
-creds = DaemonServer(
-    host=config['mapepire']['SERVER'],
-    port=config['mapepire']['PORT'],
-    user=config['mapepire']['USER'],
-    password=config['mapepire']['PASSWORD'],
-    ignoreUnauthorized=True
-)
-
 
 async def main():
     async with Pool(
         options=PoolOptions(
-            creds=creds,
+            creds="./mapepire.ini",
             opts=None,
             max_size=5,
             starting_size=3
@@ -610,7 +647,6 @@ async def main():
 
 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.
 
@@ -618,6 +654,56 @@ This script will create a pool of 3 `PoolJob` objects and run the query `values
 ['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
 
@@ -631,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`