Metadata-Version: 2.1
Name: bioto-client
Version: 0.1.5
Summary: A python CLI client for accessing Bioto data
Author: Bioto
Author-email: it@bioto.co
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: auth0-python (>=4.0.0,<5.0.0)
Requires-Dist: pydantic (>=1.10.4,<2.0.0)
Requires-Dist: python-dotenv (>=0.21.1,<0.22.0)
Requires-Dist: requests (>=2.28.2,<3.0.0)
Requires-Dist: typer[all] (>=0.7.0,<0.8.0)
Description-Content-Type: text/markdown

# PyClient

Python Client for retrieving Bioto sensor data

## Goals

### Auth0 login

- [x] As a user I can login via auth0 to get a valid access token

Both of these steps can be accomplished by enabling device authentication.

### Retrieving sensor data

- [x] As a user I can find a garden
- [x] As a user I can subscribe to that garden
- [x] As a user I can see my subscribtion state for that garden
  (pending/approved/declined)
- [x] As a user I can get an overview of "my gardens"
- [x] As a user I can retrieve sensor data from my gardens
  - current
  - raw data up to 7 days ago
  - downsampled data when more than 7 days ago

## Getting started

Software is installed via make (see below), this will setup a [virtual python
environments][3] managed via [`poetry`][4]

```bash
% pip install --user bioto-client
```

## How to use

When not installed as a python package but via `make install` run `poetry shell`
from the root of the project first. Otherwise the first step can be skipped.

### Start a user session

A user session is valid for 24h. When expired you're requested to create a new
session. This can be done as follows:

```bash

# Call the client with the `user` command to assert a valid session
% bioto-client user

Loading session

Not logged in, please take the following steps:

1. On your computer or mobile device navigate to: https://biotoco.eu.auth0.com/activate?user_code=NEWT-OKEN
2. Enter the following code:  NEWT-OKEN

Succesfully logged in.

Bioto CLI client: 1.2.3
Environment: prod
Session token ***5OFd09w
```

### Find a garden

Gardens can be found by name, the command to do this is:

```bash
% bioto-client search-garden {name}
```

### Subscribe to a garden

To gain access to the data of this garden you need to subscribe to this garden
using its `ID`:

```bash
% bioto-client subscribe-garden 94557f42-e08f-4431-a49d-2a0793be65a7
```

This will create a subscription request which only the mainter(s) can approve.
To check the state of your subscription see:

```bash
% bioto-client subscriptions
```

### Read device data

Reading a device is done by `device ID`, these can be found via the garden
command. Note that a garden might contain multiple devices.

To get the latest hourly readings for the last 24h issue the following command:

```bash
% bioto-client device {device_id}
```

To get these readings for a sepecific date this can be added as the second
argument whith these formats allowed: [%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %H:%M:%S]:

```bash
% bioto-client device {device_id} {date}
```

And to limit or increase the number of hours returned add this as a last
argument:

```bash
% bioto-client device {device_id} {date} {hours_limit}
```

> **Tip** Use `bioto-client --help` to see other available commands

## Improve the client

If you want to improve the client or add something which you think is missing to
the project you can either [open an issue][1] or develop the feature yourself
and open [a pull request with your changes][2].

To get started clone this project and create a branch. Now fix the bug or create
the feature you want and write some tests for it to prove it works. This can be
done by executing:

```bash
% make check
```

> **Note** This will run both tests and linters, use `make test` when you're in
`red - green - refactor` mode

When the checks are all passing, please open a [PR][2]

[1]: https://github.com/wearebioto/PyClient/issues
[2]: https://github.com/wearebioto/PyClient/pulls
[3]: https://docs.python.org/3/library/venv.html
[4]: https://python-poetry.org/docs/

