annie.core.bugreport

Bug reports from the Log tab: what is sent, where to, and how often (service).

The Log tab’s Report button emails an error to Annie’s maintainer. Annie cannot send mail itself, so the report goes to a form-to-email service (Web3Forms) over HTTPS, from the user’s browser, where Annie’s UI runs. The service’s access key decides the recipient, so no email address is stored here; the key is public by design (it can only deliver to that one inbox).

Before anything is sent, the user sees the exact text (build_report()) and may add a note. Each error can be reported once, and at most MAX_REPORTS_PER_HOUR reports leave one Annie per hour, so a crash loop cannot flood the inbox.

Attributes

REPORT_SUBJECT	The email subject of every report.
REPORT_URL	Where reports are posted (JSON); the service emails them to the maintainer.
ACCESS_KEY	The Web3Forms access key bound to the maintainer's inbox (public by design).
MAX_REPORTS_PER_HOUR	How many reports one Annie process sends per hour at most.

Functions

access_key(→ str)	The access key in use: ANNIE_REPORT_KEY if set, else the built-in key.
reporting_available(→ bool)	Whether reports can be sent (an access key is configured); see access_key().
build_report(→ str)	The plain text that is sent, exactly as the user previews it.
payload(→ dict[str, str])	The JSON body the form-to-email service expects (key defaults to the key in use).
already_sent(→ bool)	Whether the error with log sequence number seq was reported already.
can_send(→ bool)	Whether another report fits within MAX_REPORTS_PER_HOUR.
mark_sent(→ None)	Remember that the error seq was reported, for the Sent state and the limit.
reset(→ None)	Forget sent reports (for tests).

Module Contents

annie.core.bugreport.REPORT_SUBJECT = 'Annie bug report'

The email subject of every report.

annie.core.bugreport.REPORT_URL = 'https://api.web3forms.com/submit'

Where reports are posted (JSON); the service emails them to the maintainer.

annie.core.bugreport.ACCESS_KEY = '2ac1f9d9-3a01-4c94-a74c-87c623e9717f'

The Web3Forms access key bound to the maintainer’s inbox (public by design).

It can only deliver to that inbox; if it is ever abused, reset it on web3forms.com and ship the new one in a release. ANNIE_REPORT_KEY in the environment overrides it (e.g. to test with another inbox); an empty key turns reporting off.

annie.core.bugreport.MAX_REPORTS_PER_HOUR = 5

How many reports one Annie process sends per hour at most.

annie.core.bugreport.access_key(environ: collections.abc.Mapping[str, str] | None = None, built_in: str | None = None) → str

The access key in use: ANNIE_REPORT_KEY if set, else the built-in key.

Parameters:

• environ – The environment to read (default: the process environment).

• built_in – The key shipped with this release (default ACCESS_KEY).

annie.core.bugreport.reporting_available(environ: collections.abc.Mapping[str, str] | None = None, built_in: str | None = None) → bool

Whether reports can be sent (an access key is configured); see access_key().

annie.core.bugreport.build_report(event: annie.core.logbook.LogEvent, note: str, *, version: str) → str

The plain text that is sent, exactly as the user previews it.

Parameters:

• event – The logged error being reported.

• note – What the user was doing (optional; may be empty).

• version – The running Annie version.

Returns:

the note, the error with its full details, and where it happened (Annie, Python and OS versions). Nothing else from the PC is included.

Return type:

The report

annie.core.bugreport.payload(text: str, key: str | None = None) → dict[str, str]

The JSON body the form-to-email service expects (key defaults to the key in use).

annie.core.bugreport.already_sent(seq: int) → bool

Whether the error with log sequence number seq was reported already.

annie.core.bugreport.can_send(now: float | None = None) → bool

Whether another report fits within MAX_REPORTS_PER_HOUR.

annie.core.bugreport.mark_sent(seq: int, now: float | None = None) → None

Remember that the error seq was reported, for the Sent state and the limit.

annie.core.bugreport.reset() → None

Forget sent reports (for tests).