# Gumband™ Python SDK

[![PyPI - License](https://img.shields.io/pypi/l/gumband)](LICENSE.txt)
[![PyPI - Version](https://img.shields.io/pypi/v/gumband.svg)](https://pypi.org/project/gumband)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/gumband.svg)](https://pypi.org/project/gumband)

![Gumband logo](images/Gumband%20Logo%20on%20White.png)

The Gumband Python library is a [Gumband](https://www.gumband.com/) integration provides a way for developers to interact with their components on the Gumband platform: send/receive controls, manage content, and more.

## Features Available in this SDK

At this time, this library provides the following features:

- Monitoring application health with custom statuses
- Monitoring application through error, warning, and debug logs
- Managing application content and configurations with settings
- Syncing remote files to your local exhibit
- Triggering application events through control signals
- Tracking application interaction metrics
- Dispatching custom email notifications

## Usage

[Gumband Documentation](https://docs.gumband.com/) contains a full tutorial, guides, and examples for using this library.

### Basic Connection

After creating a component for your exhibit, you will be given an API token to authenticate your python application with the Gumband platform.

- replace `exhibit_id` with the ID of your software component
- replace `exhibit_token` with the API token the platform gave you

The library is built around Python's built-in [asyncio](https://docs.python.org/3/library/asyncio.html), so your application will need to create a wrapper for it to run.

#### example.py

```python
import asyncio
from gumband_python_sdk import Gumband
from manifest import manifest

exhibit_id = 1
exhibit_token = "ae132...di2lk9"

class GumbandWrapper:
  def __init__(self, exhibit_id, token, manifest):
    """
    Initialize the GumbandWrapper with necessary parameters.
    """
    self.gumband = Gumband(exhibit_id=exhibit_id, token=token, manifest=manifest)

  async def start(self):
    """
    Start the Gumband connection and keep it running.
    """
    await self.gumband.connect()
    while True:
      await asyncio.sleep(1)

# Instantiate and run the handler
if __name__ == "__main__":
  handler = GumbandWrapper(
    exhibit_id=exhibit_id,
    token=exhibit_token,
    manifest=manifest,
  )
  asyncio.run(handler.start())
```

With it you will need a *manifest* that defines the various controls your appliction has.

#### manifest.py

```python
manifest = {
  "manifest": {
    "statuses": [
      {
        "id": 'screen-status',
        "type": 'String',
        "display": 'Screen is currently showing:',
        "order": 0,
      },
      {
        "id": 'last-game-played',
        "type": 'String',
        "display": 'Last game played:',
        "order": 1,
      },
    ],
    "controls": [],
    "settings": [],
  },
}
```

Running `example.py` should result in your software component now appearing online with two statuses.

### Going further

For a full tutorial, guides, and examples for this library as well as the Gumband platform and other additional resources go to [docs.gumband.com](https://docs.gumband.com/)

## Contributions & Feedback

Have any feedback about using this library or about the Gumband platform? Run into any issues? Until we have a dedicated issue/bug tracker reach out to [support@gumband.com](support@gumband.com).
