Friendship ended with tuples, now named tuple is my new best friend

Author: gregsvo

README.md

@@ -132,12 +132,12 @@ await client.outbound.send_batch([email1, email2, email3])
 
 ```python
 # Paginated list
-messages, total = await client.outbound.list(
+page = await client.outbound.list(
     count=50,
     recipient="user@example.com",
     tag="onboarding",
 )
-print(f"Found {total} messages")
+print(f"Found {page.total} messages, got {len(page.items)} this page")
 
 # Auto-paginating stream
 async for message in client.outbound.stream(max_messages=5000, tag="onboarding"):
@@ -155,28 +155,29 @@ print(dump.body)
 
 ```python
 # List open events across all messages
-opens, total = await client.outbound.list_opens(count=50, tag="onboarding")
+page = await client.outbound.list_opens(count=50, tag="onboarding")
+print(f"{page.total} total opens, {len(page.items)} returned")
 
 # List open events for a specific message
-opens, total = await client.outbound.list_message_opens(message_id)
+page = await client.outbound.list_message_opens(message_id)
 
 # List click events across all messages
-clicks, total = await client.outbound.list_clicks(count=50, tag="onboarding")
+page = await client.outbound.list_clicks(count=50, tag="onboarding")
 
 # List click events for a specific message
-clicks, total = await client.outbound.list_message_clicks(message_id)
+page = await client.outbound.list_message_clicks(message_id)
 ```
 
 ### Inbound Messages
 
 ```python
 # List inbound messages (with optional filters)
