databutton 0.30.1__py3-none-any.whl → 0.31.1__py3-none-any.whl

databutton/notify/__init__.py

@@ -1,3 +1,8 @@
 from .email import email
 
-__all__ = ["email"]
+__all__ = [
+    "email",
+    "attachment_from_bytes",
+    "attachment_from_str",
+    "attachment_from_file",
+]

databutton/notify/email.py

@@ -1,17 +1,16 @@
+import base64
+import io
+import mimetypes
+import re
+from collections.abc import Sequence
 from typing import List, Optional, Union
 
+import pandas as pd
 from pydantic import BaseModel
 
 from .send import send
 
 
-class Email(BaseModel):
-    to: Union[str, List[str]]
-    subject: str
-    content_text: Optional[str]
-    content_html: Optional[str]
-
-
 def valid_email(recipient: str) -> bool:
     # Note: We could possibly use some email validation library but it's tricky
     parts = recipient.split("@")
@@ -36,11 +35,234 @@ def validate_email_to_arg(to: Union[str, List[str]]) -> List[str]:
     return to
 
 
+# This is the type expected in the api
+class Attachment(BaseModel):
+    """An attachment to be included with an email."""
+
+    # Attachment file name
+    file_name: Optional[str] = None
+
+    # MIME type of the attachment
+    content_type: Optional[str] = None
+
+    # Content ID (CID) to use for inline attachments
+    content_id: Optional[str] = None
+
+    # Base64 encoded data
+    content_base64: str
+
+
+# This is the type expected in the api
+class Email(BaseModel):
+    to: Union[str, List[str]]
+    subject: str
+    content_text: Optional[str] = None
+    content_html: Optional[str] = None
+    attachments: list[Attachment] = []
+
+
+def determine_type(type: Optional[str], name: Optional[str]) -> Optional[str]:
+    if type:
+        return type
+    if name:
+        type, encoding = mimetypes.guess_type(name)
+        # if encoding is not None:
+        #     return "; ".join([type, encoding])
+        return type
+    return None
+
+
+def encode_content(content: bytes | str) -> str:
+    if isinstance(content, str):
+        content = content.encode()
+    return base64.b64encode(content).decode()
+
+
+def attachment_from_bytes(
+    content: bytes,
+    *,
+    file_name: Optional[str] = None,
+    content_type: Optional[str] = None,
+    cid: Optional[str] = None,
+) -> Attachment:
+    """Create attachment with content as raw bytes.
+
+    You can optionally provide a file name and/or content type.
+
+    If missing we will try to guess the content type from the file name.
+
+    To use an attachment as an inline image in the email,
+    set the `cid="my_image_id"` parameter,
+    and use `<img src="cid:my_image_id">` in the html content.
+    """
+    return Attachment(
+        file_name=file_name,
+        content_type=determine_type(content_type, file_name),
+        content_base64=encode_content(content),
+        content_id=cid,
+    )
+
+
+def attachment_from_str(
+    content: str,
+    *,
+    file_name: Optional[str] = None,
+    content_type: Optional[str] = None,
+    cid: Optional[str] = None,
+) -> Attachment:
+    """Create attachment with content as raw str."""
+    return attachment_from_bytes(
+        content.encode(),
+        file_name=file_name,
+        content_type=content_type,
+        cid=cid,
+    )
+
+
+def attachment_from_file(
+    fp: Optional[io.IOBase] = None,
+    *,
+    file_name: Optional[str] = None,
+    content_type: Optional[str] = None,
+    cid: Optional[str] = None,
+) -> Attachment:
+    """Create attachment with content from a file.
+
+    fp can be anything with a .read() method returning bytes or str,
+    or omitted to read file_name from file system.
+    """
+    if fp is None:
+        if file_name is None:
+            raise ValueError("Either `fp` or `file_name` must be provided.")
+        with open(file_name, "rb") as fp:
+            buf = fp.read()
+    else:
+        buf = fp.read()
+        if isinstance(buf, str):
+            buf = buf.encode()
+    return attachment_from_bytes(
+        buf,
+        file_name=file_name,
+        content_type=content_type,
+        cid=cid,
+    )
+
+
+def attachment_from_pil_image_as_jpeg(
+    image,  # PIL image
+    *,
+    image_format: str = "JPEG",
+    file_name: Optional[str] = None,
+    content_type: Optional[str] = None,
+    cid: Optional[str] = None,
+) -> Attachment:
+    """Create image attachment with content from a PIL compatible image (such as pillow).
+
+    This convenience function calls image.save(buffer, format=image_format),
+    to further customize image formats etc take a peek at the implementation
+    here and use attachment_from_bytes directly instead.
+
+    You can optionally provide a file name and/or content type.
+
+    If missing we will try to guess the content type from the file name.
+
+    To use an attachment as an inline image in the email,
+    set the `cid="my_image_id"` parameter,
+    and use `<img src="cid:my_image_id">` in the html content.
+    """
+    buf = io.BytesIO()
+    image.save(buf, format=image_format)
+    return attachment_from_bytes(
+        buf.getvalue(),
+        file_name=file_name,
+        content_type=content_type,
+        cid=cid,
+    )
+
+
+def attachment_from_dataframe_as_csv(
+    df: pd.DataFrame,
+    *,
+    file_name: Optional[str] = None,
+) -> Attachment:
+    """Create CSV attachment with content from a pandas dataframe."""
+    return attachment_from_str(
+        df.to_csv(),
+        file_name=file_name,
+        content_type="text/csv",
+    )
+
+
+MIME_TYPE_XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+
+def attachment_from_dataframe_as_excel(
+    df: pd.DataFrame,
+    *,
+    file_name: Optional[str] = None,
+) -> Attachment:
+    """Create Excel (.xlsx) attachment with content from a pandas dataframe.
+
+    Requires the openpyxl package to be installed.
+    """
+    buf = io.BytesIO()
+    df.to_excel(buf)
+    return attachment_from_bytes(
+        buf.getvalue(),
+        file_name=file_name,
+        content_type=MIME_TYPE_XLSX,
+    )
+
+
+def validate_attachment(att: Attachment) -> Attachment:
+    assert isinstance(att, Attachment)
+    assert att.content_type
+    assert att.file_name
+    assert att.content_base64
+    assert isinstance(att.content_base64, str)
+    assert re.match(r"^[A-Za-z0-9+/=]+$", att.content_base64)
+    return att
+
+
+def create_email(
+    *,
+    to: Union[str, List[str]],
+    subject: str,
+    content_text: Optional[str] = None,
+    content_html: Optional[str] = None,
+    attachments: Sequence[Attachment] = (),
+) -> Email:
+    attachments = [validate_attachment(att) for att in attachments]
+
+    # Sendgrid has a 30 MB limit on everything, this estimate should be slightly stricter
+    size = (
+        len(content_html or "")
+        + len(content_text or "")
+        + sum([len(att.content_base64) for att in attachments])
+    )
+    max = 30 * 1024**2  # 30 MB
+    headroom = 100 * 1024  # leave some room for headers etc
+    if size > max - headroom:
+        raise ValueError(
+            "Email and attachment size exceeds 30MB, please reduce the size of the email."
+        )
+
+    return Email(
+        to=validate_email_to_arg(to),
+        subject=subject,
+        content_text=content_text,
+        content_html=content_html,
+        attachments=attachments,
+    )
+
+
 def email(
     to: Union[str, List[str]],
     subject: str,
+    *,
     content_text: Optional[str] = None,
     content_html: Optional[str] = None,
+    attachments: Sequence[Attachment] = (),
 ):
     """Send email notification from databutton.
 
@@ -53,10 +275,11 @@ def email(
     the result may be less pretty than handcrafted text.
     """
     send(
-        Email(
-            to=validate_email_to_arg(to),
+        create_email(
+            to=to,
             subject=subject,
             content_text=content_text,
             content_html=content_html,
+            attachments=attachments,
         )
     )

databutton/version.py

@@ -5,4 +5,4 @@ This module contains project version information.
 .. moduleauthor:: Databutton <support@databutton.com>
 """
 
-__version__ = "0.30.1"
+__version__ = "0.31.1"

{databutton-0.30.1.dist-info → databutton-0.31.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: databutton
-Version: 0.30.1
+Version: 0.31.1
 Summary: The CLI for databutton.com
 License: Databutton
 Author: Databutton
@@ -13,7 +13,7 @@ Requires-Dist: PyJWT (>=2.6.0,<3.0.0)
 Requires-Dist: PyYAML (>=6.0,<7.0)
 Requires-Dist: certifi (>=2022.12.7,<2023.0.0)
 Requires-Dist: cryptography (>=40.0.1,<41.0.0)
-Requires-Dist: httpx (>=0.23.3,<0.24.0)
+Requires-Dist: httpx (>=0.24.0,<0.25.0)
 Requires-Dist: pandas (>=1.5.3,<2.0.0)
 Requires-Dist: pydantic (>=1.10.7,<2.0.0)
 Requires-Dist: streamlit (>=1.20.0,<2.0.0)

{databutton-0.30.1.dist-info → databutton-0.31.1.dist-info}/RECORD

@@ -10,16 +10,16 @@ databutton/internal/performedby.py,sha256=QZ4XtsZSbltYfmZesfqVW-v7t153_ziIbCwjWD
 databutton/internal/retries.py,sha256=OMxnreq1Icaf8OrtFPPNEZ8tCZe6HUI9fJ4FQ6Uiw-M,2011
 databutton/jobs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 databutton/jobs/run.py,sha256=Td0BSiIrYKiymDKVf8w5MT3C5uiwzeulYNJUGcxQk2k,632
-databutton/notify/__init__.py,sha256=amtxb4w8mWPvLn8QhmP_bPpb-A6ggc4M42McC34i3UQ,46
-databutton/notify/email.py,sha256=JSzSDE93_CeVecNTE8kddt06NMsh_oF-kvdbbvCwaYc,1720
+databutton/notify/__init__.py,sha256=PWuuSBzsRFd0-gc6PS2oAMl4gSMSrgLAwTX2GiOaGyE,137
+databutton/notify/email.py,sha256=jfnDWtBTw8gosfEM5Oes2jeKkAKjgL3cD1NK_Usy3Cs,7932
 databutton/notify/send.py,sha256=cj-TG0jwolEXwJJVxeBxwpfg_it03KoImUn30qAbbQE,749
 databutton/secrets/__init__.py,sha256=sI0okrfRBs2l5tcLTrKc9uUfPVVRMM9D7WED8p226tI,128
 databutton/secrets/secrets.py,sha256=pehXsD09iKTxHaNQJ6awvIHXgRXBJrf4Xhrc11ZUeOk,3427
 databutton/storage/__init__.py,sha256=7ZNd4eQQ7lYYIe1MqCuFbFF1aAVCuj2c_zmJfaPVlDY,252
 databutton/storage/storage.py,sha256=XBy6z005K0KqmiTkq9eju87PgTboV-vPN1RRXuC57KI,17240
 databutton/user.py,sha256=QWyWV_G_bnfIJ9js2itOwBk4zqXgBUF9h8lf5mygef8,503
-databutton/version.py,sha256=LnAX9fhmv8Ig0dBbEI1vhJU1SZxGz3KAF3kdaF_QIwA,175
-databutton-0.30.1.dist-info/LICENSE,sha256=c7h4pcVZapFEmqWoRTRv_S1P_aibrtDobqmlR-QtMUk,45
-databutton-0.30.1.dist-info/METADATA,sha256=HaU4bNOluGiVajTSbFOPHoHRe3m_gdMHqzNm6dTsfSM,2763
-databutton-0.30.1.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-databutton-0.30.1.dist-info/RECORD,,
+databutton/version.py,sha256=eK4hE95pRdHCVWV4DPs-Hciq-3mDMMnVk8WH6hG2IwI,175
+databutton-0.31.1.dist-info/LICENSE,sha256=c7h4pcVZapFEmqWoRTRv_S1P_aibrtDobqmlR-QtMUk,45
+databutton-0.31.1.dist-info/METADATA,sha256=rlHUOLZkCxKTne3HNFxzauvKauuE_aqQftIVFiQm-Xw,2763
+databutton-0.31.1.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
+databutton-0.31.1.dist-info/RECORD,,