Notifier

Using the NotifierManager and notifiers, e.g. EmailNotifier you can create visual reports about the steps that the robot did. And send these reports via e-mail, print them out into terminal or import into Prefect.

Manager

class aiviro.modules.notifier.NotifierManager

Notifier manager provides an interface for propagating messages through several Notifiers. Where each notifier is specified by its scope.

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier
>>> nm = NotifierManager()
>>> # Adds root notifier
>>> nm.add_notifier(EmailNotifier("<client>", "Orders Title", "customer@cmp.com"))
>>> # Adds dev notifier
>>> nm.add_notifier(EmailNotifier("<client>", "[DEV] Orders Title", "developer@cmp.com"), scope="dev")
>>> nm.successful("Item added")  # Adds message into both notifiers
>>> nm.error("Something went wrong", scope="dev")  # Adds message only into 'dev' notifier
>>> blk = nm.create_block("New Block")  # Creates a shared block in both notifiers
>>> blk.successful("Great message !!")  # Message is added into shared block for both notifiers
>>> # sending reports
>>> nm.send_report()  # sends report to both notifiers
>>> nm.send_report(propagate=False)  # sends report only to the notifiers with "base" title
>>> nm.send_report(scope="dev")  # sends report to the notifier with "dev" title

property root_notifier: BaseNotifier

Returns notifier with an empty scope

add_notifier(notifier: BaseNotifier, scope: str = '') → NotifierManager

Adds new notifier with a specified scope

Parameters

• notifier – Notifier to add

• scope – Notifier’s scope to propagate messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier
>>> nm = NotifierManager().add_notifier(
...     EmailNotifier("..."), scope="dev"
... )

property last_block: aiviro.modules.notifier.notification.NotificationBlock

Returns last created NotificationBlock

create_block(title: str, block_id: Optional[str] = None, sort_notifications: bool = False, style: Optional[Style] = None, scope: str = '') → aiviro.modules.notifier.notification.NotificationBlock

Creates new block/section in the report.

Parameters

• title – Title of the block

• block_id – Identifier of the block, if not set ‘title’ is used as identifier

• sort_notifications – If True notification messages will be sorted in the block

• style – Style to automatically format Item messages.

• scope – Identification into which notifiers to add a new block

custom(title: str, text: MSG_TYPE, m_type: aiviro.modules.notifier.constants.NotificationType = NotificationType.INFO, scope: str = '') → Notification

Method creates custom notification message in default block and propage it.

Parameters

• title – Title of the message

• text – Additional text of the message

• m_type – Type of the notification, see NotificationType for options

• scope – Identification into which notifiers to propagate the message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, NotificationType
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "title"))
>>> nm.custom("Custom", "message text", NotificationType.INFO).add_sub_msg("Sub message")
"Custom - message text
    - Sub message"

successful(msg: MSG_TYPE, scope: str = '') → Notification

Method creates ‘successful’ (green) notification message in default block.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to propagate the message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Item
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "title"))
>>> nm.successful(Item("faktúra", "310-231234"))
"Úspěšně zpracováno - Faktúra '310-231234'"

unable_to_process(msg: MSG_TYPE, scope: str = '') → Notification

Method creates ‘unable to process’ (blue) notification message in default block.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to propagate the message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Item
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "title"))
>>> nm.unable_to_process(
...     Item("e-mail", "Invoice no.331343")
... ).add_sub_msg("Neznámi formát e-mailu")
"Nelze zpracovat - E-mail 'Invoice no.331343'
    - Neznámi formát e-mailu"

warning(msg: MSG_TYPE, scope: str = '') → Notification

Method creates ‘warning’ (yellow) notification message in default block.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to propagate the message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "title"))
>>> nm.warning(
...     "Byl spracovany maximálni počet položek"
... ).add_sub_msg("spracovano 20/20")
"Upozornení - Byl spracovany maximálni počet položek
    - spracovano 20/20"

error(msg: MSG_TYPE, scope: str = '') → Notification

Method creates ‘error’ (red) notification message in default block.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to propagate the message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Item
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "title"))
>>> nm.error(
...     Item("Objednávka", "RE-102-3539").text("neobsahuje požadované položky")
... ).add_sub_msg("položka DP-34101")
"Chyba - Objednávka 'RE-102-3539' neobsahuje požadované položky
    - položka DP-34101"

trigger_event(event: aiviro.modules.notifier.event.BaseEvent) → None

Sends an event to all notifiers which the event targets. Notifiers can be set up to handle specific events. For example EmailNotifier only handles SendReportEvent.