-messages, total = await client.inbound.list(
+page = await client.inbound.list(
     count=50,
     status="processed",
     tag="support",
 )
-print(f"Found {total} inbound messages")
+print(f"Found {page.total} inbound messages")
 
 # Get full details for a single inbound message
 details = await client.inbound.get(message_id)
@@ -198,7 +199,7 @@ stats = await client.bounces.get_delivery_stats()
 print(f"Inactive addresses: {stats.inactive_mails}")
 
 # List bounces
-bounces, total = await client.bounces.list(
+page = await client.bounces.list(
     type=BounceType.HARD_BOUNCE,
     count=50,
 )
@@ -220,7 +221,7 @@ result = await client.bounces.activate(bounce_id)
 from postmark.models.templates import TemplateTypeFilter
 
 # List templates
-templates, total = await client.templates.list()
+page = await client.templates.list()
 
 # Get / create / edit / delete
 template = await client.templates.get(template_id)
@@ -243,6 +244,36 @@ await client.outbound.send_batch_with_template([
 ])
 ```
 
+### Message Streams
+
+```python
+from postmark.models.streams import MessageStreamType
+
+# List all streams
+page = await client.streams.list()
+print(f"{page.total} streams")
+
+# Filter by type
+page = await client.streams.list(message_stream_type=MessageStreamType.TRANSACTIONAL)
+
+# Get a specific stream
+stream = await client.streams.get("outbound")
+
+# Create a stream
+stream = await client.streams.create(
+    id="my-broadcasts",
+    name="My Broadcasts",
+    message_stream_type=MessageStreamType.BROADCASTS,
+)
+
+# Edit a stream
+stream = await client.streams.edit("my-broadcasts", name="Renamed Stream")
+
+# Archive / unarchive
+await client.streams.archive("my-broadcasts")
+await client.streams.unarchive("my-broadcasts")
+```
+
 ### Server Settings (server token)
 
 Read and update the settings of the server associated with your server token:
@@ -270,7 +301,7 @@ Create, list, and manage all servers on your account:
 from postmark.models.servers import DeliveryType, ServerColor
 
 # List all servers
-servers, total = await account.server.list()
+page = await account.server.list()
 
 # Get a specific server
 server = await account.server.get(server_id)

postmark/__init__.py

@@ -14,6 +14,7 @@
 )
 from .models import messages
 from .models.messages import Attachment, Email, Header, Message, SendResponse
+from .models.page import Page
 from .utils import server_utils
 
 # Base logger
@@ -38,4 +39,5 @@
     "ServerException",
     "TimeoutException",
     "server_utils",
+    "Page",
 ]

postmark/models/bounces/manager.py

@@ -1,7 +1,8 @@
 import logging
 from datetime import datetime
-from typing import AsyncGenerator, List, Optional, Tuple
+from typing import AsyncGenerator, Optional
 
+from postmark.models.page import Page
 from postmark.utils.types import HTTPClient
 
 from .enums import BounceType
@@ -39,7 +40,7 @@ async def list(
         from_date: Optional[datetime] = None,
         to_date: Optional[datetime] = None,
         message_stream: Optional[str] = None,
-    ) -> Tuple[List[Bounce], int]:
+    ) -> Page[Bounce]:
         """
         List bounces for the server.
 
@@ -55,9 +56,6 @@ async def list(
             from_date: Return bounces on or after this date (Eastern Time).
             to_date: Return bounces on or before this date (Eastern Time).
             message_stream: Filter by message stream ID.
-
-        Returns:
-            A ``(bounces, total_count)`` tuple.
         """
         if count > 500:
             raise ValueError("count cannot exceed 500")
@@ -85,7 +83,7 @@ async def list(
 
         response = await self.client.get("/bounces", params=params)
         data = BouncesListResponse(**response.json())
-        return data.bounces, data.total_count
+        return Page(items=data.bounces, total=data.total_count)
 
     async def stream(
         self,
@@ -116,20 +114,18 @@ async def stream(
                 if current_limit <= 0:
                     break
 
-            bounces, total = await self.list(
-                count=current_limit, offset=offset, **filters
-            )
-            if not bounces:
+            page = await self.list(count=current_limit, offset=offset, **filters)
+            if not page.items:
                 break
 
-            for bounce in bounces:
+            for bounce in page.items:
                 yield bounce
                 yielded += 1
                 if yielded >= max_bounces:
                     return
 
-            offset += len(bounces)
-            if offset >= total:
+            offset += len(page.items)
+            if offset >= page.total:
                 break
 
     async def get(self, bounce_id: int) -> Bounce:

postmark/models/inbound/manager.py

@@ -1,5 +1,6 @@
-from typing import Any, Dict, List, Tuple
+from typing import Any, Dict
 
+from postmark.models.page import Page
 from postmark.utils.types import HTTPClient
 
 from .schemas import InboundActionResponse, InboundMessage, InboundMessageDetails
@@ -14,7 +15,7 @@ async def list(
         count: int = 100,
         offset: int = 0,
         **filters,
-    ) -> Tuple[List[InboundMessage], int]:
+    ) -> Page[InboundMessage]:
         """
         List inbound messages.
 
@@ -23,9 +24,6 @@ async def list(
             offset: Number of records to skip.
             **filters: recipient, fromemail, tag, subject, mailboxhash, status,
                 todate, fromdate.
-
-        Returns:
-            A ``(messages, total_count)`` tuple.
         """
         if count > 500:
             raise ValueError("Count cannot exceed 500 per request")
@@ -39,9 +37,9 @@ async def list(
 
         response = await self.client.get("/messages/inbound", params=params)
         data = response.json()
-        return (
-            [InboundMessage(**m) for m in data.get("InboundMessages", [])],
-            data.get("TotalCount", 0),
+        return Page(
+            items=[InboundMessage(**m) for m in data.get("InboundMessages", [])],
+            total=data.get("TotalCount", 0),
         )
 
     async def get(self, message_id: str) -> InboundMessageDetails:

postmark/models/messages/manager.py

@@ -5,6 +5,7 @@
 from pydantic import ValidationError
 
 from postmark.exceptions import InvalidEmailException
+from postmark.models.page import Page
 from postmark.models.templates.schemas import TemplateEmail
 from postmark.utils.types import HTTPClient
 
@@ -197,7 +198,7 @@ async def list(
         offset: int = 0,
         metadata: Optional[Dict[str, str]] = None,
         **filters,
-    ) -> tuple[List[Message], int]:
+    ) -> Page[Message]:
         """List sent messages."""
         if count > 500:
             raise ValueError("Count cannot exceed 500 messages per request")
@@ -222,8 +223,9 @@ async def list(
         response.raise_for_status()
         data = response.json()
 
-        return [Message(**msg) for msg in data.get("Messages", [])], data.get(
-            "TotalCount", 0
+        return Page(
+            items=[Message(**msg) for msg in data.get("Messages", [])],
+            total=data.get("TotalCount", 0),
         )
 
     async def stream(
@@ -246,20 +248,18 @@ async def stream(
                 if current_limit <= 0:
                     break
 
-            messages, total = await self.list(
-                count=current_limit, offset=offset, **filters
-            )
-            if not messages:
+            page = await self.list(count=current_limit, offset=offset, **filters)
+            if not page.items:
                 break
 
-            for msg in messages:
+            for msg in page.items:
                 yield msg
                 yielded += 1
                 if yielded >= max_messages:
                     return
 
-            offset += len(messages)
-            if offset >= total:
+            offset += len(page.items)
+            if offset >= page.total:
                 break
 
     async def get(self, message_id: str) -> MessageDetails:
@@ -278,7 +278,7 @@ async def get_dump(self, message_id: str) -> OutboundMessageDump:
 
     async def list_opens(
         self, count: int = 100, offset: int = 0, **filters
-    ) -> tuple[List[OpenEvent], int]:
+    ) -> Page[OpenEvent]:
         """
         List open tracking events across all messages.
 
@@ -304,13 +304,14 @@ async def list_opens(
 
         response = await self.client.get("/messages/outbound/opens", params=params)
         data = response.json()
-        return [OpenEvent(**o) for o in data.get("Opens", [])], data.get(
-            "TotalCount", 0
+        return Page(
+            items=[OpenEvent(**o) for o in data.get("Opens", [])],
+            total=data.get("TotalCount", 0),
         )
 
     async def list_message_opens(
         self, message_id: str, count: int = 100, offset: int = 0
-    ) -> tuple[List[OpenEvent], int]:
+    ) -> Page[OpenEvent]:
         """
         List open tracking events for a specific message.
 
@@ -327,8 +328,9 @@ async def list_message_opens(
             f"/messages/outbound/opens/{message_id}", params=params
         )
         data = response.json()
-        return [OpenEvent(**o) for o in data.get("Opens", [])], data.get(
-            "TotalCount", 0
+        return Page(
+            items=[OpenEvent(**o) for o in data.get("Opens", [])],
+            total=data.get("TotalCount", 0),
         )
 
     # -------------------------------------------------------------------------
@@ -337,7 +339,7 @@ async def list_message_opens(
 
     async def list_clicks(
         self, count: int = 100, offset: int = 0, **filters
-    ) -> tuple[List[ClickEvent], int]:
+    ) -> Page[ClickEvent]:
         """
         List click tracking events across all messages.
 
@@ -363,13 +365,14 @@ async def list_clicks(
 
         response = await self.client.get("/messages/outbound/clicks", params=params)
         data = response.json()
-        return [ClickEvent(**c) for c in data.get("Clicks", [])], data.get(
-            "TotalCount", 0
+        return Page(
+            items=[ClickEvent(**c) for c in data.get("Clicks", [])],
+            total=data.get("TotalCount", 0),
         )
 
     async def list_message_clicks(
         self, message_id: str, count: int = 100, offset: int = 0
-    ) -> tuple[List[ClickEvent], int]:
+    ) -> Page[ClickEvent]:
         """
         List click tracking events for a specific message.
 
@@ -386,6 +389,7 @@ async def list_message_clicks(
             f"/messages/outbound/clicks/{message_id}", params=params
         )
         data = response.json()
-        return [ClickEvent(**c) for c in data.get("Clicks", [])], data.get(
-            "TotalCount", 0
+        return Page(
+            items=[ClickEvent(**c) for c in data.get("Clicks", [])],
+            total=data.get("TotalCount", 0),
         )

postmark/models/page.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from typing import Generic, List, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """
+    A single page of results from a paginated list endpoint.
+
+    Attributes:
+        items: The list of results for this page.
+        total: The total number of records matching the query (across all pages).
+    """
+
+    items: List[T]
+    total: int