easydata-api 1.0.1__tar.gz → 1.1.0__tar.gz

{easydata_api-1.0.1 → easydata_api-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easydata-api
-Version: 1.0.1
+Version: 1.1.0
 Summary: Official Python client for the EasyData LinkedIn enrichment API
 Author-email: EasyData Development <dev@easydata.win>
 License-Expression: MIT
@@ -76,10 +76,27 @@ between empty reads.
 
 ```python
 list(ed.results(batch_id, wait=False))       # what is readable right now
+ed.results_page(batch_id, cursor=c)          # one page, and the next cursor
 ed.wait(batch_id, timeout=600)               # the counters, not the rows
 ed.profiles_enrich.collect(urls)             # submit and drain, in one call
 ```
 
+## Streaming instead of polling
+
+```python
+for entry in ed.stream(batch.batch_id):
+    if entry.ok:
+        save(entry.data)
+```
+
+Same cursor, same entries, same order - the server pushes over a held
+connection, so a long batch costs one request instead of hundreds against your
+rate limit. Reconnects are handled and are exact: the event id IS the cursor, so
+a dropped connection resumes with no duplicates and no gaps.
+
+Use webhooks instead if you run a server with a public URL. This is for a client
+with nowhere to deliver to: an agent on a laptop, a CLI, an edge function.
+
 ## Retries and double-billing
 
 Retries are on by default and cover exactly what is safe to repeat: `429`, `5xx`

{easydata_api-1.0.1 → easydata_api-1.1.0}/README.md

@@ -55,10 +55,27 @@ between empty reads.
 
 ```python
 list(ed.results(batch_id, wait=False))       # what is readable right now
+ed.results_page(batch_id, cursor=c)          # one page, and the next cursor
 ed.wait(batch_id, timeout=600)               # the counters, not the rows
 ed.profiles_enrich.collect(urls)             # submit and drain, in one call
 ```
 
+## Streaming instead of polling
+
+```python
+for entry in ed.stream(batch.batch_id):
+    if entry.ok:
+        save(entry.data)
+```
+
+Same cursor, same entries, same order - the server pushes over a held
+connection, so a long batch costs one request instead of hundreds against your
+rate limit. Reconnects are handled and are exact: the event id IS the cursor, so
+a dropped connection resumes with no duplicates and no gaps.
+
+Use webhooks instead if you run a server with a public URL. This is for a client
+with nowhere to deliver to: an agent on a laptop, a CLI, an edge function.
+
 ## Retries and double-billing
 
 Retries are on by default and cover exactly what is safe to repeat: `429`, `5xx`

{easydata_api-1.0.1 → easydata_api-1.1.0}/easydata_api/__init__.py

@@ -33,6 +33,7 @@ from .errors import (
     Conflict,
     EasyDataError,
     EmailUnverified,
+    InsufficientScope,
     InternalError,
     InvalidAPIKey,
     InvalidRequest,
@@ -46,7 +47,7 @@ from .errors import (
 )
 from .webhooks import Delivery, VerificationError, verify, verify_ed25519
 
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 
 __all__ = [
     "EasyData",
@@ -62,6 +63,7 @@ __all__ = [
     "InvalidAPIKey",
     "QuotaExhausted",
     "EmailUnverified",
+    "InsufficientScope",
     "NotFound",
     "Conflict",
     "UnprocessableTarget",

{easydata_api-1.0.1 → easydata_api-1.1.0}/easydata_api/client.py

@@ -476,6 +476,94 @@ class EasyData:
             # rate limiter is counting.
             time.sleep((page.recommended_poll_ms or 2000) / 1000.0)
 
+    def stream(
+        self,
+        batch_id: str,
+        *,
+        cursor: str = "",
+        max_reconnects: int = 10,
+    ) -> Iterator[ResultEntry]:
+        """Stream a batch's entries over a held connection instead of polling.
+
+        Same cursor, same entries, same order as `results()` - the difference
+        is that the server pushes rather than the client asking, so a long
+        batch costs one request instead of hundreds against your rate limit.
+
+        Use webhooks instead if you run a server with a public URL. This is for
+        a client with nowhere to deliver to: an agent on a laptop, a CLI, an
+        edge function.
+
+        Reconnects are handled here and are exact: the event id IS the cursor,
+        so a dropped connection resumes where it stopped with no duplicates and
+        no gaps. The iterator ends when the batch reaches a terminal state.
+
+            for entry in ed.stream(batch.batch_id):
+                if entry.ok:
+                    save(entry.data)
+        """
+        reconnects = 0
+
+        while True:
+            url = f"{self.base_url}/batches/{batch_id}/results"
+            if cursor:
+                url += "?" + urllib.parse.urlencode({"cursor": cursor})
+
+            headers = {
+                "X-API-Key": self.api_key,
+                "Accept": "text/event-stream",
+                "User-Agent": self.user_agent,
+            }
+            if cursor:
+                # Where to resume. The server prefers this over ?cursor= for
+                # the same reason a browser sends it: it is the more recent of
+                # the two.
+                headers["Last-Event-ID"] = cursor
+
+            req = urllib.request.Request(url, headers=headers, method="GET")
+            complete = False
+
+            try:
+                # No read timeout: a stream that stays open is the point. The
+                # server ends it with `timeout` after its own limit.
+                with urllib.request.urlopen(req) as resp:
+                    for event, data, event_id in _parse_sse(resp):
+                        if event_id:
+                            cursor = event_id
+
+                        if event == "result":
+                            yield ResultEntry.from_json(json.loads(data))
+                        elif event == "complete":
+                            complete = True
+                            break
+                        elif event == "error":
+                            raise EasyDataError(
+                                f"stream failed: {data}. Resume from cursor {cursor}."
+                            )
+                        # `timeout` is the server ending a long stream on
+                        # purpose. Falling through re-opens from the cursor,
+                        # which is what it asked for - a caller never sees it.
+            except urllib.error.HTTPError as exc:
+                raise error_for(exc.code, _decode(exc.read())) from exc
+            except (urllib.error.URLError, OSError) as exc:
+                # A dropped connection is the case reconnecting exists for.
+                if reconnects >= max_reconnects:
+                    raise TransportError(
+                        f"stream dropped and could not be resumed from {cursor}: {exc}"
+                    ) from exc
+                reconnects += 1
+                time.sleep(self._backoff(reconnects, None))
+                continue
+
+            if complete:
+                return
+
+            # Ended without a `complete`. Re-open from the cursor.
+            reconnects += 1
+            if reconnects > max_reconnects:
+                raise TransportError(
+                    f"stream dropped {reconnects} times without completing; last cursor {cursor}"
+                )
+
     def wait(self, batch_id: str, *, timeout: float | None = None) -> Batch:
         """Block until a batch reaches a terminal state, and return it.
 
@@ -609,6 +697,45 @@ class EasyData:
         return webhooks.verify(secret, headers, body, **kw)
 
 
+def _parse_sse(stream: Any) -> Iterator[tuple[str, str, str]]:
+    """The wire format of Server-Sent Events, as (event, data, id) triples.
+
+    Hand-rolled rather than a dependency, because this client has none and the
+    format is three rules: events are separated by a blank line, fields are
+    `name: value`, and a line starting with `:` is a comment.
+
+    Fields accumulate until a blank line, so a `data:` split across two reads is
+    reassembled rather than parsed as half an entry.
+    """
+    event, data, event_id = "message", [], ""
+
+    for raw in stream:
+        line = raw.decode("utf-8", "replace").rstrip("\n").rstrip("\r")
+
+        if not line:
+            if data or event != "message":
+                yield event, "\n".join(data), event_id
+            event, data, event_id = "message", [], ""
+            continue
+
+        if line.startswith(":"):
+            continue  # keepalive comment
+
+        field, _, value = line.partition(":")
+        # One optional space after the colon is part of the framing.
+        value = value[1:] if value.startswith(" ") else value
+
+        if field == "event":
+            event = value
+        elif field == "data":
+            data.append(value)
+        elif field == "id":
+            event_id = value
+
+    if data or event != "message":
+        yield event, "\n".join(data), event_id
+
+
 def _put(d: dict[str, Any], **kwargs: Any) -> None:
     """Sets the keyword arguments that were actually given.
 

{easydata_api-1.0.1 → easydata_api-1.1.0}/easydata_api/errors.py

@@ -86,6 +86,20 @@ class EmailUnverified(EasyDataError):
     type = "email_unverified"
 
 
+class InsufficientScope(EasyDataError):
+    """403. The key is valid and is the WRONG one.
+
+    It does not carry the scope this route needs - `read` to page results,
+    `write` to submit, cancel or change the account. The message names which.
+
+    Never retried, by this client or by you: no amount of waiting gives a
+    credential a scope it was not minted with. Mint a key that carries it.
+    `EasyData.account()["scopes"]` reports what the current key holds.
+    """
+
+    type = "insufficient_scope"
+
+
 class NotFound(EasyDataError):
     """404. A batch id that is not yours, or is not a batch."""
 
@@ -155,6 +169,7 @@ _BY_TYPE = {
         InvalidAPIKey,
         QuotaExhausted,
         EmailUnverified,
+        InsufficientScope,
         NotFound,
         Conflict,
         UnprocessableTarget,

{easydata_api-1.0.1 → easydata_api-1.1.0}/easydata_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easydata-api
-Version: 1.0.1
+Version: 1.1.0
 Summary: Official Python client for the EasyData LinkedIn enrichment API
 Author-email: EasyData Development <dev@easydata.win>
 License-Expression: MIT
@@ -76,10 +76,27 @@ between empty reads.
 
 ```python
 list(ed.results(batch_id, wait=False))       # what is readable right now
+ed.results_page(batch_id, cursor=c)          # one page, and the next cursor
 ed.wait(batch_id, timeout=600)               # the counters, not the rows
 ed.profiles_enrich.collect(urls)             # submit and drain, in one call
 ```
 
+## Streaming instead of polling
+
+```python
+for entry in ed.stream(batch.batch_id):
+    if entry.ok:
+        save(entry.data)
+```
+
+Same cursor, same entries, same order - the server pushes over a held
+connection, so a long batch costs one request instead of hundreds against your
+rate limit. Reconnects are handled and are exact: the event id IS the cursor, so
+a dropped connection resumes with no duplicates and no gaps.
+
+Use webhooks instead if you run a server with a public URL. This is for a client
+with nowhere to deliver to: an agent on a laptop, a CLI, an edge function.
+
 ## Retries and double-billing
 
 Retries are on by default and cover exactly what is safe to repeat: `429`, `5xx`

{easydata_api-1.0.1 → easydata_api-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "easydata-api"
-version = "1.0.1"
+version = "1.1.0"
 description = "Official Python client for the EasyData LinkedIn enrichment API"
 readme = "README.md"
 requires-python = ">=3.10"

{easydata_api-1.0.1 → easydata_api-1.1.0}/tests/test_client.py

@@ -18,7 +18,7 @@ from http.server import BaseHTTPRequestHandler, HTTPServer
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
-from easydata_api import EasyData, InvalidRequest, RateLimited, webhooks  # noqa: E402
+from easydata_api import EasyData, EasyDataError, InvalidRequest, RateLimited, webhooks  # noqa: E402
 from easydata_api.errors import TransportError  # noqa: E402
 
 
@@ -265,6 +265,83 @@ class TestResultsCursor(ServerCase):
         self.assertIn("b-1", str(ctx.exception))
 
 
+class _SSEHandler(BaseHTTPRequestHandler):
+    """Serves a scripted SSE body, one small chunk at a time."""
+
+    def log_message(self, *args):  # noqa: D102
+        pass
+
+    def do_GET(self):
+        self.server.seen.append({k.lower(): v for k, v in self.headers.items()})
+        body = self.server.bodies.pop(0) if self.server.bodies else "event: complete\ndata: {}\n\n"
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.end_headers()
+        # Deliberately tiny writes: a `data:` line split across reads is the
+        # bug every naive SSE parser has.
+        raw = body.encode()
+        for i in range(0, len(raw), 5):
+            self.wfile.write(raw[i : i + 5])
+            self.wfile.flush()
+
+
+class TestStreaming(unittest.TestCase):
+    def serve(self, bodies):
+        server = HTTPServer(("127.0.0.1", 0), _SSEHandler)
+        server.bodies = list(bodies)
+        server.seen = []
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        self.addCleanup(server.server_close)
+        self.addCleanup(server.shutdown)
+        host, port = server.server_address
+        return EasyData("pk_x", base_url=f"http://{host}:{port}"), server
+
+    def test_it_yields_entries_and_stops_on_complete(self):
+        client, server = self.serve([
+            'id: c1\nevent: result\ndata: {"item_index":0,"status":"succeeded","credits_used":1}\n\n'
+            ": keepalive\n\n"
+            'id: c2\nevent: result\ndata: {"item_index":1,"status":"succeeded","credits_used":1}\n\n'
+            'id: c3\nevent: complete\ndata: {"status":"completed"}\n\n'
+        ])
+
+        got = list(client.stream("b-1"))
+
+        self.assertEqual([e.item_index for e in got], [0, 1],
+                         "a keepalive comment was parsed as an entry")
+        self.assertEqual(server.seen[0]["accept"], "text/event-stream")
+
+    def test_a_chunk_boundary_does_not_split_an_entry(self):
+        client, _ = self.serve([
+            'id: c1\nevent: result\ndata: {"item_index":7,"status":"succeeded","credits_used":1}\n\n'
+            'event: complete\ndata: {}\n\n'
+        ])
+        (got,) = list(client.stream("b-1"))
+        self.assertEqual(got.item_index, 7)
+
+    def test_a_dropped_stream_resumes_from_the_last_event_id(self):
+        """The whole reason the event id is the cursor: resuming must be exact."""
+        client, server = self.serve([
+            'id: c1\nevent: result\ndata: {"item_index":0,"status":"succeeded","credits_used":1}\n\n',
+            'id: c2\nevent: result\ndata: {"item_index":1,"status":"succeeded","credits_used":1}\n\n'
+            'event: complete\ndata: {}\n\n',
+        ])
+
+        got = list(client.stream("b-1"))
+
+        self.assertEqual([e.item_index for e in got], [0, 1])
+        self.assertEqual(len(server.seen), 2, "the dropped connection was not re-opened")
+        self.assertEqual(server.seen[1]["last-event-id"], "c1", "resumed from the wrong position")
+
+    def test_an_error_event_names_the_cursor(self):
+        client, _ = self.serve([
+            'id: c9\nevent: error\ndata: {"type":"internal_error","cursor":"c9"}\n\n'
+        ])
+        with self.assertRaises(EasyDataError) as ctx:
+            list(client.stream("b-1"))
+        self.assertIn("c9", str(ctx.exception))
+
+
 class TestWebhookVerification(unittest.TestCase):
     SECRET = "whsec_test"
 
@@ -310,7 +387,7 @@ class TestWebhookVerification(unittest.TestCase):
         self.assertEqual(d.data["result"]["status"], "succeeded")
 
     def test_the_go_signers_own_output_verifies(self):
-        """A vector produced by backend/internal/webhooks.Sign itself.
+        """A vector produced by the server's own webhook signer.
 
         Every other test here signs with this file's own HMAC, which would keep
         passing if both sides were wrong in the same way. This one is the output
@@ -318,8 +395,8 @@ class TestWebhookVerification(unittest.TestCase):
         change to either implementation that breaks the other fails here rather
         than in a customer's receiver.
 
-        Regenerate by calling Sign("whsec_cross_check", time.Unix(1789000000, 0),
-        body) in a Go test.
+        Regenerate from the server's signing function with the secret
+        "whsec_cross_check" and the unix timestamp 1789000000.
         """
         body = (
             b'{"id":"d-1","event":"batch.result","createdAt":"2026-09-01T10:00:00Z",'