Parameters

event – Event which is sent to all notifiers specified in the event.

send_report(recipients: Optional[ADDR_TYPE] = None, logging_info: bool = True, prefect_artifact: bool = True, email_subject: Optional[str] = None, email_attachments: Optional[List[str]] = None, scope: str = '', propagate: bool = True) → None

Triggers send report in all notifiers which are inside the scope parameter.

Parameters

• recipients – (Deprecated) E-mail recipients of the html report

• logging_info – If True, plain-text report is logged in INFO level

• prefect_artifact – If True, Prefect artifact with markdown report is created

• email_subject – Subject of them e-mail, if None report_title is used as subject

• email_attachments – List of paths to attach to the email

• scope – Scope of notifiers in which this method should be executed

• propagate – If the send report should be propagated to all scopes or the exact one

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Item
>>> # Sending with one notifier
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "title"))
>>> nm.send_report()
>>> # Sending with multiple notifiers
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "base"))
>>> nm.add_notifier(EmailNotifier("<client>", "dev"), "dev")
>>> nm.send_report()  # sends report to both notifiers
>>> nm.send_report(propagate=False)  # sends report only to the notifiers with "base" title
>>> nm.send_report(scope="dev")  # sends report to the notifier with "dev" title

Email Notifier

class aiviro.modules.notifier.EmailNotifier(client: EmailClient, report_title: str, recipients: ADDR_TYPE)

Email notifier which provides an interface to create standardized reports for Aiviro scripts. It creates report in html, markdown and plain-text format.

Parameters

• client – EmailClient object with configured SMTP server credentials

• report_title – Title of the report

• recipients – E-mail recipients of the report

Example

>>> from aiviro.modules.email import EmailClient
>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Msg, Item, Style
>>>
>>> client = EmailClient()
>>> client.setup_smtp_basic_auth("<SMTP_SERVER>", "<EMAIL_ADDRESS>", "<EMAIL_PASSWORD>")
>>> # initialize notifier & manager
>>> nm = NotifierManager().add_notifier(EmailNotifier(
...     client, "Spracovaní Faktúr", ["email@domain.com", "email2@domain.com"]
... ))
>>> # set-up default block style
>>> nm.root_notifier.default_block.item_style = Style(bold=True)
>>> nm.successful(Item("Faktura", "Milburg 21893918.pdf"))
>>> nm.successful(Item("Objednavka", "300220178"))
>>> nm.unable_to_process(
...     Item("e-mail", "SecureNetwork.cz: Potvrzení o přijetí platby")
... ).add_sub_msg("Neobsahuje přilohu")
>>> nm.unable_to_process(
...     Item("e-mail", "faktura FV-11/2022")
... ).add_sub_msg("Obsahuje neznámu přílohu")
>>> nm.warning(
...     Item("položka", "107236").item("Faktura", "R22E09315").item("Objednávka", "301210221")
... ).add_sub_msg(Msg("nebyla nalezena v 'Převod s výběrem a potvrdzením'"))
>>> nm.error("Extrakce emailu")
>>> nm.error(Item("faktura", "Emmen 503031100.PDF").item("parser", "EmmennParser"))
...
>>> blk = nm.create_block("Druhy Blok")
>>> blk.item_style = Style(italic=True)
>>> blk.unable_to_process(
...     Item("E-mail", 'Melder Electronics, a.s.')
... ).add_sub_msg("Neobsahuje přílohu s PDF")
>>> blk.unable_to_process(
...     Item("Objednavka", "123-30XDSF03").text("jiz existuje ve 'Expedicni prikazy'")
... )
>>> blk.warning(Msg("Výber maximálního-menšího množství (20)").item("polozka", "7811248"))
>>> blk.error(
...     Item("Faktura", '123-3498129').text("nelze spracovat")
... ).add_sub_msg(Item("Firma", "Sewer s.r.o.").text("nebyla nalezena v konfiguračním souboru"))
>>> # send report
>>> nm.root_notifier.send_report(["email@domain.com", "email2@domain.com"])

Example of e-mail report.

report_html() → str

Returns html report

send_report(recipients: Optional[ADDR_TYPE] = None, logging_info: bool = True, prefect_artifact: bool = True, email_subject: Optional[str] = None, email_attachments: Optional[List[str]] = None) → None

Method generates and sends the report.

Parameters

• recipients – (Deprecated) E-mail recipients of the html report

• logging_info – If True, plain-text report is logged in INFO level

