git_brcal/src/brecal_api_client/README.md

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:

{
  "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:

{
  "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

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)