flashdata 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
flashdata/__init__.py ADDED
@@ -0,0 +1,34 @@
1
+ """Official FlashData Python SDK."""
2
+
3
+ from ._client import FlashData
4
+ from ._async_client import AsyncFlashData
5
+ from .errors import (
6
+ APIError,
7
+ ConnectionError,
8
+ FlashDataError,
9
+ JobFailedError,
10
+ JobPausedError,
11
+ PollingTimeoutError,
12
+ ProtocolError,
13
+ RequestTimeoutError,
14
+ ResponseTooLargeError,
15
+ SubmissionUnknownError,
16
+ ValidationError,
17
+ )
18
+
19
+ __version__ = "1.0.0"
20
+ __all__ = [
21
+ "FlashData",
22
+ "AsyncFlashData",
23
+ "APIError",
24
+ "ConnectionError",
25
+ "FlashDataError",
26
+ "JobFailedError",
27
+ "JobPausedError",
28
+ "PollingTimeoutError",
29
+ "ProtocolError",
30
+ "RequestTimeoutError",
31
+ "ResponseTooLargeError",
32
+ "SubmissionUnknownError",
33
+ "ValidationError",
34
+ ]
@@ -0,0 +1,213 @@
1
+ from __future__ import annotations
2
+ import asyncio
3
+ import os
4
+ import ssl
5
+ from pathlib import Path
6
+ from typing import Any
7
+ import httpx
8
+ from ._common import api_error, decode_json, origin, positive, secret_values, signed_url, integer
9
+ from .errors import (
10
+ ConnectionError,
11
+ ProtocolError,
12
+ RequestTimeoutError,
13
+ ResponseTooLargeError,
14
+ SubmissionUnknownError,
15
+ ValidationError,
16
+ )
17
+ from ._resources import AsyncQueries, AsyncAccount, AsyncJobs, AsyncBulk, AsyncGoogle, AsyncYouTube, AsyncPublic
18
+
19
+
20
+ class AsyncFlashData:
21
+ """Asynchronous API-key client. No network requests are automatically retried."""
22
+
23
+ def __init__(
24
+ self,
25
+ api_key: str | None = None,
26
+ *,
27
+ data_url: str = "https://data.flashdata.dev",
28
+ management_url: str = "https://api.flashdata.dev",
29
+ timeout: float = 120,
30
+ max_response_bytes: int = 64 * 1024 * 1024,
31
+ max_line_bytes: int = 16 * 1024 * 1024,
32
+ transport: Any = None,
33
+ storage_transport: Any = None,
34
+ proxy: str | None = None,
35
+ verify: ssl.SSLContext | bool = True,
36
+ trust_env: bool = True,
37
+ ):
38
+ key = api_key if api_key is not None else os.environ.get("FLASHDATA_API_KEY", "")
39
+ if not isinstance(key, str) or any(not "\x20" <= char <= "\x7e" for char in key):
40
+ raise ValidationError("api_key must be an ASCII string without control characters.")
41
+ self._key = key.strip()
42
+ self._result_origin: str | None = None
43
+ self.data_url, self.management_url = origin(data_url), origin(management_url)
44
+ self.timeout = positive(timeout, "timeout")
45
+ self.max_response_bytes = integer(max_response_bytes, "max_response_bytes", 1, 2**53 - 1)
46
+ self.max_line_bytes = integer(max_line_bytes, "max_line_bytes", 1, 2**53 - 1)
47
+ self._http = httpx.AsyncClient(
48
+ transport=transport,
49
+ timeout=timeout,
50
+ follow_redirects=False,
51
+ proxy=proxy,
52
+ verify=verify,
53
+ trust_env=trust_env,
54
+ )
55
+ self._storage = httpx.AsyncClient(
56
+ transport=storage_transport if storage_transport is not None else transport,
57
+ timeout=timeout,
58
+ follow_redirects=False,
59
+ proxy=proxy,
60
+ verify=verify,
61
+ trust_env=trust_env,
62
+ )
63
+ self.queries = AsyncQueries(self)
64
+ self.account = AsyncAccount(self)
65
+ self.jobs = AsyncJobs(self)
66
+ self.bulk = AsyncBulk(self)
67
+ self.google = AsyncGoogle(self)
68
+ self.youtube = AsyncYouTube(self)
69
+ self.public = AsyncPublic(self)
70
+
71
+ def __repr__(self) -> str:
72
+ return "<AsyncFlashData>"
73
+
74
+ async def __aenter__(self) -> AsyncFlashData:
75
+ return self
76
+
77
+ async def __aexit__(self, *_args: Any) -> None:
78
+ await self.aclose()
79
+
80
+ async def aclose(self) -> None:
81
+ await self._http.aclose()
82
+ await self._storage.aclose()
83
+
84
+ async def _read(self, response: httpx.Response) -> bytes:
85
+ content = bytearray()
86
+ async for chunk in response.aiter_bytes():
87
+ content.extend(chunk)
88
+ if len(content) > self.max_response_bytes:
89
+ raise ResponseTooLargeError("Response exceeds max_response_bytes.")
90
+ return bytes(content)
91
+
92
+ async def _request(
93
+ self,
94
+ method: str,
95
+ path: str,
96
+ *,
97
+ body: Any = None,
98
+ params: Any = None,
99
+ data: bool = False,
100
+ public: bool = False,
101
+ timeout: float | None = None,
102
+ redirect: bool = False,
103
+ ) -> Any:
104
+ if not public and not self._key:
105
+ raise ValidationError("Set FLASHDATA_API_KEY or pass api_key before calling an authenticated endpoint.")
106
+ if timeout is not None:
107
+ positive(timeout, "timeout")
108
+ base = self.data_url if data else self.management_url
109
+ url = base + ("" if data else "/v2") + path
110
+ headers = {"Accept": "application/json", "User-Agent": "flashdata-python/1.0.0"}
111
+ if not public:
112
+ headers["X-API-Key"] = self._key
113
+ try:
114
+ async with self._http.stream(
115
+ method,
116
+ url,
117
+ headers=headers,
118
+ params=params,
119
+ json=body,
120
+ timeout=timeout if timeout is not None else self.timeout,
121
+ ) as response:
122
+ if redirect and response.status_code == 302:
123
+ location = response.headers.get("location")
124
+ if not location:
125
+ raise ProtocolError("Signed result redirect is missing its location.")
126
+ return location
127
+ raw = await self._read(response)
128
+ if not 200 <= response.status_code < 300:
129
+ raise api_error(response, raw, (self._key,) + secret_values(body))
130
+ return decode_json(raw)
131
+ except httpx.TimeoutException:
132
+ if method != "GET":
133
+ raise SubmissionUnknownError(
134
+ "Request response was lost; it may have been accepted. Reconcile before repeating it."
135
+ ) from None
136
+ raise RequestTimeoutError("Read request timed out.") from None
137
+ except httpx.RequestError:
138
+ if method != "GET":
139
+ raise SubmissionUnknownError(
140
+ "Request response was lost; it may have been accepted. Reconcile before repeating it."
141
+ ) from None
142
+ raise ConnectionError("Network request failed.") from None
143
+
144
+ async def _result(self, path: str, *, binary: bool = False, timeout: float | None = None) -> Any:
145
+ location = await self._request("GET", path, redirect=True, timeout=timeout)
146
+ if not isinstance(location, str):
147
+ # Supports a future direct JSON response without exposing credentials to storage.
148
+ if binary:
149
+ raise ProtocolError("Expected a signed result redirect.")
150
+ return location
151
+ if self._result_origin is None:
152
+ self._result_origin = (await self.account.access(timeout=timeout)).get("result_origin")
153
+ url = signed_url(location, self._result_origin)
154
+ try:
155
+ async with self._storage.stream(
156
+ "GET",
157
+ url,
158
+ headers={"Accept": "application/json"},
159
+ timeout=timeout if timeout is not None else self.timeout,
160
+ ) as response:
161
+ raw = await self._read(response)
162
+ if not 200 <= response.status_code < 300:
163
+ raise api_error(response, raw, (self._key, url))
164
+ return raw if binary else decode_json(raw)
165
+ except httpx.TimeoutException:
166
+ raise RequestTimeoutError("Signed result read timed out.") from None
167
+ except httpx.RequestError:
168
+ raise ConnectionError("Signed result read failed.") from None
169
+
170
+ async def _upload(
171
+ self, created: dict[str, Any], path: str | os.PathLike[str], *, timeout: float | None = None
172
+ ) -> None:
173
+ if timeout is not None:
174
+ positive(timeout, "timeout")
175
+ if not isinstance(created, dict) or not isinstance(created.get("upload"), dict):
176
+ raise ValidationError("Pass the complete receipt returned by bulk.create().")
177
+ upload = created.get("upload", {})
178
+ if upload.get("method") != "PUT" or upload.get("contentType") != "text/plain; charset=utf-8":
179
+ raise ProtocolError("Invalid bulk upload descriptor.")
180
+ file = Path(path)
181
+ size = file.stat().st_size
182
+ if not 0 < size <= 2147483648:
183
+ raise ValidationError("Bulk input must contain 1 byte to 2 GiB of UTF-8 video IDs.")
184
+ if self._result_origin is None:
185
+ self._result_origin = (await self.account.access(timeout=timeout)).get("result_origin")
186
+ url = signed_url(upload.get("href"), self._result_origin)
187
+
188
+ async def chunks():
189
+ with file.open("rb") as stream:
190
+ while True:
191
+ chunk = await asyncio.to_thread(stream.read, 65536)
192
+ if not chunk:
193
+ break
194
+ yield chunk
195
+
196
+ try:
197
+ async with self._storage.stream(
198
+ "PUT",
199
+ url,
200
+ content=chunks(),
201
+ timeout=timeout if timeout is not None else self.timeout,
202
+ headers={
203
+ "Content-Type": upload["contentType"],
204
+ "Content-Length": str(size),
205
+ },
206
+ ) as response:
207
+ raw = await self._read(response)
208
+ if not 200 <= response.status_code < 300:
209
+ raise api_error(response, raw, (self._key, url))
210
+ except httpx.RequestError:
211
+ raise ConnectionError(
212
+ "Bulk input upload failed. The bulk ID remains available; upload and start separately."
213
+ ) from None
flashdata/_client.py ADDED
@@ -0,0 +1,210 @@
1
+ from __future__ import annotations
2
+ import os
3
+ import ssl
4
+ from pathlib import Path
5
+ from typing import Any
6
+ import httpx
7
+ from ._common import api_error, decode_json, origin, positive, secret_values, signed_url, integer
8
+ from .errors import (
9
+ ConnectionError,
10
+ ProtocolError,
11
+ RequestTimeoutError,
12
+ ResponseTooLargeError,
13
+ SubmissionUnknownError,
14
+ ValidationError,
15
+ )
16
+ from ._resources import Queries, Account, Jobs, Bulk, Google, YouTube, Public
17
+
18
+
19
+ class FlashData:
20
+ """Synchronous API-key client. No network requests are automatically retried."""
21
+
22
+ def __init__(
23
+ self,
24
+ api_key: str | None = None,
25
+ *,
26
+ data_url: str = "https://data.flashdata.dev",
27
+ management_url: str = "https://api.flashdata.dev",
28
+ timeout: float = 120,
29
+ max_response_bytes: int = 64 * 1024 * 1024,
30
+ max_line_bytes: int = 16 * 1024 * 1024,
31
+ transport: Any = None,
32
+ storage_transport: Any = None,
33
+ proxy: str | None = None,
34
+ verify: ssl.SSLContext | bool = True,
35
+ trust_env: bool = True,
36
+ ):
37
+ key = api_key if api_key is not None else os.environ.get("FLASHDATA_API_KEY", "")
38
+ if not isinstance(key, str) or any(not "\x20" <= char <= "\x7e" for char in key):
39
+ raise ValidationError("api_key must be an ASCII string without control characters.")
40
+ self._key = key.strip()
41
+ self._result_origin: str | None = None
42
+ self.data_url, self.management_url = origin(data_url), origin(management_url)
43
+ self.timeout = positive(timeout, "timeout")
44
+ self.max_response_bytes = integer(max_response_bytes, "max_response_bytes", 1, 2**53 - 1)
45
+ self.max_line_bytes = integer(max_line_bytes, "max_line_bytes", 1, 2**53 - 1)
46
+ self._http = httpx.Client(
47
+ transport=transport,
48
+ timeout=timeout,
49
+ follow_redirects=False,
50
+ proxy=proxy,
51
+ verify=verify,
52
+ trust_env=trust_env,
53
+ )
54
+ self._storage = httpx.Client(
55
+ transport=storage_transport if storage_transport is not None else transport,
56
+ timeout=timeout,
57
+ follow_redirects=False,
58
+ proxy=proxy,
59
+ verify=verify,
60
+ trust_env=trust_env,
61
+ )
62
+ self.queries = Queries(self)
63
+ self.account = Account(self)
64
+ self.jobs = Jobs(self)
65
+ self.bulk = Bulk(self)
66
+ self.google = Google(self)
67
+ self.youtube = YouTube(self)
68
+ self.public = Public(self)
69
+
70
+ def __repr__(self) -> str:
71
+ return "<FlashData>"
72
+
73
+ def __enter__(self) -> FlashData:
74
+ return self
75
+
76
+ def __exit__(self, *_args: Any) -> None:
77
+ self.close()
78
+
79
+ def close(self) -> None:
80
+ self._http.close()
81
+ self._storage.close()
82
+
83
+ def _read(self, response: httpx.Response) -> bytes:
84
+ content = bytearray()
85
+ for chunk in response.iter_bytes():
86
+ content.extend(chunk)
87
+ if len(content) > self.max_response_bytes:
88
+ raise ResponseTooLargeError("Response exceeds max_response_bytes.")
89
+ return bytes(content)
90
+
91
+ def _request(
92
+ self,
93
+ method: str,
94
+ path: str,
95
+ *,
96
+ body: Any = None,
97
+ params: Any = None,
98
+ data: bool = False,
99
+ public: bool = False,
100
+ timeout: float | None = None,
101
+ redirect: bool = False,
102
+ ) -> Any:
103
+ if not public and not self._key:
104
+ raise ValidationError("Set FLASHDATA_API_KEY or pass api_key before calling an authenticated endpoint.")
105
+ if timeout is not None:
106
+ positive(timeout, "timeout")
107
+ base = self.data_url if data else self.management_url
108
+ url = base + ("" if data else "/v2") + path
109
+ headers = {"Accept": "application/json", "User-Agent": "flashdata-python/1.0.0"}
110
+ if not public:
111
+ headers["X-API-Key"] = self._key
112
+ try:
113
+ with self._http.stream(
114
+ method,
115
+ url,
116
+ headers=headers,
117
+ params=params,
118
+ json=body,
119
+ timeout=timeout if timeout is not None else self.timeout,
120
+ ) as response:
121
+ if redirect and response.status_code == 302:
122
+ location = response.headers.get("location")
123
+ if not location:
124
+ raise ProtocolError("Signed result redirect is missing its location.")
125
+ return location
126
+ raw = self._read(response)
127
+ if not 200 <= response.status_code < 300:
128
+ raise api_error(response, raw, (self._key,) + secret_values(body))
129
+ return decode_json(raw)
130
+ except httpx.TimeoutException:
131
+ if method != "GET":
132
+ raise SubmissionUnknownError(
133
+ "Request response was lost; it may have been accepted. Reconcile before repeating it."
134
+ ) from None
135
+ raise RequestTimeoutError("Read request timed out.") from None
136
+ except httpx.RequestError:
137
+ if method != "GET":
138
+ raise SubmissionUnknownError(
139
+ "Request response was lost; it may have been accepted. Reconcile before repeating it."
140
+ ) from None
141
+ raise ConnectionError("Network request failed.") from None
142
+
143
+ def _result(self, path: str, *, binary: bool = False, timeout: float | None = None) -> Any:
144
+ location = self._request("GET", path, redirect=True, timeout=timeout)
145
+ if not isinstance(location, str):
146
+ # Supports a future direct JSON response without exposing credentials to storage.
147
+ if binary:
148
+ raise ProtocolError("Expected a signed result redirect.")
149
+ return location
150
+ if self._result_origin is None:
151
+ self._result_origin = self.account.access(timeout=timeout).get("result_origin")
152
+ url = signed_url(location, self._result_origin)
153
+ try:
154
+ with self._storage.stream(
155
+ "GET",
156
+ url,
157
+ headers={"Accept": "application/json"},
158
+ timeout=timeout if timeout is not None else self.timeout,
159
+ ) as response:
160
+ raw = self._read(response)
161
+ if not 200 <= response.status_code < 300:
162
+ raise api_error(response, raw, (self._key, url))
163
+ return raw if binary else decode_json(raw)
164
+ except httpx.TimeoutException:
165
+ raise RequestTimeoutError("Signed result read timed out.") from None
166
+ except httpx.RequestError:
167
+ raise ConnectionError("Signed result read failed.") from None
168
+
169
+ def _upload(self, created: dict[str, Any], path: str | os.PathLike[str], *, timeout: float | None = None) -> None:
170
+ if timeout is not None:
171
+ positive(timeout, "timeout")
172
+ if not isinstance(created, dict) or not isinstance(created.get("upload"), dict):
173
+ raise ValidationError("Pass the complete receipt returned by bulk.create().")
174
+ upload = created.get("upload", {})
175
+ if upload.get("method") != "PUT" or upload.get("contentType") != "text/plain; charset=utf-8":
176
+ raise ProtocolError("Invalid bulk upload descriptor.")
177
+ file = Path(path)
178
+ size = file.stat().st_size
179
+ if not 0 < size <= 2147483648:
180
+ raise ValidationError("Bulk input must contain 1 byte to 2 GiB of UTF-8 video IDs.")
181
+ if self._result_origin is None:
182
+ self._result_origin = self.account.access(timeout=timeout).get("result_origin")
183
+ url = signed_url(upload.get("href"), self._result_origin)
184
+
185
+ def chunks():
186
+ with file.open("rb") as stream:
187
+ while True:
188
+ chunk = stream.read(65536)
189
+ if not chunk:
190
+ break
191
+ yield chunk
192
+
193
+ try:
194
+ with self._storage.stream(
195
+ "PUT",
196
+ url,
197
+ content=chunks(),
198
+ timeout=timeout if timeout is not None else self.timeout,
199
+ headers={
200
+ "Content-Type": upload["contentType"],
201
+ "Content-Length": str(size),
202
+ },
203
+ ) as response:
204
+ raw = self._read(response)
205
+ if not 200 <= response.status_code < 300:
206
+ raise api_error(response, raw, (self._key, url))
207
+ except httpx.RequestError:
208
+ raise ConnectionError(
209
+ "Bulk input upload failed. The bulk ID remains available; upload and start separately."
210
+ ) from None