• prefect_artifact – If True, Prefect artifact with markdown report is created

• email_subject – Subject of them e-mail, if None report_title is used as subject

• email_attachments – List of paths to attach to the email

property blocks: List[aiviro.modules.notifier.notification.NotificationBlock]

Returns list of non-empty blocks. It can be used to check if report contains any messages.

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier
>>> nm = NotifierManager().add_notifier(
...     EmailNotifier("<client>", "Invoice Processing", "robot.aiviro@aiviro.com")
... )
>>> en = nm.root_notifier
>>> if en.blocks:
>>>     en.send_report(email_subject="Robot Report")

create_block(title: str, block_id: Optional[str] = None, sort_notifications: bool = False, style: Optional[Style] = None) → aiviro.modules.notifier.notification.NotificationBlock

Creates new block/section in the report.

Parameters

• title – Title of the block

• block_id – Identifier of the block, if not set ‘title’ is used as identifier

• sort_notifications – If True notification messages will be sorted in the block

• style – Style to automatically format Item messages.

property default_block: aiviro.modules.notifier.notification.NotificationBlock

Returns default NotificationBlock

get_block(block_id: str) → aiviro.modules.notifier.notification.NotificationBlock

Method to get NotificationBlock

Parameters

block_id – Identification of the notification block

property last_block: aiviro.modules.notifier.notification.NotificationBlock

Returns last created NotificationBlock

report_markdown() → str

Returns markdown report

report_plain_text() → str

Returns plain-text report

Notification Components

class aiviro.modules.notifier.Notification(title: str, message: Msg, m_type: aiviro.modules.notifier.constants.NotificationType, item_style: Optional[Style] = None)

Notification object representing one message (possibly with sub messages) for NotificationBlock.

add_sub_msg(text: MSG_TYPE) → Notification

Adds sub message into the notification

property notification_type: aiviro.modules.notifier.constants.NotificationType

Type of the notification, one of NotificationType options.

Getter

Returns notification type

Setter

Sets type of the notification

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, NotificationType, Item
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "Title", "mail@bs.com"))
>>> msg = nm.successful(Item("invoice", "600-123456"))
>>> # some code
>>> # change the successful message into error
>>> msg.notification_type = NotificationType.ERROR

class aiviro.modules.notifier.NotificationBlock(blk_id: str, title: str, sort_notifications: bool = False, style: Optional[Style] = None, notification_manager: Optional[NotifierManager] = None, default_scope: str = '')

Block/section of the section, containing corresponding notifications.

Parameters

• blk_id – Identifier of the block

• title – Title of the section

• sort_notifications – If True notification messages will be sorted

property item_style: Optional[Style]

Default style setting using which Item text is automatically formated.

Getter

Returns style object

Setter

Sets style for item texts

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, NotificationType, Item, Style
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "Title", "mail@bs.com"))
>>> blk = nm.create_block("New Block", "nb")
>>> blk.item_style = Style(bold=True)
>>> blk.successful(Item("invoice", "600-123456").item("email", "title of email"))
"Úspěšně zpracováno - **Invoice** '600-123456', **Email** 'title of email'"

custom(title: str, text: MSG_TYPE, m_type: aiviro.modules.notifier.constants.NotificationType = NotificationType.INFO, scope: str = '') → aiviro.modules.notifier.notification.Notification

Method creates custom notification message.

Parameters

• title – Title of the message

• text – Additional text of the message

• m_type – Type of the notification, see NotificationType for options

• scope – Identification into which notifiers to add a message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, NotificationType
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "Title", "mail@bs.com"))
>>> blk = nm.create_block("supplier-1", "s1")
>>> blk.custom("Custom", "message text", NotificationType.INFO).add_sub_msg("Sub message")
"Custom - message text
    - Sub message"

successful(msg: MSG_TYPE, scope: str = '') → aiviro.modules.notifier.notification.Notification

Method creates ‘successful’ (green) notification message.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to add a message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Item
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "Title", "mail@bs.com"))
>>> blk = nm.create_block("supplier-1", "s1")
>>> blk.successful(Item("faktúra", "310-231234"))
"Úspěšně zpracováno - Faktúra '310-231234'"

unable_to_process(msg: MSG_TYPE, scope: str = '') → aiviro.modules.notifier.notification.Notification

Method creates ‘unable to process’ (blue) notification message.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to add a message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Item
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "Title", "mail@bs.com"))
>>> blk = nm.create_block("supplier-1", "s1")
>>> blk.unable_to_process(
...     Item("e-mail", "Invoice no.331343")
... ).add_sub_msg("Neznámi formát e-mailu")
"Nelze zpracovat - E-mail 'Invoice no.331343'
    - Neznámi formát e-mailu"

