quantstrip
The module every client script imports. quantstrip.py is a
single top-level module, not a package. It defines ClientBase and instantiates
the application's db, email, and settings singletons, shared by every client.
Import surface
Only ClientBase is documented on this page. db_handler,
email_manager, settings, and send_email are
re-exports — see db_handler,
email_manager, and settings
for their full method surfaces.
from quantstrip import (
ClientBase, # base class for your client
db_handler, # DBHandler singleton
email_manager, # EmailManager singleton
settings, # Settings singleton
send_email, # shorthand for email_manager.send()
)
class ClientBase
Base class for every client. Subclass it, do your setup in __init__ (after
calling super().__init__()), and schedule jobs on self.scheduler
(a schedule.Scheduler). You never start it yourself — deploy the file
through the Python IDE, which moves it into the live clients/ root
directory, and service.py's main loop picks it up and starts it
automatically.
from quantstrip import ClientBase
import logging
logger = logging.getLogger(__name__)
class Client(ClientBase):
def __init__(self, *args):
super().__init__()
self.display_name = "Default Client"
self.client_category = "Other"
self.scheduler.every(1).seconds.do(self.job)
def job(self):
try:
logger.info(f"Hello from {self.display_name}")
except Exception as e:
logger.error(f"job failed: {e}", exc_info=True)
self.notify_exception(f"{type(e).__name__}: {e}")
finally:
self.stop_client()
stop_client()
The one lifecycle method a client might realistically call on itself — typically from a
job's finally block, to run once and then stop (a one-shot test client, for
example; see the minimal example above). Sets the internal stop flag; the running
main_loop thread exits on its next iteration.
start_client()
Resets lifecycle state — clears the stop flag, records the start timestamp, resets
job_count and last_job_error, and stamps the initial heartbeat.
Part of the platform's own start sequence, called automatically by run_client
— not something a client calls itself.
get_resource_usage()
Returns None if the client hasn't been started yet. Otherwise a dict:
cpu_percent · thread_count · last_heartbeat ·
job_count · last_job_error. Backs the stats shown in the
Client Monitor.
run_client(client_id, thread_name = "Client - main_loop")
Called by service.py's main loop when a client is deployed — not something
your own client code calls. Starts main_loop on a background thread and sets
is_running = True. No-ops if already running, so a stray second call can't
spawn a second thread sharing this instance's schedule.Scheduler, which
isn't thread-safe.
main_loop()
Runs on the background thread started by run_client. Every 100ms: runs any
pending jobs on self.scheduler, increments job_count, and
updates the heartbeat. Continues until the stop flag is set.
A single job raising an exception is caught, logged, and recorded in
last_job_error — it does not stop the loop, and notify_exception
fires the generic alert email. An exception in the loop itself (outside a job) is fatal:
it's logged, exception is set to a "FATAL: ..." string, and the
client stops.
schedule's Job.run() calls your job function
before advancing its own next_run. An uncaught exception inside
a job freezes next_run in the past, and the job retries on every ~100ms
tick instead of its real interval.
Wrap your job's entire body in its own try/except — don't rely on
main_loop's outer catch to protect you from this.
notify_exception(error_message, traceback_text = None)
Sends the generic "this client hit an exception" alert email — the safety net
main_loop falls back to for any client that doesn't already have its own more
specific failure email. Throttled to at most once per failure streak. Recipient: a
Settings entry named after the client's module under
Settings/Notifications/Exception Alert Email, falling back to that folder's
Default entry. Silently a no-op (logged once) if neither is configured.
clear_exception_throttle()
Call at the end of a job that has its own try/except and completed successfully. Without this, a client with its own try/except gets a fresh alert email on every poll tick after a failure instead of once per failure streak.
def job(self):
try:
...
self.clear_exception_throttle()
except Exception as e:
logger.error(f"job failed: {e}", exc_info=True)
self.notify_exception(f"{type(e).__name__}: {e}")
Contract
- Class name must be exactly
Client— the loader usesgetattr(module, "Client"). - Constructor accepts
*args— the service passes itself as the first argument during load; a strategy typically doesn't need it. - Set
self.display_name— the name shown for this client in the Client Monitor. - Set
self.client_category— which section of the Client Monitor this client is grouped under. If a section with that name already exists, the client joins it; otherwise the Monitor generates a new section for it. Defaults to"Other"if unset. - Schedule jobs on
self.scheduler— theschedulelibrary, one instance per client. - Wrap every job's full body in its own try/except — see the warning above.
- Deploy through the Python IDE to go live —
service.py's main loop starts it automatically; you don't callrun_client()yourself.
"Strategy", "Trade Processing", and "Other"
are the built-in sections, shown in that order. Any other
self.client_category string gets its own new section.