databutton 0.31.0__py3-none-any.whl → 0.31.2__py3-none-any.whl

databutton/notify/__init__.py

@@ -1,3 +1,19 @@
-from .email import email
+from .email import (
+    attachment_from_bytes,
+    attachment_from_dataframe_as_csv,
+    attachment_from_dataframe_as_excel,
+    attachment_from_file,
+    attachment_from_pil_image_as_jpeg,
+    attachment_from_str,
+    email,
+)
 
-__all__ = ["email", "create_attachment"]
+__all__ = [
+    "email",
+    "attachment_from_bytes",
+    "attachment_from_str",
+    "attachment_from_file",
+    "attachment_from_pil_image_as_jpeg",
+    "attachment_from_dataframe_as_csv",
+    "attachment_from_dataframe_as_excel",
+]

databutton/notify/email.py

@@ -1,9 +1,11 @@
 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
@@ -37,17 +39,17 @@ def validate_email_to_arg(to: Union[str, List[str]]) -> List[str]:
 class Attachment(BaseModel):
     """An attachment to be included with an email."""
 
-    # Filename
-    name: Optional[str] = None
+    # Attachment file name
+    file_name: Optional[str] = None
 
     # MIME type of the attachment
-    type: Optional[str] = None
+    content_type: Optional[str] = None
 
-    # ID to use for inline attachments
-    cid: Optional[str] = None
+    # Content ID (CID) to use for inline attachments
+    content_id: Optional[str] = None
 
     # Base64 encoded data
-    base64_content: str
+    content_base64: str
 
 
 # This is the type expected in the api
@@ -76,39 +78,149 @@ def encode_content(content: bytes | str) -> str:
     return base64.b64encode(content).decode()
 
 
-def create_attachment(
+def attachment_from_bytes(
+    content: bytes,
     *,
-    content: bytes | str,
-    name: Optional[str] = None,
-    type: Optional[str] = None,
+    file_name: Optional[str] = None,
+    content_type: Optional[str] = None,
     cid: Optional[str] = None,
 ) -> Attachment:
-    """Create an attachment to be included with an email.
+    """Create attachment with content as raw bytes.
 
-    Content can either be a string or a bytes object.
-    We will base64 encode it for you.
+    You can optionally provide a file name and/or content type.
 
-    The content type can be omitted if the name has a normal file extension.
+    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(
-        name=name,
-        type=determine_type(type, name),
-        base64_content=encode_content(content),
+        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.type
-    assert att.name
-    assert att.base64_content
-    assert isinstance(att.base64_content, str)
-    assert re.match(r"^[A-Za-z0-9+/=]+$", att.base64_content)
+    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
 
 
@@ -126,7 +238,7 @@ def create_email(
     size = (
         len(content_html or "")
         + len(content_text or "")
-        + sum([len(att.base64_content) for att in attachments])
+        + sum([len(att.content_base64) for att in attachments])
     )
     max = 30 * 1024**2  # 30 MB
     headroom = 100 * 1024  # leave some room for headers etc

databutton/version.py

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

{databutton-0.31.0.dist-info → databutton-0.31.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: databutton
-Version: 0.31.0
+Version: 0.31.2
 Summary: The CLI for databutton.com
 License: Databutton
 Author: Databutton

{databutton-0.31.0.dist-info → databutton-0.31.2.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=QO5y-Y-2y6thE84M7S1k1XVDQ1kaln1sHwLkyrAXDsQ,67
-databutton/notify/email.py,sha256=hROf3IEZZWl9cJwJefsXSghYGXJ5jyogAv9d_Vw643Y,4762
+databutton/notify/__init__.py,sha256=ZikgBdlUgRz7L3CWcvWzrfHMBRjgiUiDyeDo7ZXfGQ4,464
+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=Wpp7aD59eRPATKtGt4Ko7GFEKsW7zAMWDJegHbbW2pI,175
-databutton-0.31.0.dist-info/LICENSE,sha256=c7h4pcVZapFEmqWoRTRv_S1P_aibrtDobqmlR-QtMUk,45
-databutton-0.31.0.dist-info/METADATA,sha256=Cu0vHHn-S-4-pSQzqLG4JXfiHQrC5kIjnN3mTYcbLAQ,2763
-databutton-0.31.0.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-databutton-0.31.0.dist-info/RECORD,,
+databutton/version.py,sha256=c53j10a-SMk1YW86F6GuvXrvDE8ry1i-Mm2li2yzteY,175
+databutton-0.31.2.dist-info/LICENSE,sha256=c7h4pcVZapFEmqWoRTRv_S1P_aibrtDobqmlR-QtMUk,45
+databutton-0.31.2.dist-info/METADATA,sha256=93n7qoZEXm_oq1uFraQaXStg5C31wnG65t-KYCTLSlE,2763
+databutton-0.31.2.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
+databutton-0.31.2.dist-info/RECORD,,