Metadata-Version: 2.4
Name: runline-u
Version: 0.1.3
Summary: Python client for Runline's U data distribution platform.
Project-URL: Homepage, https://www.runline.com/
Author-email: Runline <support@runline.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: client,data-distribution,runline,u
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# Runline U Python Client

This package provides a Python API for interacting with Runline's U platform. Use of Runline services requires an active Runline customer account and any required service credentials.

The package is publicly downloadable for customer convenience, but it remains subject to the included proprietary license.

## Installation

```bash
pip install runline-u
```

For local development from this repository:

```bash
pip install -e ".[dev]"
```

## Usage

```python
from runline_u import UClient

client = UClient(host="eval.runline.com", port=40001)
client.subscribe(topic="ABC_CORP/MY_REPORT_GROUP/MY_REPORT_NAME")
client.publish(
    topic="ABC_CORP/OTHER_REPORT_GROUP/OTHER_REPORT_NAME",
    single_page_content=get_data_as_list_of_lists()
)
```

The direct host/port constructor remains supported for applications that use a
single HubServer. Applications that need HubServer hot failover can use endpoint
configuration:

```python
from runline_u import UClient, UClientEndpoint

client = UClient(
    primary_endpoint=UClientEndpoint("primary-hub.example.com", 40001, secure=True),
    backup_endpoint=UClientEndpoint("backup-hub.example.com", 40001, secure=True),
)
```

Backup endpoints are optional. A missing, unconfigured, or identical backup
HubServer endpoint is treated as no backup.

For password-based authentication, a backup AuthServer can be supplied. The
primary AuthServer is always tried first:

```python
token = client.get_authn_token(
    "https://primary-auth.example.com:40151/api/v1/basicauthntoken",
    password,
    backup_auth_url="https://backup-auth.example.com:40151/api/v1/basicauthntoken",
)
client.authenticate(token)
```

Applications can also authenticate with a saved token and configure renewal,
which avoids storing user credentials in the application:

```python
client.authenticate(
    saved_token,
    renew_auth_url="https://primary-auth.example.com:40151/api/v1/renewauthntoken",
    backup_renew_auth_url="https://backup-auth.example.com:40151/api/v1/renewauthntoken",
    token_renewal_interval_minutes=60,
)
```

## UpTickXL backward compatibility

Existing UpTickXL Python applications can install the `runline-u` package and
continue using legacy imports:

```bash
pip install runline-u
```

```python
from uptickxl_client import UpTickXLClient
```

New applications should prefer the modern API:

```python
from runline_u import UClient
```

Both import styles use the same underlying Runline U implementation. The legacy
facade preserves the old top-level import path and public compatibility names,
while falsey client host values intentionally use the modern `RUNLINE-PROD1`
default.

## Complete Example

A complete example application is included with the `runline-u` package. It demonstrates subscriptions, wildcard subscriptions, callbacks for processing incoming reports, publishing reports, authentication, periodic publishing, and interaction with a supplied Excel workbook.

Copy editable examples into your current directory:

```bash
runline-u-copy-examples
```

Or choose a destination:

```bash
runline-u-copy-examples ./my-runline-u-examples
```

Update the copied `u_example_server.py` for your entity, endpoint/authentication details, and credentials, then run:

```bash
python runline-u-examples/u_example_server.py
```

Open the copied `Client_of_U_Server_Example.xlsx` while the example server is running to use the workbook as a front end for publishing requests and viewing responses.

## Release Notes

Release notes are maintained in `CHANGELOG.md`.
