correspond.notify

Make a draft’s notify list a property of sending, not a rule a sender can forget.

A Draft may name who must be notified (Draft.notify). Each writer then guarantees it in its platform’s terms: a mention added to the text when it is absent (GitHub, Telegram), an address in To or Cc (email). A channel whose capabilities.notify is none refuses such a draft with NotSupported("notify") before anything is planned, so a notification is never silently dropped.

These helpers are pure: the writers call them while building the plan, so the dry run shows the exact text, or the exact Cc, that will go out.

>>> with_mentions("Fixed in #12.", ["octocat", "@hubot"])
'Fixed in #12.\n\ncc @octocat @hubot'
>>> with_mentions("Thanks @Octocat, fixed.", ["octocat"])
'Thanks @Octocat, fixed.'

Module Attributes

DFLT_MENTION_LEAD

The line that carries the mentions a text lacked, before the handles.

Functions

handle(name)	A handle without its leading @.
is_mentioned(text, name)	Is @name in text as a whole mention that notifies? Case-insensitive.
missing_mentions(text, names)	The handles in names that text does not mention yet, in order, each once.
with_copies(to, cc, names)	cc plus every address in names that is neither to nor already copied (case-insensitive).
with_mentions(text, names, *[, lead])	text with a closing cc @a @b line naming every handle it did not mention.

correspond.notify.DFLT_MENTION_LEAD = 'cc'

The line that carries the mentions a text lacked, before the handles.

correspond.notify.handle(name)

A handle without its leading @.

>>> handle("@octocat"), handle("octocat")
('octocat', 'octocat')

Return type:

str

correspond.notify.is_mentioned(text, name)

Is @name in text as a whole mention that notifies? Case-insensitive.

Not inside an address or a longer handle, and not inside code or an HTML comment, where platforms render it without notifying anyone.

>>> is_mentioned("ping @octocat.", "octocat")
True
>>> is_mentioned("mail octocat@example.org", "octocat")
False
>>> is_mentioned("ping @octocat-two", "octocat")
False
>>> is_mentioned("see `@octocat` and <!-- @octocat -->", "octocat")
False

Return type:

bool

correspond.notify.missing_mentions(text, names)

The handles in names that text does not mention yet, in order, each once.

Return type:

tuple[str, ...]

correspond.notify.with_copies(to, cc, names)

cc plus every address in names that is neither to nor already copied (case-insensitive).

>>> with_copies("a@example.org", ["b@example.org"], ["A@example.org", "c@example.org"])
('b@example.org', 'c@example.org')

Return type:

tuple[str, ...]

correspond.notify.with_mentions(text, names, *, lead='cc')

text with a closing cc @a @b line naming every handle it did not mention.

Return type:

str