mapepire-python 0.2.0__tar.gz → 0.3.1__tar.gz

{mapepire_python-0.2.0 → mapepire_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: mapepire-python
-Version: 0.2.0
+Version: 0.3.1
 Author-email: Adam Shedivy <adam.shedivy@ibm.com>, Irfan Sharif <IrfanSharif@ibm.com>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -207,41 +207,39 @@ 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: websockets>=14.0
-Requires-Dist: pyee
 Requires-Dist: pep249abc
+Provides-Extra: kerberos
+Requires-Dist: gssapi; sys_platform != "win32" and extra == "kerberos"
+Requires-Dist: pywin32; sys_platform == "win32" and extra == "kerberos"
 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: ruff<0.16,>=0.15; extra == "dev"
+Requires-Dist: mypy<2.4,>=1.0; extra == "dev"
+Requires-Dist: black<27.0,>=24.3.0; extra == "dev"
+Requires-Dist: isort<8.1,>=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"
+Dynamic: license-file
 
 # mapepire-python
 <div align="center">
@@ -264,11 +262,18 @@ Requires-Dist: pre-commit; extra == "dev"
   - [Overview](#overview)
   - [Setup](#setup)
     - [Install with `pip`](#install-with-pip)
+      - [Optional: Kerberos authentication support](#optional-kerberos-authentication-support)
     - [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)
@@ -329,46 +334,147 @@ Requires-Dist: pre-commit; extra == "dev"
 pip install mapepire-python
 ```
 
+#### Optional: Kerberos authentication support
+
+Kerberos authentication (see [Authenticating with Kerberos](#11-authenticating-with-kerberos)) requires the optional `kerberos` extra, which pulls in `gssapi` on Linux/macOS or `pywin32` on Windows:
+
+```bash
+pip install mapepire-python[kerberos]
+```
+
+On Linux, building `gssapi` also requires Kerberos development headers to be available, e.g.:
+
+```bash
+sudo apt install libkrb5-dev      # Debian/Ubuntu
+sudo dnf install krb5-devel       # Fedora/RHEL
+```
+
+If you don't use Kerberos authentication, you don't need this extra — the base `pip install mapepire-python` has no Kerberos dependencies.
+
 ### 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
 
-There are three ways to configure mapepire server connection details using `mapepire-python`:
+ > [!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 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",
-    ignoreUnauthorized=True
+    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.
+
+> [!NOTE]
+> Kerberos support requires the `kerberos` extra: `pip install mapepire-python[kerberos]`. See [Optional: Kerberos authentication support](#optional-kerberos-authentication-support).
+
+#### 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",
+    port="PORT",
 )
 
 job = SQLJob(creds)
@@ -379,7 +485,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",
@@ -402,27 +508,96 @@ First create a `mapepire.ini` file in the root of your project with the followin
 
 ```ini title=mapepire.ini
 [mapepire]
-SERVER="SERVER"
-PORT="PORT"
-USER="USER"
-PASSWORD="PASSWORD"
+host=SERVER
+port=PORT
+user=USER
+password=PASSWORD
 ```
 
+> **Note:** The keys must match the `DaemonServer` fields (`host`, `port`, `user`, `password`), and values must **not** be quoted — write `host=myhost`, not `host="myhost"`.
+
 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
+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
 
-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.
+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 four 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`:
@@ -436,7 +611,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:
@@ -580,7 +755,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
@@ -594,7 +769,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:
@@ -610,7 +785,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:
@@ -629,7 +804,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(
@@ -694,18 +869,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())
 ```
@@ -863,9 +1077,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.
 
-`tests/pytest.ini`
+### 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/integration/pytest.ini`
 
 ```ini
 [pytest]
@@ -875,11 +1106,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/
 ```