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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easydata-api
-Version: 1.0.2
+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.2 → 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.2 → 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.2"
+__version__ = "1.1.0"
 
 __all__ = [
     "EasyData",
@@ -62,6 +63,7 @@ __all__ = [
     "InvalidAPIKey",
     "QuotaExhausted",
     "EmailUnverified",
+    "InsufficientScope",
     "NotFound",
     "Conflict",
     "UnprocessableTarget",

{easydata_api-1.0.2 → 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.2 → 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.2 → 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.2
+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.2 → easydata_api-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "easydata-api"
-version = "1.0.2"
+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.2 → 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"