Quant Trading for Programmers 27: Record Paper-Trading Daily Reports In Files

Article 26 abstracted notification channels. Now the system needs one concrete implementation that really runs.

Article 27 starts with a file-based channel: write daily report delivery records into JSONL. It is not the final notification solution, but it is very useful for local debugging and test replay.

Why Write Files First

Real notification platforms bring network calls, authentication, rate limits, and configuration.

All of that matters, but it is not the most important problem at this point. First, we need to prove that the daily flow can produce a report, the channel can accept it, and the send result can be saved.

JSONL Delivery Records

Chapter 27 adds app/file_notifications.py.

FileNotificationChannel writes each send action as one JSON line:

channel = FileNotificationChannel(path=Path("data/paper-alerts.jsonl"))
receipt = send_paper_alert(channel, message, destination="paper-daily", sent_at=now)

Each line contains the channel, acceptance status, destination, title, send time, severity, body, and error information.

Why Not CSV

The daily report body may naturally contain line breaks. CSV can handle that, but JSONL is easier to read and append.

The advantage of JSONL is that each line is a complete record. Later it can be read line by line, and command-line tools can inspect it quickly.

It also has an engineering advantage: append writes are naturally suitable for local audit logs. Even if the program exits halfway, already-written lines will not become unreadable just because a large JSON array was not closed.

Current Integrated Run

Continue running the same command:

uv run python -m scripts.chapter_examples paper-notify

The file channel writes the daily report into paper-alerts.jsonl, and the example command then reads it back through read_file_notifications():

The screenshot keeps the core fields from one JSONL line. When Lark or email is connected later, the receipt structure can stay similar. Only the channel name and external-platform fields need to change.

Chapter Update And Repository

This chapter adds:

• app/file_notifications.py.
• A file-based notification channel.
• Append-only JSONL delivery records.
• read_file_notifications() for reading records back.
• An integrated paper-notify example showing daily report delivery, JSONL records, and read-back output.
• Context on using JSONL as an append-only audit log.
• tests/test_file_notifications.py, covering valid sends, invalid sends, and missing-file reads.

Repository:

https://github.com/ax2/zi-quant-platform

Code for this chapter:

git clone https://github.com/ax2/zi-quant-platform.git
cd zi-quant-platform
git checkout chapter-27
uv sync --extra dev
uv run pytest tests/test_file_notifications.py

Chapter 27 is commit 5191340, tagged as chapter-27.

Summary

The file-based channel makes notification delivery verifiable first.

Article 27 does not connect any external platform, but it can already save daily report delivery records. The next article continues splitting boundaries by abstracting price inputs in the daily flow.

WeChat

Follow ZiCode on WeChat

If this post was useful, you can follow later updates on WeChat as well.

X / Twitter

Follow @ax2_zicode

Faster technical notes, short thoughts, and new-post alerts are posted on X.

X Open X Profile @ax2_zicode