Metadata-Version: 2.4
Name: pragma-onkey
Version: 0.0.5
Summary: Pragma/OnKey SOAP client library.
Author-email: Jc Cloete <jc@drakkentech.co.za>, Drakkentech <info@drakkentech.co.za>
License: Proprietary
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: zeep>=4.2.1
Requires-Dist: pydantic>=2.7.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: typing-extensions>=4.10.0
Provides-Extra: dev
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: setuptools_scm>=8.0.0; extra == "dev"

# pragma-onkey

Standalone Pragma/OnKey SOAP client library with generated schemas and services. The client is tenant-neutral and configured at runtime with your OnKey base URL.

## Installation

If you are consuming a published build:

```bash
pip install pragma-onkey
```

For local development:

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

## Configuration

The client resolves WSDL endpoints using a base URL and an optional query suffix.

- `wsdl_base_url`: your tenant base URL (required unless a service provides `wsdl_url`).
- `wsdl_query`: appended when building the WSDL URL (default `?singleWsdl`).
- `use_soap11`: force SOAP 1.1 Basic bindings instead of SOAP 1.2 Custom (default `False`).

Example base URL format:

```text
https://your.domain/tenant
```

## Usage

Sync client with typed, snake_case accessors:

```python
from pragma_onkey import PragmaOnkeyClient

client = PragmaOnkeyClient(
    wsdl_base_url="https://your.domain/tenant",
    wsdl_query="?singleWsdl",
    use_soap11=False,
)

alarm_service = client.alarm_import_service
response = alarm_service.import_alarms(payload)
```

Async client:

```python
from pragma_onkey import PragmaOnkeyAsyncClient

client = PragmaOnkeyAsyncClient(wsdl_base_url="https://your.domain/tenant")
response = await client.alarm_import_service.import_alarms(payload)
```

Server-side async operations (not Python async):

```python
# "import_alarms_async" starts an async job on the server and returns a job response.
job = client.alarm_import_service.import_alarms_async(payload)
progress = client.alarm_import_service.fetch_async_import_progress(progress_payload)
```

Dynamic access (less type-friendly):

```python
service = client.get_service("AlarmImportService")
```

## Development

This module is managed with `uv` and targets Python 3.12.

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

Run linting and formatting:

```bash
ruff check .
ruff format .
```

## Regenerating from WSDLs

Generated outputs include schemas, services, the service registry, and typed accessors.

```bash
python tools/generate_from_wsdls.py
```

Generated files:

- `src/pragma_onkey/schemas/*`
- `src/pragma_onkey/services/*`
- `src/pragma_onkey/service_registry.py`
- `src/pragma_onkey/service_accessors.py`

## Distribution

Local build and validation:

1. Ensure your tags follow `vX.Y.Z` (the tag is the version source of truth).
2. Regenerate artifacts: `python tools/generate_from_wsdls.py`.
3. Clean previous builds: `rm -rf dist build *.egg-info`.
4. Install build tools: `uv pip install build twine`.
5. Build the package: `python -m build`.
6. Verify metadata: `python -m twine check dist/*`.
7. (Optional) test install: `uv pip install dist/pragma_onkey-*.whl`.
8. (Optional) publish: `python -m twine upload dist/*`.

GitHub Actions publishing (tag-based):

1. Configure a PyPI Trusted Publisher for this repo.
2. Tag and push a release (the tag sets the package version):

```bash
git tag v1.0.0
git push origin v1.0.0
```
