sendstack 0.1.1__tar.gz → 0.1.2__tar.gz

{sendstack-0.1.1/src/sendstack.egg-info → sendstack-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendstack
-Version: 0.1.1
+Version: 0.1.2
 Summary: Sync and async Python SDK for the SendStack email SaaS API.
 Author: Noria Labs
 License-Expression: MIT
@@ -293,6 +293,45 @@ client.emails.send(
 )
 ```
 
+### Reading from files
+
+The API accepts strings (`html`/`text`) and base64 (`attachments`). These
+stdlib-only helpers do the read-and-encode step so you don't repeat it:
+
+```python
+from sendstack import (
+    Sendstack,
+    html_from_file,
+    text_from_file,
+    attachment_from_file,
+    attachment_from_bytes,
+)
+
+client.emails.send(
+    {
+        "from": "billing@example.com",
+        "to": "customer@example.com",
+        "subject": "Your invoice",
+        "html": html_from_file("templates/invoice.html"),
+        "text": text_from_file("templates/invoice.txt"),
+        "attachments": [
+            # From a path: filename defaults to the basename, content is base64-encoded.
+            attachment_from_file("invoices/2026-06.pdf", content_type="application/pdf"),
+            # From in-memory bytes (e.g. a generated PDF): filename is required.
+            attachment_from_bytes(generated_pdf, filename="summary.pdf", content_type="application/pdf"),
+        ],
+    }
+)
+```
+
+- `html_from_file(path, *, encoding="utf-8")` / `text_from_file(...)` — read a text
+  file into a string.
+- `attachment_from_file(path, *, filename=None, content_type=None, inline=None, content_id=None)`
+  — read a file into a base64 attachment `dict`. `filename` defaults to the basename.
+  `path` accepts a `str` or any `os.PathLike`.
+- `attachment_from_bytes(data, *, filename, content_type=None, inline=None, content_id=None)`
+  — encode in-memory `bytes`; `filename` is required.
+
 ## Domains
 
 ```python
@@ -510,6 +549,11 @@ Clients and errors:
 - `SendstackError`
 - `DEFAULT_BASE_URL`
 
+Filesystem helpers:
+
+- `html_from_file`, `text_from_file`
+- `attachment_from_file`, `attachment_from_bytes`
+
 Auth, options, and machinery:
 
 - `BearerAuthStrategy`, `HeadersAuthStrategy`, `SendstackAuthStrategy`

{sendstack-0.1.1 → sendstack-0.1.2}/README.md

@@ -266,6 +266,45 @@ client.emails.send(
 )
 ```
 
+### Reading from files
+
+The API accepts strings (`html`/`text`) and base64 (`attachments`). These
+stdlib-only helpers do the read-and-encode step so you don't repeat it:
+
+```python
+from sendstack import (
+    Sendstack,
+    html_from_file,
+    text_from_file,
+    attachment_from_file,
+    attachment_from_bytes,
+)
+
+client.emails.send(
+    {
+        "from": "billing@example.com",
+        "to": "customer@example.com",
+        "subject": "Your invoice",
+        "html": html_from_file("templates/invoice.html"),
+        "text": text_from_file("templates/invoice.txt"),
+        "attachments": [
+            # From a path: filename defaults to the basename, content is base64-encoded.
+            attachment_from_file("invoices/2026-06.pdf", content_type="application/pdf"),
+            # From in-memory bytes (e.g. a generated PDF): filename is required.
+            attachment_from_bytes(generated_pdf, filename="summary.pdf", content_type="application/pdf"),
+        ],
+    }
+)
+```
+
+- `html_from_file(path, *, encoding="utf-8")` / `text_from_file(...)` — read a text
+  file into a string.
+- `attachment_from_file(path, *, filename=None, content_type=None, inline=None, content_id=None)`
+  — read a file into a base64 attachment `dict`. `filename` defaults to the basename.
+  `path` accepts a `str` or any `os.PathLike`.
+- `attachment_from_bytes(data, *, filename, content_type=None, inline=None, content_id=None)`
+  — encode in-memory `bytes`; `filename` is required.
+
 ## Domains
 
 ```python
@@ -483,6 +522,11 @@ Clients and errors:
 - `SendstackError`
 - `DEFAULT_BASE_URL`
 
+Filesystem helpers:
+
+- `html_from_file`, `text_from_file`
+- `attachment_from_file`, `attachment_from_bytes`
+
 Auth, options, and machinery:
 
 - `BearerAuthStrategy`, `HeadersAuthStrategy`, `SendstackAuthStrategy`

{sendstack-0.1.1 → sendstack-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sendstack"
-version = "0.1.1"
+version = "0.1.2"
 description = "Sync and async Python SDK for the SendStack email SaaS API."
 readme = "README.md"
 requires-python = ">=3.11"

{sendstack-0.1.1 → sendstack-0.1.2}/src/sendstack/__init__.py

@@ -20,6 +20,12 @@ from .errors import (
     is_success_envelope,
     to_sendstack_error,
 )
+from .files import (
+    attachment_from_bytes,
+    attachment_from_file,
+    html_from_file,
+    text_from_file,
+)
 from .types import (
     DEFAULT_BASE_URL,
     BearerAuthStrategy,
@@ -77,6 +83,11 @@ __all__ = [
     "is_error_envelope",
     "is_success_envelope",
     "to_sendstack_error",
+    # Filesystem helpers
+    "html_from_file",
+    "text_from_file",
+    "attachment_from_file",
+    "attachment_from_bytes",
     # Auth
     "BearerAuthStrategy",
     "HeadersAuthStrategy",

sendstack-0.1.2/src/sendstack/files.py

@@ -0,0 +1,83 @@
+"""Filesystem conveniences for building email payloads from local files.
+
+The SendStack API accepts strings (``html``/``text``) and base64 (``attachments``).
+These helpers do the read-and-encode step so callers don't repeat it. They use
+only the standard library, so they add no dependencies.
+
+The returned attachment ``dict`` uses the snake_case wire field names, so it can
+be dropped straight into ``emails.send({"attachments": [...]})``.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from pathlib import Path
+from typing import Any
+
+PathLike = str | os.PathLike[str]
+
+__all__ = [
+    "html_from_file",
+    "text_from_file",
+    "attachment_from_file",
+    "attachment_from_bytes",
+]
+
+
+def html_from_file(path: PathLike, *, encoding: str = "utf-8") -> str:
+    """Read a text file (e.g. an HTML template) into a string for ``html``."""
+    return Path(path).read_text(encoding=encoding)
+
+
+def text_from_file(path: PathLike, *, encoding: str = "utf-8") -> str:
+    """Read a text file (e.g. a ``.txt`` body) into a string for ``text``."""
+    return Path(path).read_text(encoding=encoding)
+
+
+def attachment_from_file(
+    path: PathLike,
+    *,
+    filename: str | None = None,
+    content_type: str | None = None,
+    inline: bool | None = None,
+    content_id: str | None = None,
+) -> dict[str, Any]:
+    """Read a file from disk into a base64 attachment dict.
+
+    ``filename`` defaults to the file's basename. The result is ready to drop
+    into ``emails.send({"attachments": [...]})``.
+    """
+    data = Path(path).read_bytes()
+    return attachment_from_bytes(
+        data,
+        filename=filename if filename is not None else Path(os.fspath(path)).name,
+        content_type=content_type,
+        inline=inline,
+        content_id=content_id,
+    )
+
+
+def attachment_from_bytes(
+    data: bytes,
+    *,
+    filename: str,
+    content_type: str | None = None,
+    inline: bool | None = None,
+    content_id: str | None = None,
+) -> dict[str, Any]:
+    """Encode in-memory bytes (e.g. a generated PDF) into a base64 attachment dict.
+
+    ``filename`` is required since there is no path to derive one from.
+    """
+    attachment: dict[str, Any] = {
+        "filename": filename,
+        "content_base64": base64.b64encode(data).decode("ascii"),
+    }
+    if content_type is not None:
+        attachment["content_type"] = content_type
+    if inline is not None:
+        attachment["inline"] = inline
+    if content_id is not None:
+        attachment["content_id"] = content_id
+    return attachment

{sendstack-0.1.1 → sendstack-0.1.2/src/sendstack.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendstack
-Version: 0.1.1
+Version: 0.1.2
 Summary: Sync and async Python SDK for the SendStack email SaaS API.
 Author: Noria Labs
 License-Expression: MIT
@@ -293,6 +293,45 @@ client.emails.send(
 )
 ```
 
+### Reading from files
+
+The API accepts strings (`html`/`text`) and base64 (`attachments`). These
+stdlib-only helpers do the read-and-encode step so you don't repeat it:
+
+```python
+from sendstack import (
+    Sendstack,
+    html_from_file,
+    text_from_file,
+    attachment_from_file,
+    attachment_from_bytes,
+)
+
+client.emails.send(
+    {
+        "from": "billing@example.com",
+        "to": "customer@example.com",
+        "subject": "Your invoice",
+        "html": html_from_file("templates/invoice.html"),
+        "text": text_from_file("templates/invoice.txt"),
+        "attachments": [
+            # From a path: filename defaults to the basename, content is base64-encoded.
+            attachment_from_file("invoices/2026-06.pdf", content_type="application/pdf"),
+            # From in-memory bytes (e.g. a generated PDF): filename is required.
+            attachment_from_bytes(generated_pdf, filename="summary.pdf", content_type="application/pdf"),
+        ],
+    }
+)
+```
+
+- `html_from_file(path, *, encoding="utf-8")` / `text_from_file(...)` — read a text
+  file into a string.
+- `attachment_from_file(path, *, filename=None, content_type=None, inline=None, content_id=None)`
+  — read a file into a base64 attachment `dict`. `filename` defaults to the basename.
+  `path` accepts a `str` or any `os.PathLike`.
+- `attachment_from_bytes(data, *, filename, content_type=None, inline=None, content_id=None)`
+  — encode in-memory `bytes`; `filename` is required.
+
 ## Domains
 
 ```python
@@ -510,6 +549,11 @@ Clients and errors:
 - `SendstackError`
 - `DEFAULT_BASE_URL`
 
+Filesystem helpers:
+
+- `html_from_file`, `text_from_file`
+- `attachment_from_file`, `attachment_from_bytes`
+
 Auth, options, and machinery:
 
 - `BearerAuthStrategy`, `HeadersAuthStrategy`, `SendstackAuthStrategy`

{sendstack-0.1.1 → sendstack-0.1.2}/src/sendstack.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/sendstack/__init__.py
 src/sendstack/client.py
 src/sendstack/errors.py
+src/sendstack/files.py
 src/sendstack/py.typed
 src/sendstack/types.py
 src/sendstack/utils.py
@@ -14,4 +15,5 @@ src/sendstack.egg-info/requires.txt
 src/sendstack.egg-info/top_level.txt
 tests/test_conformance.py
 tests/test_distribution_identity.py
+tests/test_files.py
 tests/test_sendstack.py

sendstack-0.1.2/tests/test_files.py

@@ -0,0 +1,86 @@
+"""Tests for the filesystem convenience helpers."""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+from sendstack import (
+    attachment_from_bytes,
+    attachment_from_file,
+    html_from_file,
+    text_from_file,
+)
+
+
+def test_html_from_file_reads_utf8(tmp_path: Path) -> None:
+    path = tmp_path / "welcome.html"
+    path.write_text("<p>Hëllo</p>", encoding="utf-8")
+
+    assert html_from_file(path) == "<p>Hëllo</p>"
+
+
+def test_text_from_file_reads_utf8_and_honors_encoding(tmp_path: Path) -> None:
+    path = tmp_path / "welcome.txt"
+    path.write_text("Héllo", encoding="latin-1")
+
+    assert text_from_file(path, encoding="latin-1") == "Héllo"
+
+
+def test_attachment_from_file_defaults_filename_to_basename(tmp_path: Path) -> None:
+    path = tmp_path / "invoice.pdf"
+    payload = b"%PDF-1.4 fake"
+    path.write_bytes(payload)
+
+    assert attachment_from_file(path) == {
+        "filename": "invoice.pdf",
+        "content_base64": base64.b64encode(payload).decode("ascii"),
+    }
+
+
+def test_attachment_from_file_accepts_str_path_and_overrides(tmp_path: Path) -> None:
+    path = tmp_path / "logo.png"
+    payload = bytes([0x89, 0x50, 0x4E, 0x47])
+    path.write_bytes(payload)
+
+    # Pass the path as a str to exercise the os.fspath branch.
+    assert attachment_from_file(
+        str(path),
+        filename="brand-logo.png",
+        content_type="image/png",
+        inline=True,
+        content_id="logo",
+    ) == {
+        "filename": "brand-logo.png",
+        "content_base64": base64.b64encode(payload).decode("ascii"),
+        "content_type": "image/png",
+        "inline": True,
+        "content_id": "logo",
+    }
+
+
+def test_attachment_from_bytes_minimal() -> None:
+    data = b"generated bytes"
+
+    assert attachment_from_bytes(data, filename="report.bin") == {
+        "filename": "report.bin",
+        "content_base64": base64.b64encode(data).decode("ascii"),
+    }
+
+
+def test_attachment_from_bytes_with_all_metadata() -> None:
+    data = bytes([1, 2, 3, 4])
+
+    assert attachment_from_bytes(
+        data,
+        filename="raw.dat",
+        content_type="application/octet-stream",
+        inline=False,
+        content_id="raw",
+    ) == {
+        "filename": "raw.dat",
+        "content_base64": base64.b64encode(data).decode("ascii"),
+        "content_type": "application/octet-stream",
+        "inline": False,
+        "content_id": "raw",
+    }