Booking service¶
The booking service books a list of weekly classes for you. You describe the classes in a config file, and the service logs in, waits until the booking window opens and books them all at once:
python -m pysportbot.service --config config.json still works too, and takes the same options.
Credentials¶
Your credentials don't need to be in the config file. Set them as env vars instead:
export SPORTBOT_EMAIL="you@example.com"
export SPORTBOT_PASSWORD="your-password"
export SPORTBOT_CENTRE="your-centre-slug"
Configuration¶
The config file is JSON or TOML, chosen by its suffix. There are two ways to run it.
Book now¶
To book Yoga next Monday at 18:00 right away:
Book at a set time¶
Most centres open bookings a few days before the class. To book Yoga on Monday at 18:00 and Spinning on Tuesday at 07:00 as soon as bookings open on Friday at 07:30:
The service waits until the next Friday 07:30, then books each class on its next occurrence after that.
Classes are always in the future
A class on the same weekday as the booking is booked for the following week. With "booking_execution": "Friday 07:30", a class on Friday at 18:00 is booked for next Friday, not the same day.
Keys¶
| Key | Type | Required | Env var |
|---|---|---|---|
email |
string | yes, in the file or the env | SPORTBOT_EMAIL |
password |
string | yes, in the file or the env | SPORTBOT_PASSWORD |
centre |
string | yes, in the file or the env | SPORTBOT_CENTRE |
booking_execution |
"now" or "<weekday> <time>" |
no, defaults to "now" |
|
classes |
list of classes, each with activity (the name as listed by pysportbot activities; case and extra spaces are ignored), class_day (weekday) and class_time (time) |
yes, at least one | |
notify_url |
ntfy topic URL, see Notifications | no, notifications are off without it | SPORTBOT_NOTIFY_URL |
notify_on |
"always" or "failure" |
no, defaults to "always" |
SPORTBOT_NOTIFY_ON |
notify_language |
"en", "de", "es", "fr" or "it" |
no, defaults to "en" |
SPORTBOT_NOTIFY_LANGUAGE |
- Env vars override the matching keys in the file. Empty env vars are ignored.
- Weekdays are English day names or their 3-letter abbreviations, in any case, e.g.
Mondayormon. - Times use the 24-hour format
HH:MMorHH:MM:SS, e.g.18:00. In TOML, unquoted times such asclass_time = 18:00:00work too. - Unknown keys are errors, so a typo such as
centerdoesn't go unnoticed. The service reports all problems in the file at once and exits with code 2.
Options¶
| Option | Default | Description |
|---|---|---|
--booking-delay SECONDS |
0 |
Wait this long after the execution time before booking. |
--poll-interval SECONDS |
0.5 |
Time between attempts while a slot is not bookable yet or not found. Must be positive. |
--poll-window SECONDS |
60 |
How long to keep polling after booking starts. |
--retry-attempts N |
3 |
Attempts per class for errors that may be temporary, such as network errors. Must be at least 1. |
--retry-delay SECONDS |
5 |
Time to wait after such an error. |
--max-threads N |
no limit | How many classes to book in parallel. |
--notify-on {always,failure} |
always |
When to send a notification. Overrides notify_on and SPORTBOT_NOTIFY_ON. |
--dry-run |
Do everything except send booking requests, see below. | |
--time-zone TZ |
Europe/Madrid |
The time zone of the centre. |
--log-level LEVEL |
INFO |
DEBUG, INFO, WARNING, ERROR or CRITICAL. |
Delays can be fractions of a second, e.g. --retry-delay 0.5, and must not be negative.
All classes are booked in parallel. With --max-threads, the remaining classes are booked as soon as a thread is free, in the order of the config file.
Dry run¶
--dry-run logs in, waits until the execution time and checks that each slot exists and is neither full nor cancelled, but it doesn't send any booking requests.
With "booking_execution": "now" it runs straight away, which makes it a quick way to check a new config file:
A successful dry run doesn't guarantee the real booking, though: a slot can still fill up in the meantime.
How the service books¶
Popular classes fill up within seconds of the booking window opening, so the service gets ready a minute early and then tries quickly at the opening time:
T-60 s log in again if the session expired (retrying on failure), and look up each slot
T book: one request per class, all classes at once
T…T+60 s try again every 0.5 s while a slot is "not bookable yet"
Here T is the booking_execution time plus --booking-delay, and polling stops --poll-window seconds after T.
Each class looks up its own slot, so one slow lookup doesn't hold up the others. If a slot can't be found at T-60 s, e.g. because the calendar isn't published yet, it is looked up again when booking.
With "booking_execution": "now", the service books straight away.
What happens after a failed attempt depends on the error:
| Error | What happens | Result |
|---|---|---|
| Not bookable yet, not available, or slot not found | Try again every --poll-interval seconds until --poll-window ends. Polls don't count as retry attempts. |
failed or not found once the window ends |
| Network error, unexpected API response or unknown error code | Try again after --retry-delay seconds, up to --retry-attempts attempts. |
failed after the last attempt |
| Already booked | Stop. This includes a booking that timed out but went through: the next attempt finds it already booked. | already booked |
| Full | Send one booking request anyway, in case one of the places is already yours, then stop. | full, or already booked |
At the end, the service logs a summary with the status and number of attempts for each class.
It exits with code 0 if every class is booked or already booked (or would be booked, in a dry run), and with code 1 otherwise. That way a failed booking is easy to spot, e.g. as a failed scheduled run in GitHub Actions.