Metadata-Version: 2.1
Name: shinobi-client
Version: 3.0.1
Summary: A Python client for controlling Shinobi (an open-source video management solution)
Home-page: https://github.com/colin-nolan/python-shinobi-client
Keywords: shinobi,client,cli
Author: Colin Nolan
Author-email: cn580@alumni.york.ac.uk
Requires-Python: >=3.6,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Provides-Extra: cli
Provides-Extra: shinobi-controller
Requires-Dist: dataclasses (>=0.7,<0.8); python_version >= "3.6" and python_version < "3.7"
Requires-Dist: docker-compose (>=1.25,<2.0); extra == "shinobi-controller"
Requires-Dist: fire (>=0.3.0,<0.4.0); extra == "cli"
Requires-Dist: get-port (>=0.0.5,<0.0.6); extra == "shinobi-controller"
Requires-Dist: gitpython (>=3,<4); extra == "shinobi-controller"
Requires-Dist: logzero (>=1.5.0,<2.0.0)
Requires-Dist: requests (>=2.23,<3.0)
Requires-Dist: toml (>=0.9,<0.10)
Project-URL: Repository, https://github.com/colin-nolan/python-shinobi-client
Description-Content-Type: text/markdown

[![Build Status](https://travis-ci.com/colin-nolan/python-shinobi-client.svg?branch=master)](https://travis-ci.com/colin-nolan/python-shinobi-client)
[![Code Coverage](https://codecov.io/gh/colin-nolan/python-shinobi-client/branch/master/graph/badge.svg)](https://codecov.io/gh/colin-nolan/python-shinobi-client)
[![PyPi](https://img.shields.io/pypi/dm/shinobi-client)](https://pypi.org/project/shinobi-client)

# Shinobi Python Client
_A Python client for controlling [Shinobi](https://gitlab.com/Shinobi-Systems/Shinobi) (an open-source video management 
solution)._


## About
This package contains an (very incomplete) set of tools for interacting with Shinobi using Python.

This library tries to use the (rather unique) [documented API](https://shinobi.video/docs/api) but it also uses 
undocumented endpoints (which may not be stable).


## Installation
Install from [PyPi](https://pypi.org/project/shinobi-client/):
```bash
pip install shinobi-client
```

Install with ability to start a Shinobi installation:
```bash
pip install shinobi-client[shinobi-controller]
```

Install with CLI:
```bash
pip install shinobi-client[cli]
```

## Usage
_Warning: methods are generally not thread safe._

### Python
Start with creating the client for a particular Shinobi installation:
```python
from shinobi_client import ShinobiClient

shinobi_client = ShinobiClient(host, port, super_user_token=super_user_token)
```
(`super_user_token` is optional and only required for some operations.)

#### User
```python
user = shinobi_client.user.get(email)
# Get user details using the user's password (does not require super user token)
user = shinobi_client.user.create(email, password)

users = shinobi_client.user.get_all()

user = shinobi_client.user.create(email, password)

modified = shinobi_client.user.modify(email, password=new_password)

deleted = shinobi_client.user.delete(email)
```

#### API Key
```python
api_key = shinobi_client.api_key.get(email, password)
```

#### Monitor (Camera Setup)
```python
# Setting monitors (camera setups) for the user with the given email address
monitor_orm = shinobi_client.monitor(email, password)

monitors = monitor_orm.get_all()

monitor = monitor_orm.get(monitor_id)

monitor = monitor_orm.create(monitor_id, configuration)

modified = monitor_orm.modify(monitor_id, configuration)

deleted =  monitor_orm.delete(monitor_id)
```

#### Shinobi Controller
Starts/Stops a temporary [containerised installation of Shinboi](https://github.com/colin-nolan/docker-shinobi). Written
for the purpose of testing but it is also installable as an extra. Requires Docker.
```python
from shinobi_client import start_shinobi

with start_shinobi() as shinobi_client:
    print(shinobi_client.url)
    # Do things with a temporary Shinobi installation
```
or
```python
from shinobi_client import ShinobiController

controller = ShinobiController()
shinobi_client = controller.start()
print(shinobi_client.url)
# Do things with a temporary Shinobi installation
controller.stop()
```

### CLI
A basic auto-generated CLI is available if the package is installed with the `cli` extra: 
```bash
PYTHONPATH=. python shinobi_client/user.py \
        --host=HOST --port=PORT --super_user_token=SUPER_USER_TOKEN \
    get user@example.com
```
e.g.
```bash
$ PYTHONPATH=. python shinobi_client/cli.py \
        --host='0.0.0.0' --port=50694 --super_user_token='26dd3352-73c4-4bbd-8b09-17f2aacbd7b9' \
    create 'user@example.com' 'password123'
```


## Development
Install with dev-dependencies:
```bash
poetry install --no-root --extras "shinobi-controller cli"
```

Run tests with:
```bash
python -m unittest discover -v -s shinobi/tests
```


## Legal
[GPL v3.0](LICENSE.txt). Copyright 2020 Colin Nolan.

I am not affiliated to the development of Shinobi project in any way. This work is in no way related to the company that
I work for.

