email_manager
email_manager.py — two ways for a client to tell a human
something. Something urgent (an order rejected, a broker connection down) goes out
immediately via send/send_email. Something routine (today's
fills, a reconciliation pass that found nothing wrong) gets contributed to a shared digest
via report, and a separate scheduled client renders and sends it once.
Immediate send
send_email(subject, body, to = None, account = None, to_account = None)
Module-level convenience function, re-exported from quantstrip. Equivalent
to calling email_manager.send(...) with html=False. Returns
(success: bool, message: str) — log message on failure rather
than assuming the call always succeeds.
email_manager.send(subject, body, to = None, account = None, to_account = None, cc = None, html = False)
The underlying send — import email_manager directly when you need
cc, an HTML body, or a non-default sender account.
Recipient resolution, in order: the literal to address if
given; otherwise the named receiver account in to_account if given;
otherwise the default receiver account. Most installs are a single-person operation with
exactly one receiver configured, so a client never has to hardcode a recipient.
Sender resolution: the named sender account in account if
given, otherwise the default sender account.
from quantstrip import send_email
send_email(
subject="Strategy alert",
body="Position limit reached for SPY.",
)
self.notify_exception(error_message, traceback_text=None) — a
ClientBase method, not email_manager — is a throttled,
automatic alert already wired into every client's main_loop. See
quantstrip.
The report digest
Lets any client contribute to a named report without knowing anything about email or
HTML. Reports are keyed by (name, date), so more than one distinct report
can exist on the same day. A separate scheduled client later calls
get_report_for_render and report_summary to render everything
contributed for a given (name, date) into one HTML digest and send it — see
daily_reporting_client.py for a working example.
report.add_section(report_name, client_name, title, rows, date = None)
Contributes a plain-text section, rendered as a bulleted list. A second call today with
the same (report_name, client_name, title) appends to the same section
instead of creating a new one.
report.add_table(report_name, client_name, title, columns, rows, date = None)
Contributes a column-aligned table as an append-only log. Right for a log (e.g. intraday
executions as they're found); wrong for "current state" data — use
set_table_row for that.
from email_manager import report
report.add_section(
report_name="Daily Summary",
client_name=self.display_name,
title="Reconciliation notes",
rows=["All fills matched.", "0 unattributed trades."],
)
report.add_table(
report_name="Daily Summary",
client_name=self.display_name,
title="Fills today",
columns=["Time", "Symbol", "Side", "Qty"],
rows=[["09:31:02", "SPY", "BUY", "100"]],
)
report.set_table_row(report_name, client_name, title, key, columns, row, date = None)
Like add_table, but for "current state" data: key identifies
this row within the section — if a row with the same key was already posted today, it's
replaced in place instead of appended as a duplicate. key is entirely
caller-defined — a symbol, an "account:conid" pair, whatever identifies one
of your own rows.
report.get_report_for_render(report_name, date = None)
Fetches everything contributed for (report_name, date), already decoded.
Returns (report_row, sections), or (None, None) if nothing was
contributed.
report.mark_sent(report_name, date = None)
Flips the report's status to sent. Call after a successful send so a
service restart doesn't re-send the same digest.
report_summary(report_row, sections, timestamp = None)
Module-level function — builds the subject and HTML body for a consolidated digest from
whatever get_report_for_render returned. Returns
(subject: str, html_body: str) — pass straight into
email_manager.send(subject, html_body, html=True).
from email_manager import (
report, report_summary, email_manager,
)
report_row, sections = report.get_report_for_render(
"Daily Summary",
)
if report_row is not None:
subject, html_body = report_summary(
report_row, sections,
)
ok, msg = email_manager.send(
subject, html_body, html=True,
)
if ok:
report.mark_sent("Daily Summary")
type (list vs table) is purely a
layout switch, not a severity marker. Something actually wrong calls
send/notify_exception immediately.
Accounts
An account is either a sender (full SMTP configuration) or a
receiver (just a name and an email address — the common
single-person-operation case). Both are rows in the same table, distinguished by
account_type.
email_manager.get_account(name)
Look up one account (sender or receiver) by name. Returns
Optional[EmailAccount].
email_manager.get_accounts(account_type = "sender")
All configured accounts of one type. Returns Dict[str, EmailAccount], keyed
by account name. get_receivers() is shorthand for
account_type="receiver".
email_manager.get_default_account() / get_default_receiver()
The account marked default for its type — what send falls back to when
account/recipient isn't given.
@dataclass
class EmailAccount:
email_account_id: int
name: str
provider: str
smtp_server: str # "" on a receiver
smtp_port: int
use_tls: bool
username: str # "" on a receiver
password: str # "" on a receiver
from_address: str # contact's email, on a receiver
from_name: str # contact's name, on a receiver
is_default: bool = False
account_type: str = "sender" # "sender" | "receiver"
@property
def email_address(self) -> str:
"""Alias for from_address."""
secret-typed Settings values.