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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mapepire-python
-Version: 0.1.3
+Version: 0.1.5
 Author-email: Allen Institute for Artificial Intelligence <contact@allenai.org>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -217,12 +217,15 @@ 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
 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: pytest-asyncio; extra == "dev"
 Requires-Dist: pytest-sphinx; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: twine>=1.11.0; extra == "dev"
@@ -243,8 +246,8 @@ Requires-Dist: pre-commit; extra == "dev"
 <a href="https://github.com/Mapepire-IBMi/mapepire-python/actions">
     <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Mapepire-IBMi/mapepire-python/main.yml">
 </a>
-<a href="https://pypi.org/project/python-wsdb/">
-    <img alt="PyPI" src="https://img.shields.io/pypi/v/python-wsdb">
+<a href="https://pypi.org/project/mapepire-python/">
+    <img alt="PyPI" src="https://img.shields.io/pypi/v/mapepire-python">
 </a>
 <a href="https://github.com/Mapepire-IBMi/mapepire-python/blob/main/LICENSE">
     <img alt="License" src="https://img.shields.io/github/license/allenai/tango.svg?color=blue&cachedrop">
@@ -252,35 +255,47 @@ 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)
+- [mapepire-python](#mapepire-python)
+  - [Overview](#overview)
+  - [Setup](#setup)
+    - [Install with `pip`](#install-with-pip)
+    - [Server Component Setup](#server-component-setup)
+  - [Example usage](#example-usage)
+    - [Query and run](#query-and-run)
+    - [Asynchronous Query Execution](#asynchronous-query-execution)
+  - [Pooling (beta)](#pooling-beta)
 - [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)
 
 
 
+## Overview
 
-#### ⚠️ (WIP!) This Project is for demo purposes only
+<img src="images/mapepire-logo.png" alt="logo" width="200"/>
 
-## Overview
+---
 
-![alt text](images/image-1.png)
 
-`mapepire-python` is a Python client implementation that leverages the [CodeFori Server Component](https://github.com/ThePrez/CodeForIBMiServer). 
+`mapepire-python` is a Python client implementation for [Mapepire](https://github.com/Mapepire-IBMi) that provides a simple interface for connecting to an IBM i server and running SQL queries. The client is designed to work with the [Mapepire Server Component](https://github.com/Mapepire-IBMi/mapepire-server)
 
 ## Setup
 
@@ -288,36 +303,49 @@ Requires-Dist: pre-commit; extra == "dev"
 
 ### Install with `pip`
 
-`mapepire-python` is available on [PyPi](https://pypi.org/project/python-wsdb/). Just Run
+`mapepire-python` is available on [PyPi](https://pypi.org/project/mapepire-python/). Just Run
 
 ```bash
-pip install python-wsdb
+pip install mapepire-python
 ```
 
-### Server Component Setup (Forthcoming)
+### 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
 
-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. 
+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:
+
+```ini
+[mapepire]
+SERVER="SERVER"
+PORT="PORT"
+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.
 
 ```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="localhost",
-    port=8085,
-    user="USER",
-    password="PASSWORD",
+    host=config['mapepire']['SERVER'],
+    port=config['mapepire']['PORT'],
+    user=config['mapepire']['USER'],
+    password=config['mapepire']['PASSWORD'],
     ignoreUnauthorized=True
 )
 
-
-job = SQLJob()
-res = job.connect(creds)
-query = job.query("select * from sample.employee")
-result = query.run(rows_to_fetch=3)
-print(result)
+with SQLJob(creds) 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:
@@ -440,6 +468,156 @@ 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
+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:
+    # query automatically closed after running
+    results = sql_job.query_and_run("select * from sample.employee", rows_to_fetch=1)
+    print(result)
+```
+
+### Asynchronous Query Execution
+
+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 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
+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)
+        print(res)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+
+```
+
+
+## Pooling (beta)
+
+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,
+            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']
+```
+
 
 # Development Setup
 

{mapepire_python-0.1.3 → mapepire_python-0.1.5}/README.md

@@ -3,8 +3,8 @@
 <a href="https://github.com/Mapepire-IBMi/mapepire-python/actions">
     <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Mapepire-IBMi/mapepire-python/main.yml">
 </a>
-<a href="https://pypi.org/project/python-wsdb/">
-    <img alt="PyPI" src="https://img.shields.io/pypi/v/python-wsdb">
+<a href="https://pypi.org/project/mapepire-python/">
+    <img alt="PyPI" src="https://img.shields.io/pypi/v/mapepire-python">
 </a>
 <a href="https://github.com/Mapepire-IBMi/mapepire-python/blob/main/LICENSE">
     <img alt="License" src="https://img.shields.io/github/license/allenai/tango.svg?color=blue&cachedrop">
@@ -12,35 +12,47 @@
 <br/>
 </div>
 
-- [Overview](#overview)
-- [Setup](#setup)
-  - [Install with `pip`](#install-with-pip)
-  - [Server Component Setup (Forthcoming)](#server-component-setup-forthcoming)
-- [Example usage](#example-usage)
+- [mapepire-python](#mapepire-python)
+  - [Overview](#overview)
+  - [Setup](#setup)
+    - [Install with `pip`](#install-with-pip)
+    - [Server Component Setup](#server-component-setup)
+  - [Example usage](#example-usage)
+    - [Query and run](#query-and-run)
+    - [Asynchronous Query Execution](#asynchronous-query-execution)
+  - [Pooling (beta)](#pooling-beta)
 - [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)
 
 
 
+## Overview
 
-#### ⚠️ (WIP!) This Project is for demo purposes only
+<img src="images/mapepire-logo.png" alt="logo" width="200"/>
 
-## Overview
+---
 
-![alt text](images/image-1.png)
 
-`mapepire-python` is a Python client implementation that leverages the [CodeFori Server Component](https://github.com/ThePrez/CodeForIBMiServer). 
+`mapepire-python` is a Python client implementation for [Mapepire](https://github.com/Mapepire-IBMi) that provides a simple interface for connecting to an IBM i server and running SQL queries. The client is designed to work with the [Mapepire Server Component](https://github.com/Mapepire-IBMi/mapepire-server)
 
 ## Setup
 
@@ -48,36 +60,49 @@
 
 ### Install with `pip`
 
-`mapepire-python` is available on [PyPi](https://pypi.org/project/python-wsdb/). Just Run
+`mapepire-python` is available on [PyPi](https://pypi.org/project/mapepire-python/). Just Run
 
 ```bash
-pip install python-wsdb
+pip install mapepire-python
 ```
 
-### Server Component Setup (Forthcoming)
+### 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
 
-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. 
+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:
+
+```ini
+[mapepire]
+SERVER="SERVER"
+PORT="PORT"
+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.
 
 ```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="localhost",
-    port=8085,
-    user="USER",
-    password="PASSWORD",
+    host=config['mapepire']['SERVER'],
+    port=config['mapepire']['PORT'],
+    user=config['mapepire']['USER'],
+    password=config['mapepire']['PASSWORD'],
     ignoreUnauthorized=True
 )
 
-
-job = SQLJob()
-res = job.connect(creds)
-query = job.query("select * from sample.employee")
-result = query.run(rows_to_fetch=3)
-print(result)
+with SQLJob(creds) 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:
@@ -200,6 +225,156 @@ 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
+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:
+    # query automatically closed after running
+    results = sql_job.query_and_run("select * from sample.employee", rows_to_fetch=1)
+    print(result)
+```
+
+### Asynchronous Query Execution
+
+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 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
+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)
+        print(res)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+
+```
+
+
+## Pooling (beta)
+
+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,
+            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']
+```
+
 
 # Development Setup
 

mapepire_python-0.1.5/mapepire_python/base_job.py

@@ -0,0 +1,42 @@
+from typing import Any, Dict, Optional, Union
+
+from .data_types import DaemonServer, JobStatus, QueryOptions
+
+
+class BaseJob:
+    def __init__(self, creds: DaemonServer = None, options: Dict[Any, Any] = {}) -> None:
+        self.creds = creds
+        self.options = options
+
+    def connect(self, db2_server: Union[DaemonServer, Dict[str, Any]]) -> Dict[str, Any]:
+        raise NotImplementedError()
+
+    def close(self) -> None:
+        raise NotImplementedError()
+
+    def get_status(self) -> JobStatus:
+        raise NotImplementedError()
+
+    def query(
+        self,
+        sql: str,
+        opts: Optional[Union[Dict[str, Any], QueryOptions]] = None,
+    ):
+        raise NotImplementedError()
+
+    def query_and_run(
+        self, sql: str, opts: Optional[Dict[str, Any]] = None, **kwargs
+    ) -> Dict[str, Any]:
+        raise NotImplementedError()
+
+    def __enter__(self):
+        raise NotImplementedError()
+
+    def __exit__(self, *args, **kwargs):
+        raise NotImplementedError()
+
+    async def __aenter__(self):
+        raise NotImplementedError()
+
+    async def __aexit__(self, *args, **kwargs):
+        raise NotImplementedError()