README.md

# RSVP python

This repo contains the implementation of the *RSVP (Request-and-Stream Variable Protocol)* for python. 

The general protocol is described in more details [here][1].

## Add pyrsvp to your project

The CI publishes a *pypy* package on gitlab. This package can be used in other projects.

### Add pyrsvp to Poetry project

Add a secondary source to your poetry project

```bash
poetry source add -s igib https://labinfo.ing.he-arc.ch/gitlab/api/v4/projects/2369/packages/pypi/simple
```

Add *pyrsvp* package

```bash
poetry add pyrsvp --source igib
```

### Add using PIP

```bash
pip install pyrsvp --index-url https://labinfo.ing.he-arc.ch/gitlab/api/v4/projects/2369/packages/pypi/simple/
```

## Quick start

### Server

Here is an example of how to create a RSVP server running on TCP. The basic idea is to create
an instance of the RsvpServer and add command callback functions that will be called when a specific
command is received.

```py
#Define commands and their callbacks

# @RsvpServer.Command("EXCEPTION")
def handle_exception(ex : Exception) -> str:
    
    error =f"{type(ex).__name__} {ex}"

    try:
        raise ex
    except Exception as ex:
        print(f"{type(ex).__name__}: {ex}")

    return RsvpServer.reply(False, [RsvpString("ERROR", error)])

@RsvpServer.Command("START")
def start(values : dict) -> str:
    
    print(values)

    return RsvpServer.reply(True, [RsvpInteger("CODE", 1)])


if __name__ == "__main__":

    srv = RsvpServerTcp("", port)
    srv.run()
```

To add a command put decorator above your function. All the function will get a dict containing the 
arguments sent by the client. 

```py
@RsvpServer.Command(<COMMAND_NAME>)
def function(args : dict)
```

Each callback must return a reply string using the following function

```py
return RsvpServer.reply(ack : bool, args : list[RsvpBaseType])
```

There is only one callback predefined with and it's called *"EXCEPTION"* it called if an exception
is raised during the processing of the data. If this command is not defined the exception will be raises.

### Client

The client can be used to exchange data with the server.

```py
def start_cb(args : dict):
    print(args)

if __name__ == "__main__":

    client = RsvpClientTcp()

    args = [
        RsvpInteger("ARG1", 1),
        RsvpDouble("ARG2", 2.0),
    ]

    try:
        print(client.send_command("START", args, callback=start_cb))
    except Exception as ex:
        print(f"[{type(ex).__name__}] Error: {ex}")
```

A method called send data is available to send data to the server:

```py
client.send_command(cmd_name: str, args: list[svpBaseType], function = None)
```

The function take the command name as a string, a list containing the arguments as RsvpBaseType and
an optional callback function that will be called when the server answer. If the callback is not defined the
function will return received data as a dict.


### RsvpType classes

To mitigate errors we encourage the use of the special types for arguments. Available types are:

```py
RsvpInteger(name: str, value : int)
RsvpDouble(name: str, value : float)
RsvpBool(name: str value : bool)
RsvpString(name: str, value: str)
RsvpVectorDouble(name: str, value: dict[str, float])
RsvpVectorString(name: str, value: list[str])
```

All type are checked when creating a new object and it will raise an *RsvpWrongTypeException* exception the
*value* parameter is not of the correct type.

## Usage examples

In the *examples* folder you'll find some usage examples

## Developers

### Dependencies

| | |
|-|-|
| Poetry | >= 1.2.0 |

Install python dependencies:

```bash
poetry install
```

### Run tests

```bash
poetry run pytest -v -s tests
```

### TODO list

- [X] Add CI/CD for tests and wheel generation
- [ ] Add serial support

[1]:https://labinfo.ing.he-arc.ch/gitlab/igib/documents-latex/rsvp-specs