Settings
Read the settings of the terminal and of an order book, change them, and follow changes.
Reading settings needs the settings:read scope. Changing them needs
settings:write.
Read settings
settings = terminal.settings(category="multiview")
for row in settings.data:
print(row.category, row.key, row.value, row.writable)A setting is a row with a category, a key and a value. writable tells
whether the API can change it. Without arguments you get the settings of the
whole terminal.
| Argument | Meaning |
|---|---|
category, key | Only the rows of this category or key. |
scope | global, the default, or order_book. |
instrument | The rows saved for the order book of this instrument. |
connection_id | The rows saved for this connection. |
Read the settings of an order book
book = terminal.orderbook_settings(12, "binance:futures:BTCUSDT")
for category, keys in book.data.items():
for key, setting in keys.items():
print(category, key, setting.value, setting.resolved_from)The call above shows what is saved. This one shows what an order book ends
up with: it takes each setting from the first place that has a value, and
resolved_from names that place.
resolved_from | Where the value is saved |
|---|---|
instrument | For this instrument on this connection |
connection | As the default of the connection |
app_instrument | For this instrument without a connection |
global | As the default of the terminal |
Change a setting
from spectre_terminal import SettingChange
applied = terminal.update_settings([
SettingChange("multiview", "stack_width_px", 300),
SettingChange("general", "auto_scroll", True, instrument="binance:futures:BTCUSDT", connection_id=12),
])
print(applied.applied)A call takes up to 100 changes. Where a change is saved depends on what you pass with it.
| You pass | The change is saved |
|---|---|
instrument | For the order book of this instrument |
scope="order_book" and connection_id | As the order-book default of the connection |
scope="order_book" alone | As the order-book default of the terminal |
| Nothing else | As a setting of the whole terminal |
The terminal checks every change against its list of settings first. If one is refused, nothing is saved.
Then the changes are applied in order. If one fails, the call stops with an error, and the changes before it stay applied.
Leverage is not changed through settings. Use Change the leverage.
Change the theme or a hotkey
from spectre_terminal import SettingChange
terminal.update_settings([
SettingChange("appearance", "theme", {"stack": "dark"}),
SettingChange("hotkeys_orderbook", "close_position", {"code": "KeyX", "modifiers": []}),
])The theme takes any of stack, graphic and interface. The last two take
only light or dark.
A hotkey takes code and modifiers, or null. A combination that another
action uses is refused.
Follow changes
import asyncio
from spectre_terminal import Event
async def main():
async with terminal.stream() as stream:
await stream.subscribe("settings")
async for frame in stream:
if isinstance(frame, Event) and frame.topic == "settings":
print(frame.data.scope, frame.data.category, frame.data.key, frame.data.value)
asyncio.run(main())A frame comes for every saved row, whoever saved it. A subscription sends no
starting state, so read the values with settings() first. More in
Streaming.
When a call fails
| What happens | What you get | What to do |
|---|---|---|
| An unknown key, a wrong type or form of the value, a number out of range | 400 invalid_request | Nothing was saved. Fix the change the message names |
| The setting is leverage or a service row of the terminal | 501 unsupported | Nothing to retry |
| More than 5 settings writes a second, for the whole terminal | 429 rate_limited | Slow down, see Limits |
| The terminal could not read or save the settings | 503 unavailable | Call again |