mapepire-python 0.1.8__tar.gz → 0.3.0__tar.gz

{mapepire_python-0.1.8 → mapepire_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: mapepire-python
-Version: 0.1.8
+Version: 0.3.0
 Author-email: Adam Shedivy <adam.shedivy@ibm.com>, Irfan Sharif <IrfanSharif@ibm.com>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -207,42 +207,38 @@ License:                                  Apache License
 Project-URL: Homepage, https://github.com/Mapepire-IBMi/mapepire-python
 Project-URL: Repository, https://github.com/Mapepire-IBMi/mapepire-python  
 Project-URL: Changelog, https://github.com/Mapepire-IBMi/mapepire-python/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://mapepire-ibmi.github.io/
 Classifier: Intended Audience :: Science/Research
 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.9
+Requires-Python: >=3.10
 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==13.1
-Requires-Dist: pyee
+Requires-Dist: websockets>=14.0
 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: mypy<1.20,>=1.0; extra == "dev"
+Requires-Dist: black<27.0,>=24.3.0; extra == "dev"
+Requires-Dist: isort<6.2,>=5.12; extra == "dev"
+Requires-Dist: pytest>=9.0.3; 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"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: setuptools; extra == "dev"
 Requires-Dist: wheel; extra == "dev"
-Requires-Dist: Sphinx<7.1.0,>=4.3.0; extra == "dev"
-Requires-Dist: furo==2023.7.26; extra == "dev"
-Requires-Dist: myst-parser<2.1,>=1.0; extra == "dev"
-Requires-Dist: sphinx-copybutton==0.5.2; extra == "dev"
-Requires-Dist: sphinx-autobuild==2021.3.14; extra == "dev"
-Requires-Dist: sphinx-autodoc-typehints==1.23.3; extra == "dev"
 Requires-Dist: packaging; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: python-dotenv; extra == "dev"
+Requires-Dist: pytest-env; extra == "dev"
+Requires-Dist: gssapi; extra == "dev"
+Requires-Dist: pywin32; sys_platform == "win32" and extra == "dev"
+Dynamic: license-file
 
 # mapepire-python
 <div align="center">
@@ -266,10 +262,16 @@ Requires-Dist: pre-commit; extra == "dev"
   - [Setup](#setup)
     - [Install with `pip`](#install-with-pip)
     - [Server Component Setup](#server-component-setup)
-- [Connection options](#connection-options)
+- [Quick Start](#quick-start)
+- [Other Connection options](#other-connection-options)
   - [1. Using the `DaemonServer` object](#1-using-the-daemonserver-object)
+    - [1.1 Authenticating with Kerberos](#11-authenticating-with-kerberos)
+      - [1.1.1 Windows](#111-windows)
+      - [1.1.2 Other Platforms](#112-other-platforms)
   - [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)
+  - [4. Using environment variables](#4-using-environment-variables)
+  - [TLS Configuration](#tls-configuration)
 - [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)
@@ -315,6 +317,13 @@ Requires-Dist: pre-commit; extra == "dev"
 
 `mapepire-python` requires Python 3.10 or later.
 
+ > [!NOTE]
+ >  New websocket Implementation: As of version 0.2.0, `mapepire-python` uses the `websockets` library for websocket connections. If you are upgrading from a previous version, make sure to update your dependecies. The `websocket-client` library is no longer supported.
+ > - To update run `pip install -U mapepire-python`
+ >
+ > - More info on [websockets](https://websockets.readthedocs.io/en/stable/)
+
+
 ### Install with `pip`
 
 `mapepire-python` is available on [PyPi](https://pypi.org/project/mapepire-python/). Just Run
@@ -326,43 +335,124 @@ 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/)
 
-   
-# Connection options
+# Quick Start
+
+To get started with `mapepire-python`, you will need to setup a connection credentials for the Mapepire server. You can use a dictionary to store the connection details:
+
+```python
+from mapepire_python import connect
+
+creds = {
+  "host": "SERVER",
+  "port": 8076,
+  "user": "USER",
+  "password": "PASSWORD",
+}
+
+with connect(creds) as conn:
+    with conn.execute("select * from sample.employee") as cursor:
+        result = cursor.fetchone()
+        print(result)
+
+```
+
+# Other Connection options
+
+ > [!NOTE]
+ >  TLS support as of version 0.3.0 is now available. Server certificate verification is enabled by default. To disable certificate verification, set the `ignoreUnauthorized` field to `True` in the connection details.
+ > - To update run `pip install -U mapepire-python`
+ >
+ > - More info TLS Configuration [here](#tls-configuration)
 
-There are three ways to configure mapepire server connection details using `mapepire-python`:
+There are four 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
+4. Using environment variables
 
 ## 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:
+`DaemonServer` is importable directly from `mapepire_python`:
 
 ```python
-from mapepire_python.data_types import DaemonServer
+from mapepire_python import DaemonServer
 
 creds = DaemonServer(
     host="SERVER",
     port="PORT",
     user="USER",
-    password="PASSWORD",
-    ignoreUnauthorized=True
+    password="PASSWORD"
 )
 ```
 
 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
+from mapepire_python import SQLJob, DaemonServer
+
+creds = DaemonServer(
+    host="SERVER",
+    port="PORT",
+    user="USER",
+    password="PASSWORD"
+)
+
+job = SQLJob(creds)
+```
+
+### 1.1 Authenticating with Kerberos
+If your IBM i is configured to support Kerberos authentication, you can authenticate using Kerberos instead of passing a plain-text password to the `DaemonServer` Object.
+
+#### 1.1.1 Windows
+
+If your Windows machine is part of a Kerberos realm and supports SSPI authentication, you can authenticate by creating the `DaemonServer` as shown below:
+```python
+from mapepire_python import DaemonServer
+from mapepire_python.authentication.kerberosTokenProvider import KerberosTokenProvider
 
 creds = DaemonServer(
     host="SERVER",
+    password=KerberosTokenProvider(host="SERVER"),
+    user="USER",
     port="PORT",
+)
+
+job = SQLJob(creds)
+```
+
+#### 1.1.2 Other Platforms
+
+For non-Windows platforms, Kerberos authentication requires a valid Ticket Granting Ticket (TGT) in your credential cache.
+
+Required Parameters:
+
+1. `host`: The IBM i host you are connecting to
+2. `realm`: Your Kerberos realm
+3. `realm_user`: Your Kerberos username
+4. `krb5_path`: Path to your `krb5.conf` configuration file
+
+Optional Parameters:
+
+1. `ticket_cache`: Path to your ticket cache (if not default)
+2. `krb5_mech`: The Kerberos 5 mechanism to use (if not default)
+
+```python
+from mapepire_python import DaemonServer
+from mapepire_python.authentication.kerberosTokenProvider import KerberosTokenProvider
+
+token_provider = KerberosTokenProvider(
+                  realm="REALM",
+                  realm_user="REALM_USER",
+                  host="SERVER",
+                  krb5_path="KRB5_PATH"
+                )
+
+creds = DaemonServer(
+    host="SERVER",
+    password=token_provider,
     user="USER",
-    password="PASSWORD",
-    ignoreUnauthorized=True
+    port="PORT",
 )
 
 job = SQLJob(creds)
@@ -373,7 +463,7 @@ job = SQLJob(creds)
 You can also use a dictionary to configure the connection details:
 
 ```python
-from mapepire_python.client.sql_job import SQLJob
+from mapepire_python import SQLJob
 
 creds = {
   "host": "SERVER",
@@ -406,13 +496,80 @@ Then you can create a `SQLJob` object by passing the path to the `.ini` file whi
 
 
 ```python
-from mapepire_python.client.sql_job import SQLJob
+from mapepire_python 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. 
 
+## 4. Using environment variables
+
+You can configure connection credentials through environment variables, avoiding the need to pass them explicitly in code:
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `MAPEPIRE_HOST` | Yes | — | Server hostname |
+| `MAPEPIRE_USER` | Yes | — | Database user |
+| `MAPEPIRE_PASSWORD` | Yes | — | Database password |
+| `MAPEPIRE_PORT` | No | `8076` | Server port |
+| `MAPEPIRE_CA_PATH` | No | — | Path to CA certificate file |
+
+Set the variables in your shell:
+
+```bash
+export MAPEPIRE_HOST=myibmi.example.com
+export MAPEPIRE_USER=myuser
+export MAPEPIRE_PASSWORD=mypassword
+```
+
+Then `connect()` and `async_connect()` can be called with no arguments:
+
+```python
+from mapepire_python import connect
+
+with connect() as conn:
+    with conn.execute("select * from sample.employee") as cursor:
+        print(cursor.fetchone())
+```
+
+You can also create a `DaemonServer` directly from env vars:
+
+```python
+from mapepire_python import DaemonServer, SQLJob
+
+creds = DaemonServer.from_env()
+job = SQLJob(creds)
+```
+
+## TLS Configuration
+
+Server certificate verification (`ssl.CERT_REQUIRED`) is enabled by default. To disable certificate verification, set the `ignoreUnauthorized` field to `True` in the connection details.
+
+get the server certificate:
+
+```python
+from mapepire_python.data_types import DaemonServer
+from mapepire_python.ssl import get_certificate
+
+creds = DaemonServer(host=server, port=port, user=user, password=password)
+cert = get_certificate(creds)
+print(cert)
+```
+
+## Logging
+
+`mapepire-python` emits structured logs through the standard library `logging` module. Following library best practice, it does not configure any handlers itself, so logging is silent until your application opts in. Each module logs under the `mapepire_python` namespace, so you can enable and filter logs as needed:
+
+```python
+import logging
+
+# Enable INFO-level logs from mapepire-python
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("mapepire_python").setLevel(logging.DEBUG)
+```
+
+
 
 # Usage
 
@@ -430,7 +587,7 @@ There are four main ways to run queries using `mapepire-python`:
 ## 1. Using the `SQLJob` object to run queries synchronously
 
 ```python
-from mapepire_python.client.sql_job import SQLJob
+from mapepire_python import SQLJob
 
 with SQLJob("./mapepire.ini") as sql_job:
     with sql_job.query("select * from sample.employee") as query:
@@ -574,7 +731,7 @@ 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
-from mapepire_python.client.sql_job import SQLJob
+from mapepire_python import SQLJob
 
 with SQLJob("./mapepire.ini") as sql_job:
     # query automatically closed after running
@@ -588,7 +745,7 @@ The `PoolJob` object can be used to create and run queries asynchronously:
 
 ```python
 import asyncio
-from mapepire_python.pool.pool_job import PoolJob
+from mapepire_python import PoolJob
 
 async def main():
     async with PoolJob("./mapepire.ini") as pool_job:
@@ -604,7 +761,7 @@ To run a create and run a query asynchronously in a single step, use the `query_
 
 ```python
 import asyncio
-from mapepire_python.pool.pool_job import PoolJob
+from mapepire_python import PoolJob
 
 async def main():
     async with PoolJob("./mapepire.ini") as pool_job:
@@ -623,7 +780,7 @@ The `Pool` object can be used to create a pool of `PoolJob` objects to run queri
 
 ```python
 import asyncio
-from mapepire_python.pool.pool_client import Pool, PoolOptions
+from mapepire_python import Pool, PoolOptions
 
 async def main():
     async with Pool(
@@ -688,18 +845,57 @@ with connect("./mapepire.ini") as conn:
 
 ## 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:
+The PEP 249 implementation provides a native async interface backed by non-blocking WebSocket I/O — no thread delegation. Use `async_connect` from the top-level package, or `connect` from `mapepire_python.asyncio`:
 
 ```python
 import asyncio
-from mapepire_python.asycnio import connect
+from mapepire_python import async_connect
 
 async def main():
-    async with connect("./mapepire.ini") as conn:
+    async with async_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())
+```
+
+Fetch multiple rows at once with `fetchmany` or drain the full result set with `fetchall`:
+
+```python
+async def main():
+    async with async_connect("./mapepire.ini") as conn:
+        async with await conn.execute("select * from sample.employee") as cursor:
+            page = await cursor.fetchmany(10)   # first 10 rows
+            rest = await cursor.fetchall()       # remaining rows
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+Stream rows one at a time using `async for`:
+
+```python
+async def main():
+    async with async_connect("./mapepire.ini") as conn:
+        async for row in await conn.execute("select * from sample.employee"):
+            print(row)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+Use `AsyncSQLJob` directly for lower-level access without a pool:
+
+```python
+from mapepire_python.client.async_sql_job import AsyncSQLJob
+
+async def main():
+    async with AsyncSQLJob("./mapepire.ini") as job:
+        result = await job.query_and_run("select * from sample.employee")
+        print(result.data)
+
 if __name__ == '__main__':
     asyncio.run(main())
 ```
@@ -857,9 +1053,26 @@ conda deactivate
 ```
 ## Run local test suite
 
-First, create a `pytest.ini` file in the `tests` directory. 
+The suite is split in two:
+
+- `tests/unit/` — offline unit tests. They mock the WebSocket transport and need
+  **no** IBM i server or credentials, so they run anywhere (including CI on forks).
+- `tests/integration/` — live-server tests. They connect to a real Mapepire
+  server and require credentials.
+
+### Unit tests (no server required)
+
+```bash
+# activate python development environment first
+
+pytest tests/unit/
+```
+
+### Integration tests (server required)
+
+First, create a `pytest.ini` file in the `tests/integration` directory:
 
-`tests/pytest.ini`
+`tests/integration/pytest.ini`
 
 ```ini
 [pytest]
@@ -869,11 +1082,17 @@ env =
     VITE_DB_PASS=PASS
 ```
 
-Run the test suite from the `mapepire-python` directory:
+Then run the integration suite from the `mapepire-python` directory:
 
 ```bash
 # activate python development environment first
 
+pytest tests/integration/
+```
+
+To run everything (unit + integration), just point pytest at `tests/`:
+
+```bash
 pytest tests/
 ```