52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
# BreCal API Client
|
|
|
|
Minimal Python helper for `misc/BreCalApi.yaml`. It focuses on the login, shipcall, and times endpoints needed by CLI tools, but the helper method `BreCalClient.raw_request` makes it straightforward to call any other endpoint defined in the OpenAPI specification.
|
|
|
|
Dependencies: only the `requests` package in addition to the standard library.
|
|
|
|
## Endpoint selection
|
|
|
|
`BreCalClient` reads its default `base_url` from `~/.config/brecal/client.json`. The file lets you define multiple deployments and switch between them without modifying code:
|
|
|
|
```json
|
|
{
|
|
"environment": "devel",
|
|
"endpoints": {
|
|
"local": "http://localhost:5000",
|
|
"devel": "https://brecaldevel.bsmd-emswe.eu",
|
|
"test": "https://brecaltest.example.net",
|
|
"prod": "https://brecal.example.com"
|
|
}
|
|
}
|
|
```
|
|
|
|
Override the selection at runtime via `BreCalClient(base_url="...")` or the environment variable `BRECAL_BASE_URL`. If no config is present the client falls back to the development server URL.
|
|
|
|
## Credentials
|
|
|
|
Store credentials in `~/.config/brecal/credentials.json`:
|
|
|
|
```json
|
|
{
|
|
"username": "alfred",
|
|
"password": "123456"
|
|
}
|
|
```
|
|
|
|
You can override the location when calling `Credentials.load("/path/to/file.json")` or provide credentials from environment variables via `Credentials.from_env()`.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from brecal_api_client import BreCalClient, Credentials
|
|
|
|
creds = Credentials.load()
|
|
with BreCalClient(credentials=creds) as client:
|
|
# list ship calls from the last week
|
|
shipcalls = client.get_shipcalls(past_days=7)
|
|
|
|
# create/update ship calls or times
|
|
shipcall_id = client.create_shipcall({...})
|
|
times = client.get_times(shipcall_id=shipcall_id)
|
|
```
|