Metadata-Version: 2.5
Name: readyview
Version: 1.18.0
Summary: ReadyLinks ReadyView API library.
Project-URL: Homepage, https://gitlab.com/readylinks
Project-URL: Issues, https://gitlab.com/readylinks
Author-email: ReadyLinks Developers <developers@ready-links.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: pydantic<3,>=2.4
Requires-Dist: requests
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Requires-Dist: responses>=0.23; extra == 'test'
Description-Content-Type: text/markdown

# ReadyView Dashboard Python Library

The ReadyView Dashboard Python library provides all current ReadyView [dashboard API](https://api.readylinks.io/redoc) calls to interface with the ReadyLinks ReadyView cloud-managed platform. ReadyView generates the library based on dashboard API's OpenAPI spec to keep it up to date with the latest API releases, and provides the full source code for the library including the tools used to generate the library. ReadyLinks welcomes constructive pull requests that maintain backwards compatibility with prior versions. The library requires Python 3.8+, receives support from the community, and you can install it via [PyPI](https://pypi.org/project/readyview/):

```
pip install --upgrdade readyview
```

## Usage
1. Export your Organization ID and API Key as an environment variable, for example:
```
export READYVIEW_DASHBOARD_ORG_ID=YOUR_ORG_ID
export READYVIEW_DASHBOARD_API_KEY=YOUR_API_KEY
```
2. Import the library with a single line at the top of your Python script.
```
import readyview
```
3. Instantiate the dashboard client. 
```
dashboard = readyview.Dashboard()
```
4. Start programmatically interacting with your ReadyView dashboard!
```
my_networks = dashboard.network.get_networks()
```

## Errors and strict mode
By default, a call that fails returns `None`, so existing scripts keep working. To find out why a call failed, turn on strict mode:

```python
import readyview

dashboard = readyview.Dashboard(raise_errors=True)

try:
    config = dashboard.switch.get_switch_configurations("AA:BB:CC:DD:EE:FF")
except readyview.ReadyViewAPIError as error:
    print(error)
    # GET /v1/devices/AA:BB:CC:DD:EE:FF/switch failed with HTTP 504: The device did not answer within the time limit.
```

In strict mode, a call that fails raises `readyview.ReadyViewAPIError`, which has:

- `status_code`: the HTTP status, such as 401, 404, 429 or 504. It is `None` when no reply arrived, because the API could not be reached or did not answer in time. Those calls raise the subclass `readyview.ReadyViewConnectionError`.
- `message`: why the call failed, as the API explained it.
- `method` and `path`: the call that failed, such as `GET` and `/v1/devices/AA:BB:CC:DD:EE:FF/switch`.
- `retry_after`: when the reply has a `Retry-After` header (usually with a 429, when you are rate limited), how many seconds it asks you to wait before trying again. Otherwise `None`.

The error is built from the API's reply only. It never repeats what you sent, or the values the API rejected, since those can be passwords.

Calls that work return the same values in both modes, with two differences in strict mode: any 2xx status counts as success, and a reply that is not JSON (say, a hotel network's sign-in page) raises `ReadyViewAPIError`.

### Logging
The library logs to the `readyview` logger with Python's `logging` module. It logs each reply at DEBUG. In the default mode, it also logs a failed call: an error status at INFO, and a request that got no reply at WARNING, which earlier versions printed. To see why calls return `None` without switching to strict mode:

```python
import logging

logging.basicConfig()
logging.getLogger("readyview").setLevel(logging.INFO)
```

## Contribute 
Create a branch to add your feature/fix then submit a merge request to main for review. Be sure to follow the correct format in your commit message to trigger the pipeline to 
submit a new release. Example commit below. 

```
feat: Added the ability to update switch configurations.
fix: Fixes some bug. 
BREAKING CHANGE: Updated function API. 
```

Run the tests before you submit:
```
pip install -e ".[test]"
pytest
```
