send_email/send_email.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sending an email\n",
    "This notebook shows how to create an email and send it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import nuclio"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# nuclio: start-code\n",
    "%nuclio config kind = \"job\"\n",
    "%nuclio config spec.image = \"mlrun/mlrun\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mlrun.execution import MLClientCtx\n",
    "from typing import List\n",
    "\n",
    "# Import the email modules we'll need\n",
    "import smtplib\n",
    "from email.message import EmailMessage\n",
    "import os\n",
    "\n",
    "# For guessing MIME type based on file name extension\n",
    "import mimetypes\n",
    "\n",
    "def send_email(\n",
    "    context: MLClientCtx,\n",
    "    sender: str,\n",
    "    to: str,\n",
    "    subject: str,\n",
    "    content: str = \"\",\n",
    "    server_addr: str = None,\n",
    "    attachments: List[str] = []\n",
    ") -> None:\n",
    "    \"\"\"Send an email.\n",
    "    :param sender: Sender email address\n",
    "    :param context: The function context\n",
    "    :param to: Email address of mail recipient\n",
    "    :param subject: Email subject\n",
    "    :param content: Optional mail text\n",
    "    :param server_addr: Address of SMTP server to use. Use format <addr>:<port>\n",
    "    :param attachments: List of attachments to add.\n",
    "    \"\"\"\n",
    "\n",
    "    # Validate inputs\n",
    "    email_user = context.get_secret(\"SMTP_USER\")\n",
    "    email_pass = context.get_secret(\"SMTP_PASSWORD\")\n",
    "    if email_user is None or email_pass is None:\n",
    "        context.logger.error(\"Missing sender email or password - cannot send email.\")\n",
    "        return\n",
    "\n",
    "    if server_addr is None:\n",
    "        context.logger.error(\"Server not specified - cannot send email.\")\n",
    "        return\n",
    "        \n",
    "    msg = EmailMessage()\n",
    "    msg['From'] = sender\n",
    "    msg['Subject'] = subject\n",
    "    msg['To'] = to\n",
    "    msg.set_content(content)   \n",
    "\n",
    "    for filename in attachments:\n",
    "        context.logger.info(f'Looking at attachment: {filename}')\n",
    "        if not os.path.isfile(filename):\n",
    "            context.logger.warning(f'Filename does not exist {filename}')\n",
    "            continue\n",
    "        # Guess the content type based on the file's extension.  Encoding\n",
    "        # will be ignored, although we should check for simple things like\n",
    "        # gzip'd or compressed files.\n",
    "        ctype, encoding = mimetypes.guess_type(filename)\n",
    "        if ctype is None or encoding is not None:\n",
    "            # No guess could be made, or the file is encoded (compressed), so\n",
    "            # use a generic bag-of-bits type.\n",
    "            ctype = 'application/octet-stream'\n",
    "        maintype, subtype = ctype.split('/', 1)\n",
    "        with open(filename,'rb') as fp:\n",
    "            msg.add_attachment(fp.read(),\n",
    "                               maintype=maintype,\n",
    "                               subtype=subtype,\n",
    "                               filename=os.path.basename(filename))\n",
    "            context.logger.info(f'Added attachment: Filename: {filename}, of mimetype: {maintype}, {subtype}')\n",
    "    \n",
    "    try:\n",
    "        s = smtplib.SMTP(host=server_addr)\n",
    "        s.starttls()\n",
    "        s.login(email_user,email_pass)\n",
    "        s.send_message(msg)\n",
    "        context.logger.info('Email sent successfully.')\n",
    "    except smtplib.SMTPException as exp:\n",
    "        context.logger.error(f'SMTP exception caught in SMTP code: {exp}')\n",
    "    except ConnectionError as ce:\n",
    "        context.logger.error(f'Connection error caught in SMTP code: {ce}')\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# nuclio: end-code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## MLRun conf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mlrun import mlconf\n",
    "import os\n",
    "\n",
    "#artifact_path = mlconf.artifact_path or os.path.abspath('jobs')\n",
    "artifact_path = os.path.abspath('jobs')\n",
    "mlconf.dbpath = 'http://mlrun-api:8080'\n",
    "mlconf.artifact_path = artifact_path\n",
    "print(f'Artifacts path: {mlconf.artifact_path}\\nMLRun DB path: {mlconf.dbpath}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mlrun import code_to_function\n",
    "\n",
    "# create job function object from notebook code\n",
    "fn = code_to_function(\"send_email\")\n",
    "# add metadata (for templates and reuse)\n",
    "fn.spec.default_handler = \"send_email\"\n",
    "fn.spec.description = \"Send Email messages through SMTP server\"\n",
    "fn.metadata.categories = [\"notifications\"]\n",
    "fn.metadata.labels = {\"author\": \"saarc\"}\n",
    "fn.export(\"function.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Test the function\n",
    "First, configure MLRun. Define project parameters that will be used for testing the function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from os import path, getenv\n",
    "from mlrun import new_project\n",
    "\n",
    "project_name = '-'.join(filter(None, ['email-sending', getenv('V3IO_USERNAME', None)]))\n",
    "project_path = path.abspath('conf')\n",
    "project = new_project(project_name, project_path, init_git=True)\n",
    "\n",
    "print(f'Project path: {project_path}\\nProject name: {project_name}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mlrun import run_local, NewTask, import_function, mount_v3io\n",
    "\n",
    "# Target location for storing pipeline artifacts\n",
    "artifact_path = path.abspath('jobs')\n",
    "# MLRun DB path or API service URL\n",
    "mlconf.dbpath = mlconf.dbpath or 'http://mlrun-api:8080'\n",
    "\n",
    "print(f'Artifacts path: {artifact_path}\\nMLRun DB path: {mlconf.dbpath}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create some artifacts\n",
    "\n",
    "First we'll load the Iris dataset and use the describe function to generate some artifacts describing it. \n",
    ">This is only used to generate some nice artifacts so we can send them later via email. If all you want is to test the email sending functionality you can safely ignore this part (and modify the code that actually sends the email to not use attachments).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mlrun.execution import MLClientCtx\n",
    "from typing import List\n",
    "from os import path\n",
    "import pandas as pd\n",
    "\n",
    "# Ingest a data set into the platform\n",
    "def get_data(context, \n",
    "             source_url, \n",
    "             format='csv'):\n",
    "\n",
    "    iris_dataset = pd.read_csv(str(source_url))\n",
    "\n",
    "    target_path = path.join(context.artifact_path, 'data')\n",
    "    # Optionally print data to your logger\n",
    "    context.logger.info('Saving Iris data set to {} ...'.format(target_path))\n",
    "\n",
    "    # Store the data set in your artifacts database\n",
    "    context.log_dataset('iris_dataset', df=iris_dataset, format=format,\n",
    "                        index=False, artifact_path=target_path)\n",
    "    \n",
    "source_url = 'http://iguazio-sample-data.s3.amazonaws.com/iris_dataset.csv'\n",
    "\n",
    "get_data_run = run_local(name='get_data',\n",
    "                         handler=get_data,\n",
    "                         inputs={'source_url':source_url},\n",
    "                         project=project_name, artifact_path=artifact_path)\n",
    "\n",
    "project.set_function('hub://describe', 'describe')\n",
    "describe = project.func('describe').apply(mount_v3io())\n",
    "\n",
    "describe_run = describe.run(params={'label_column': 'label'},\n",
    "                            inputs={\"table\":\n",
    "                                    get_data_run.outputs['iris_dataset']},\n",
    "                            artifact_path=artifact_path)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sending the email\n",
    "\n",
    "Sending emails need to have server_addr set to confirure the SMTP address. It also needs to have secrets created with the SMTP_USER and SMTP_PASSWORD secrets set, so it can login to the server.\n",
    "\n",
    "We'll send an email with the artifacts generated by the describe function. Note that some of these artifacts are HTML and the last one is a CSV. The send_email function will attempt to auto-detect the attachments' MIME types and add them to the email with their appropriate types."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configure task parameters to be used when executing the function\n",
    "\n",
    "***Make sure to replace placeholders with actual SMTP configuration (address/email/password)***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "task_params = {\n",
    "    'sender' : '<sender email>',\n",
    "    'to': '<recipient email>',\n",
    "    'subject': 'Dataset description, sent by the send_email function',\n",
    "    'content': 'Some basic analysis of the iris dataset.',\n",
    "    'attachments': [describe_run.outputs['histograms'],\n",
    "                    describe_run.outputs['correlation'],\n",
    "                    describe_run.outputs['correlation-matrix']],\n",
    "    'server_addr': '<server address>:<port>',\n",
    "}\n",
    "\n",
    "task = NewTask(name='email_task', project=project_name, handler=send_email, artifact_path=artifact_path,\n",
    "              params=task_params)\n",
    "\n",
    "task_secrets = {'SMTP_USER':'<username>',\n",
    "                'SMTP_PASSWORD': '<password>'}\n",
    "\n",
    "task.with_secrets('inline',task_secrets)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run locally"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "send_email_run = run_local(task,name='send_email')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run remotely"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Convert the local get_data function into an email_func project function\n",
    "email_func = code_to_function(name='send_email')\n",
    "email_func.apply(mount_v3io())\n",
    "\n",
    "email_func.run(task, params=task_params,  workdir=mlconf.artifact_path)\n",
    "email_func.doc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}