Messaging
---------

The *messaging* module of the allegroUtils helps you to communicate with the
users of the Allegro computers.

Message Templates
^^^^^^^^^^^^^^^^^^

There are a few pre-defined messages in :py:func:`~allegroUtils.messaging.message_templates`,
which can be retrieved by setting the keyword ``kind``. These messages are...

* ... a welcome message for visitors (``kind='visitor_welcome'``)
* ... a goodbye message for visitors (``kind='visitor_goodbye'``)
* ... an info message for users that are linked to a new project (``kind='link_user'``)
* ... an info message for users about maintenance (``kind='maintenance'``)

By running this piece of code, you can get the message for maintenance ::

    >>> from allegroUtils import messaging
    >>> msg = messaging.message_templates(kind='maintenance')
    >>> print(msg)
    Dear Allegro user,

    Allegro computers are due for a reboot due to maintenance. See the list below for more detailed information concerning the reboot:

    who?  <COMPUTERS>
    when? <TIME>
    why?  <REASON>

    If you have any objection, please let us know as soon as possible.

    You will be informed once the computer(s) are up and running again.

    If you have any further questions, please do not hesitate to contact us.

    Kind regards,
    ALMA Local Expertise Group (Allegro)

    ---
    You receive this message because you have a working directory on the Allegro computing system in /lustre/allegro/home or /lustre/allegro.

As you see, these message templates contain certain keywords, which can be replaced by
providing the ``info`` dictionary (please note, that all necessary keywords have
to be provided)::

    >>> info = {'COMPUTERS': 'chaxa', 'TIME': 'now', 'REASON': 'hardware upgrade'}
    >>> msg = messaging.message_templates(kind='maintenance', info=info)
    >>> print(msg)
    Dear Allegro user,

    Allegro computers are due for a reboot due to maintenance. See the list below for more detailed information concerning the reboot:

    who?  chaxa
    when? now
    why?  hardware upgrade

    If you have any objection, please let us know as soon as possible.

    You will be informed once the computer(s) are up and running again.

    If you have any further questions, please do not hesitate to contact us.

    Kind regards,
    ALMA Local Expertise Group (Allegro)

    ---
    You receive this message because you have a working directory on the Allegro computing system in /lustre/allegro/home or /lustre/allegro.


Sending Emails
^^^^^^^^^^^^^^

You can then send this message by using the function :py:func:`~allegroUtils.messaging.email`. This
function uses the command line tool ``mail``. ::

   >>> messaging.email(to='alma@strw.leidenuniv.nl', cc=['michiel@strw.leidenuniv.nl', 'rtilanus@strw.leidenuniv.nl'], subject='Maintenance', message=msg)

.. note:: For sending messages to many users it is good practice to send the message
          to ``alma@strw.leidenuniv.nl`` and have all users as ``bcc``