broadcast-python 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

broadcast_python/client.py

@@ -16,6 +16,7 @@ from .resources.sequences import Sequences
 from .resources.subscribers import Subscribers
 from .resources.suppressions import Suppressions
 from .resources.templates import Templates
+from .resources.topics import Topics
 from .resources.transactionals import Transactionals
 from .resources.users import Users
 from .resources.webhook_endpoints import WebhookEndpoints
@@ -40,6 +41,7 @@ class Broadcast:
         self.sequences = Sequences(self)
         self.broadcasts = Broadcasts(self)
         self.segments = Segments(self)
+        self.topics = Topics(self)
         self.templates = Templates(self)
         #: The channel's brand kit (Settings -> Design). Read-only.
         self.channel_design = ChannelDesign(self)

broadcast_python/resources/migration.py

@@ -35,6 +35,7 @@ COLLECTIONS = (
     "webhook_endpoints",
     "tokens",
     "suppressions",
+    "unsubscribed_emails",
     "tags",
     "users",
     "link_redirects",
@@ -106,7 +107,7 @@ def _make_collection_method(name: str):
     return method
 
 
-# Generated rather than hand-written: 18 near-identical methods invite the kind
+# Generated rather than hand-written: 19 near-identical methods invite the kind
 # of copy-paste drift this whole SDK family exists to prevent. Declared in
 # .api-coverage.yml so the coverage report still counts them.
 for _collection in COLLECTIONS:

broadcast_python/resources/subscribers.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 from .base import BaseResource
 
@@ -46,8 +46,13 @@ class Subscribers(BaseResource):
 
         return self._post("/api/v1/subscribers.json", payload)
 
-    def update(self, email: str, **attrs: Any) -> Any:
-        return self._patch("/api/v1/subscribers.json", {"email": email, "subscriber": attrs})
+    def update(self, email: str, custom_data_mode: Optional[str] = None, **attrs: Any) -> Any:
+        """custom_data_mode: "replace" (the API default) stores custom_data as sent;
+        "merge" changes only the keys sent, and a None value deletes that key."""
+        payload: Dict[str, Any] = {"email": email, "subscriber": attrs}
+        if custom_data_mode:
+            payload["custom_data_mode"] = custom_data_mode
+        return self._patch("/api/v1/subscribers.json", payload)
 
     def add_tags(self, email: str, tags: List[str]) -> Any:
         return self._post("/api/v1/subscribers/add_tag.json", {"email": email, "tags": tags})

broadcast_python/resources/topics.py

@@ -0,0 +1,29 @@
+from typing import Any, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+
+class Topics(BaseResource):
+    """Subscriber topics: kinds of email subscribers opt in to or out of.
+
+    A topic reads a top-level custom_data key (true, false, or no value) or a
+    tag. Topics use the token's subscriber permissions.
+    """
+
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/topics.json", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/topics/{}.json".format(id), {})
+
+    def create(self, **attrs: Any) -> Any:
+        return self._post("/api/v1/topics", {"topic": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/topics/{}".format(id), {"topic": attrs})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        """Refused (422) while a broadcast or sequence uses the topic."""
+        return self._delete("/api/v1/topics/{}".format(id))

broadcast_python/version.py

@@ -1,3 +1,3 @@
 # Kept in sync with pyproject.toml by tests/test_package.py — a User-Agent that
 # lies about its version misattributes server-side client analytics.
-VERSION = "0.2.0"
+VERSION = "0.4.0"

broadcast_python/webhook.py

@@ -25,6 +25,7 @@ EMAIL_EVENTS = (
 SUBSCRIBER_EVENTS = (
     "subscriber.created",
     "subscriber.updated",
+    "subscriber.preferences_updated",
     "subscriber.deleted",
     "subscriber.subscribed",
     "subscriber.unsubscribed",

{broadcast_python-0.2.0.dist-info → broadcast_python-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: broadcast-python
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python client for the Broadcast email platform. Subscribers, sequences, broadcasts, segments, templates, autopilot, webhooks, and transactional email.
 Project-URL: Homepage, https://sendbroadcast.net
 Project-URL: Repository, https://github.com/send-broadcast/broadcast-python
@@ -246,6 +246,32 @@ client.opt_in_forms.duplicate(id, label="Copy")
 
 Reading a segment recounts its members server-side, so `segments.get` is not free.
 
+### Topics
+
+A topic is one kind of email subscribers opt in to or out of (webinars, offers).
+Its value lives in a top-level `custom_data` key (`True`, `False`, or no value)
+or in a tag. `unset_receives` decides, at send time, whether a subscriber with no
+value receives it; Broadcast never writes a default. Topics use the subscriber
+permissions.
+
+```python
+topic = client.topics.create(name="Webinars", custom_data_key="sub_webinars")
+client.topics.create(name="News", storage="tag", tag_name="news")
+client.topics.list()
+client.topics.update(topic["id"], unset_receives=False)
+client.topics.delete(topic["id"])  # 422 while a broadcast or sequence uses it
+
+# Send to a topic: (segments) AND topic
+client.broadcasts.create(subject="Webinar", body="...", segment_ids=[2], topic_id=topic["id"])
+
+# Change only the keys you send (None deletes a key); the default replaces custom_data
+client.subscribers.update("jane@example.com", custom_data={"sub_webinars": False}, custom_data_mode="merge")
+```
+
+The subscriber JSON has `topics`: each topic's stored value (`True`, `False`, or
+`None`). Topic changes fire `subscriber.preferences_updated` as well as
+`subscriber.updated`.
+
 ### Channel design (brand kit)
 
 ```python
@@ -363,6 +389,11 @@ client.migration.manifest()
 for sub in client.migration.each_record("subscribers"):
     ...   # auto-pages; advances by the limit the server actually applied
 
+# Suppressed addresses live in two lists; export both:
+# suppressions = global suppression list, unsubscribed_emails = the channel's own
+for row in client.migration.each_record("unsubscribed_emails"):
+    ...   # {"id", "email", "broadcast_channel_id", "created_at", "updated_at"}
+
 data = client.migration.download_file_asset(id)   # bytes
 ```
 
@@ -408,7 +439,7 @@ every rejection rather than distinguishing them.
 Pass the **raw** request body. Re-serialising a parsed dict changes the bytes
 and verification will fail.
 
-`broadcast_python.EVENT_TYPES` lists all 34 event names. `SUBSCRIBER_EVENTS`
+`broadcast_python.EVENT_TYPES` lists all 35 event names. `SUBSCRIBER_EVENTS`
 includes `subscribers.purged` and `subscribers.purge_failed`: a purge of the
 whole list sends one of these instead of a `subscriber.deleted` per subscriber.
 

{broadcast_python-0.2.0.dist-info → broadcast_python-0.4.0.dist-info}/RECORD

@@ -1,12 +1,12 @@
 broadcast_python/__init__.py,sha256=_mzCFewxAEutE4fJ7hRPpaHuQwXpliHt5BNRE-J80TY,1632
-broadcast_python/client.py,sha256=9aS5Jhq06Um-nM0s9idUM2Cs_LkmJVG8THHqiHESbpA,5471
+broadcast_python/client.py,sha256=Sd_8vA0lFCl9Da3luwC10k9cGaREyK-AwotFXE4kb4c,5543
 broadcast_python/configuration.py,sha256=kXheoYhwRJo6STIL9Wmhl_MOEdWfaV3CBETEh1SbEcI,3961
 broadcast_python/connection.py,sha256=cAXyfwJ1pdleLm7S9fr1FUk5nqkdOTdav6dGZGJ0GfU,14064
 broadcast_python/errors.py,sha256=NFJ69Oy_FtYZ3-BEq8Q1m5wLqcufRZLPDYuJlgBfGpc,1993
 broadcast_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 broadcast_python/response.py,sha256=fIBzxi4a2Sc7sNSOb2_t85Y3Opdet89uNbHM5CX3YXw,5511
-broadcast_python/version.py,sha256=f52uUZ9_ePggmFw6jNA8hgza42_PJo1M9gSQXdKeymI,169
-broadcast_python/webhook.py,sha256=eLSxUkZ75dqEMoKfjLiG6SAVSVmxa0TQlhPl9MwZKaM,3679
+broadcast_python/version.py,sha256=4w8Ic2wUVGeOQ0Qa4FK6ErQDU1YfEIjcoIulx3E47j4,169
+broadcast_python/webhook.py,sha256=QamE73PkdyC6zax90Jd8FSmfbBBdX8lcbD4rSp7qYhw,3717
 broadcast_python/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 broadcast_python/resources/autopilots.py,sha256=yDXs7lPi2tqJwPEi_e156jRFQIkVamsdvYGiHax_7HM,3416
 broadcast_python/resources/base.py,sha256=-_uG_bAy_sz2oGHe2GQ64zRcpef6WZdMe4oHGJYFqEw,1632
@@ -15,17 +15,18 @@ broadcast_python/resources/channel_design.py,sha256=4xiJMGkiBjbCH35LQi_2DqrZV8n5
 broadcast_python/resources/discovery.py,sha256=B0BKq9hpRwd9gN4MWoPArz2dli4bQLZs9T6IYB8edC4,1960
 broadcast_python/resources/email_servers.py,sha256=1_ZJEPwVjFi5rN6S_0n7WfFfmF5y3JDIcW0Ixak0Z24,2830
 broadcast_python/resources/global_suppressions.py,sha256=5Nghq0AfQYLPEL_IAc_tmwGfovA5jpLmdw8yUxg6HpA,1730
-broadcast_python/resources/migration.py,sha256=y-GqY4BWzdNnlc6TWu7wNmqcqzEWSroxva1KiMqAJQg,4099
+broadcast_python/resources/migration.py,sha256=EvqUvn254Tr_mMVM7Ki3MZb0o0c8_PO4ZUo-lHnvBTA,4126
 broadcast_python/resources/opt_in_forms.py,sha256=ScoEKXejT27UfTL8iGxlsADO6g5Q-4xCpWOFtmM6q2E,2509
 broadcast_python/resources/segments.py,sha256=ZfUJxiWPhERWzkzuRGVu09uWqbwyUbdr3NsKOEeuW8o,857
 broadcast_python/resources/sequences.py,sha256=9IuKw13e_LYZMLZiBYrr0b-BPhAAAucdt8DUjQvbP80,2467
-broadcast_python/resources/subscribers.py,sha256=DtUnHs1rj3LF7KACQRQFB-ofgAHl1WTiLluL4W7xbfw,3168
+broadcast_python/resources/subscribers.py,sha256=EZu1cuWaBRZoXK3HB31-N46KpdeCfMvvpyRcdZNB5Lo,3515
 broadcast_python/resources/suppressions.py,sha256=3IHMkWHgU3ArxcDeMSzPDFWL1Ngag2-m04XNll31C8c,2354
 broadcast_python/resources/templates.py,sha256=FP0KcP61KkfrRID1XeAQ8hRxxRyxBzt404nXmnBqXNY,1262
+broadcast_python/resources/topics.py,sha256=jgspk04PgpxzGpehP9DO_AjKk361pgsbaYFR_BixLLs,980
 broadcast_python/resources/transactionals.py,sha256=iwe9aTHKpeEMtDxd_S2TVzdUVm5Phno-Vinrxu9bn6w,2940
 broadcast_python/resources/users.py,sha256=25gPmWLI1rqQnS9gCOi_2esUjdz_e0Zfi7_7Y2x91mg,4813
 broadcast_python/resources/webhook_endpoints.py,sha256=Llkry10QT3JavkmKok3IAayYKM1PD1-iI51YhW3RbpE,1180
-broadcast_python-0.2.0.dist-info/METADATA,sha256=lNr6zS4CcDh3Ws4Ts6_VnuCdo148GTkJeIAeE-V2NnQ,19364
-broadcast_python-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-broadcast_python-0.2.0.dist-info/licenses/LICENSE,sha256=cnoPKJuOFIyR8mBe7kmEcUQelniJaujjGl21QWqzlKE,1067
-broadcast_python-0.2.0.dist-info/RECORD,,
+broadcast_python-0.4.0.dist-info/METADATA,sha256=DoYhUeO0kqnOSMV1EFsED4vxbLdVC8ItBtMYAWLnqR4,20818
+broadcast_python-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+broadcast_python-0.4.0.dist-info/licenses/LICENSE,sha256=cnoPKJuOFIyR8mBe7kmEcUQelniJaujjGl21QWqzlKE,1067
+broadcast_python-0.4.0.dist-info/RECORD,,