jrc_email

Shared HTML building blocks for Janelia DIS run-summary emails.

A small, dependency-free (standard-library only) toolkit for composing the house-style run-summary email used by the DIS sync/pull programs: a navy header banner, a row of KPI stat tiles, section cards listing DOIs, and a footer — all as inline-styled tables that survive Outlook's Word rendering engine.

Installation

pip install git+https://github.com/JaneliaSciComp/jrc_email.git

Usage

import jrc_email.jrc_email as JE

kpis = ''.join([
    JE.kpi_card(f"{read:,}",  "Read from Elsevier"),
    JE.kpi_card(f"{held:,}",  "Not yet published", 'warn' if held else 'neutral'),
    JE.kpi_card(f"{ready:,}", "Ready to process",  'good' if ready else 'neutral'),
])

body = JE.body_row(
    JE.section_header(f"✓ Ready to Process ({ready:,})")
    + JE.doi_card("Ready to Process", [(doi, None) for doi in ready_dois], 'good'))

html = JE.render('pull_elsevier.py', __version__, run_data,
                 mode_label='TEST', mode_tone='warn',
                 kpi_cards=kpis, body_rows=body)

JRC.send_email(html, sender, recipient, "Elsevier DOI sync", mime='html')

API

Name	What it produces
NAVY, GREEN, AMBER, RED, GRAY, *_BG, STRIPE_BG, BORDER, BLUE, PAGE_BG	The house palette (status colors + neutrals)
doiurl(doi, base=…)	An HTML-escaped anchor to a DOI's DIS UI page
pill(bg, fg, text)	A small colored status badge (single-cell table)
kpi_card(value, label, tone, width)	One KPI stat tile (<td>); tone ∈ neutral/good/warn/bad
section_header(title)	A section header bar
doi_card(label, entries, tone, second_header, icon)	A titled, count-pilled, zebra-striped DOI table, with an optional right-hand column
body_row(content, padding)	Wraps a body block in a container table row
render(script_name, version, run_data, mode_label, mode_tone, kpi_cards, body_rows, footer_note)	Assembles the full email (banner + KPI row + body + footer)

Design notes / Outlook

Every helper emits inline styles only (no <style> block or CSS classes) and uses the patterns that render reliably in Outlook desktop (its Word engine is the binding constraint):

• Status color is always paired with an icon and/or descriptive label — never color alone (colorblind accessibility).
• Colored boxes carry both the bgcolor attribute and a background-color style; Word honors the attribute where it ignores the CSS.
• Pills are single-cell tables (Word ignores background-color on inline elements).
• KPI tiles stack value/label as inline <span>s split by a <br>, never block <div>s inside a styled <td> (Word leaks a block element's closing tag as literal text, e.g. 0</div>).
• Tile gaps come from the cellspacing attribute, not CSS margins.

Because HTML email renders differently everywhere, always preview a real message in Outlook desktop before relying on a layout change.