Metadata-Version: 2.4
Name: gumband
Version: 0.1.0a3
Summary: A library to connect to and interact with the Gumband platform
Project-URL: Homepage, https://gumband.com
Project-URL: Documentation, https://docs.gumband.com
Project-URL: Source, https://github.com/gumbandapp/gumband-python-sdk
Author-email: Gumband Team <support@gumband.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: gumband
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12
Requires-Dist: pyee>=12.1.1
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: requests>=2.32.3
Requires-Dist: websockets>=14.2
Description-Content-Type: text/markdown

# 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).