warning(msg: MSG_TYPE, scope: str = '') → aiviro.modules.notifier.notification.Notification

Method creates ‘warning’ (yellow) notification message.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to add a message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Msg
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "Title", "mail@bs.com"))
>>> blk = nm.create_block("supplier-1", "s1")
>>> blk.warning(
...     Msg("Byl spracovany maximálni počet položek")
... ).add_sub_msg("spracovano 20/20")
"Upozornení - Byl spracovany maximálni počet položek
    - spracovano 20/20"

error(msg: MSG_TYPE, scope: str = '') → aiviro.modules.notifier.notification.Notification

Method creates ‘error’ (red) notification message.

Parameters

• msg – Standardized message object

• scope – Identification into which notifiers to add a message

Returns

Notification object, to add additional messages

Example

>>> from aiviro.modules.notifier import NotifierManager, EmailNotifier, Item
>>> nm = NotifierManager().add_notifier(EmailNotifier("<client>", "Title", "mail@bs.com"))
>>> blk = nm.create_block("supplier-1", "s1")
>>> blk.error(
...     Item("Objednávka", "RE-102-3539").text("neobsahuje požadované položky")
... ).add_sub_msg("položka DP-34101")
"Chyba - Objednávka 'RE-102-3539' neobsahuje požadované položky
    - položka DP-34101"

class aiviro.modules.notifier.NotificationType(value)

Default types for notification messages.

SUCCESS = 10

Green colored message

INFO = 20

Blue colored message

WARNING = 30

Yellow colored message

ERROR = 40

Red colored message

class aiviro.modules.notifier.Msg(text: str = '', style: Optional[aiviro.modules.notifier.message.Style] = None)

Main object to create a standardized message for e-mail notifications, see EmailNotifier.

Parameters

• text – Initial text of the message

• style – Style to format text

Example

>>> from aiviro.modules.notifier import Msg
>>> m = Msg("Text at the beginning")
>>> m.message
"Text at the beginning"

>>> m = Msg("")
...     .item("Item", 'DP123-1').text("unable to process")
...     .item("Invoice", "300220178").text("has invalid format")
>>> m.message
"Item 'DP123-1' unable to process, Invoice '300220178' has invalid format"

item(name: str, value: str, style: Optional[aiviro.modules.notifier.message.Style] = None) → aiviro.modules.notifier.message.Msg

Method to add custom item with its value.

Parameters

• name – Name of the item, text is capitalized

• value – String value of the item, text is formatted between two ‘

• style – Style to format ‘name’ text, ‘value’ is not formatted

Example

>>> m = Msg("Some text").item('invoice', '310-12345').item('file', 'R234_12345.pdf')
>>> m.message
"Some text, Invoice '310-12345', File 'R234_12345.pdf'"

>>> m = Msg("Some text").item("Item", 'DP123-1', Style(bold=True))
>>> m.message
"Some text, **Item** 'DP123-1'"

text(text: str, style: Optional[aiviro.modules.notifier.message.Style] = None) → aiviro.modules.notifier.message.Msg

Method to add additional text to the message.

Parameters

• text – Text added to the final message, “space” is added in front of it

• style – Style to format text

Example

>>> m = Msg("Some text").text("additional text")
>>> m.message
"Some text addtitional text"

>>> m = Msg("Bold text", Style(bold=True))
>>> m.message
"**Bold text**"

class aiviro.modules.notifier.Item(name: str, value: str, style: Optional[aiviro.modules.notifier.message.Style] = None)

Object to create a standardized message for e-mail notifications, see EmailNotifier. Can be used instead of Msg, when initial text is not required.

Parameters

• name – Name of the item, text is capitalized

• value – String value of the item, text is formatted between two ‘

Example

>>> from aiviro.modules.notifier import Item
>>> m = Item("Item", "DP123-1")
>>> m.message
"Item 'DP123-1'"

>>> m = Item("Item", 'DP123-1').text("unable to process")
...     .item("Invoice", "300220178").text("has invalid format")
>>> m.message
"Item 'DP123-1' unable to process, Invoice '300220178' has invalid format"

>>> m = Item("Item", 'DP123-1', Style(bold=True)).text("unable to process")
>>> m.message
"**Item** 'DP123-1' unable to process"

class aiviro.modules.notifier.Style(bold: bool = False, italic: bool = False)