pandafile 0.2.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.
pandafile/__init__.py ADDED
@@ -0,0 +1,37 @@
1
+ """Pandafile – the official Python SDK. https://pandafile.co/developers/sdks
2
+
3
+ from pandafile import Pandafile
4
+ pf = Pandafile() # PANDAFILE_API_KEY
5
+ print(pf.transfers.send(["film.mov"]).url)
6
+ """
7
+ from . import types, webhooks
8
+ from ._client import DEFAULT_BASE_URL, AsyncPandafile, Pandafile
9
+ from ._errors import (
10
+ APIConnectionError,
11
+ APIError,
12
+ AuthenticationError,
13
+ IdempotencyError,
14
+ InvalidRequestError,
15
+ NotFoundError,
16
+ PandafileError,
17
+ PermissionDeniedError,
18
+ RateLimitError,
19
+ SignatureVerificationError,
20
+ UploadError,
21
+ )
22
+ from ._files import PreparedFile, prepare_files
23
+ from ._pagination import AsyncPage, AsyncPager, Page, SyncPage, SyncPager
24
+ from ._send import FileProgress, SendProgress, SendResult
25
+ from ._tus import DEFAULT_CHUNK_SIZE, TusResult, encode_metadata, tus_upload, tus_upload_async
26
+ from ._version import __version__
27
+ from .types import API_VERSION, EVENT_TYPES
28
+
29
+ __all__ = [
30
+ "Pandafile", "AsyncPandafile", "DEFAULT_BASE_URL", "API_VERSION", "EVENT_TYPES", "__version__",
31
+ "webhooks", "types",
32
+ "PandafileError", "InvalidRequestError", "NotFoundError", "AuthenticationError", "PermissionDeniedError", "IdempotencyError",
33
+ "RateLimitError", "APIError", "APIConnectionError", "SignatureVerificationError", "UploadError",
34
+ "Page", "SyncPage", "AsyncPage", "SyncPager", "AsyncPager",
35
+ "SendProgress", "SendResult", "FileProgress", "PreparedFile", "prepare_files",
36
+ "tus_upload", "tus_upload_async", "encode_metadata", "TusResult", "DEFAULT_CHUNK_SIZE",
37
+ ]
pandafile/_client.py ADDED
@@ -0,0 +1,243 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import json as _json
5
+ import os
6
+ import platform
7
+ import random
8
+ import time
9
+ import uuid
10
+ from email.utils import parsedate_to_datetime
11
+ from typing import Any, Dict, Mapping, Optional, Tuple
12
+ from urllib.parse import urlencode
13
+
14
+ import httpx
15
+
16
+ from . import webhooks as _webhooks
17
+ from ._errors import APIConnectionError, PandafileError, error_from_response
18
+ from ._pagination import AsyncPager, SyncPager
19
+ from ._resources import Branding, Domains, Events, FileRequests, Hooks, Keys, Me, Signatures, Team, Transfers
20
+ from ._send import send_async, send_sync
21
+ from ._version import __version__
22
+ from .types import API_VERSION
23
+
24
+ DEFAULT_BASE_URL = "https://pandafile.co"
25
+ RETRY_STATUS = {408, 429, 500, 502, 503, 504}
26
+
27
+
28
+ def _retry_after(headers: Mapping[str, str]) -> Optional[float]:
29
+ v = headers.get("retry-after")
30
+ if not v:
31
+ return None
32
+ try:
33
+ return max(0.0, float(v))
34
+ except ValueError:
35
+ try:
36
+ return max(0.0, parsedate_to_datetime(v).timestamp() - time.time())
37
+ except (TypeError, ValueError):
38
+ return None
39
+
40
+
41
+ def _backoff(attempt: int, base: float = 0.5, cap: float = 8.0) -> float:
42
+ d = min(cap, base * (2 ** attempt))
43
+ return d / 2 + random.random() * d / 2
44
+
45
+
46
+ def _parse(r: httpx.Response) -> Any:
47
+ if not r.content:
48
+ return None
49
+ try:
50
+ return r.json()
51
+ except ValueError:
52
+ return r.text
53
+
54
+
55
+ class _Base:
56
+ def __init__(self, api_key: Optional[str], base_url: Optional[str], api_version: Optional[str], max_retries: int, timeout: float, app_info: Optional[str]) -> None:
57
+ key = api_key or os.environ.get("PANDAFILE_API_KEY")
58
+ if not key:
59
+ raise PandafileError("No API key: pass api_key=... or set PANDAFILE_API_KEY.", type="authentication_error", code="api_key_missing")
60
+ self.api_key = key
61
+ self.base_url = (base_url or os.environ.get("PANDAFILE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
62
+ self.api_version = api_version or API_VERSION
63
+ self.max_retries = max_retries
64
+ self.timeout = timeout
65
+ self.user_agent = f"pandafile-python/{__version__} python/{platform.python_version()}" + (f" {app_info}" if app_info else "")
66
+ self.last_response: Optional[Dict[str, Any]] = None
67
+ self.me = Me(self)
68
+ self.keys = Keys(self)
69
+ self.domains = Domains(self)
70
+ self.transfers = Transfers(self)
71
+ self.requests = FileRequests(self)
72
+ self.signatures = Signatures(self)
73
+ self.branding = Branding(self)
74
+ self.team = Team(self)
75
+ self.events = Events(self)
76
+ self.hooks = Hooks(self)
77
+
78
+ webhooks = _webhooks
79
+
80
+ @property
81
+ def livemode(self) -> bool:
82
+ return not self.api_key.startswith("pf_test_")
83
+
84
+ def _url(self, path: str, query: Optional[Mapping[str, Any]]) -> str:
85
+ url = f"{self.base_url}/api/v1{path}"
86
+ q = {k: ("true" if v is True else "false" if v is False else v) for k, v in (query or {}).items() if v is not None and v != ""}
87
+ return url + ("?" + urlencode(q) if q else "")
88
+
89
+ def _prepare(self, method: str, json: Any, content: Optional[bytes], content_type: Optional[str], binary: bool,
90
+ idempotency_key: Optional[str], headers: Optional[Mapping[str, str]]) -> Tuple[Dict[str, str], Optional[bytes]]:
91
+ h = {
92
+ "Authorization": f"Bearer {self.api_key}",
93
+ "Pandafile-Version": self.api_version,
94
+ "Accept": "*/*" if binary else "application/json",
95
+ "User-Agent": self.user_agent,
96
+ }
97
+ body: Optional[bytes] = None
98
+ if content is not None:
99
+ h["Content-Type"] = content_type or "application/octet-stream"
100
+ body = content
101
+ elif json is not None:
102
+ h["Content-Type"] = "application/json"
103
+ body = _json.dumps(json).encode("utf-8")
104
+ if method in ("POST", "PATCH", "PUT"):
105
+ h["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
106
+ h.update(headers or {})
107
+ return h, body
108
+
109
+ def _handle(self, r: httpx.Response, binary: bool) -> Tuple[bool, Any, Optional[PandafileError], float]:
110
+ h = {k.lower(): v for k, v in r.headers.items()}
111
+ self.last_response = {"status": r.status_code, "headers": h, "request_id": h.get("x-request-id")}
112
+ if r.status_code < 300:
113
+ return True, (r.content if binary else _parse(r)), None, 0.0
114
+ err = error_from_response(r.status_code, _parse(r), h)
115
+ retryable = r.status_code in RETRY_STATUS or err.code == "idempotency_key_in_use"
116
+ ra = _retry_after(h)
117
+ return False, retryable, err, (min(ra, 60.0) if ra is not None else -1.0)
118
+
119
+ def _connection_error(self, e: Exception) -> APIConnectionError:
120
+ timeout = isinstance(e, httpx.TimeoutException)
121
+ return APIConnectionError(f"Request timed out" if timeout else f"Could not reach {self.base_url}: {e}",
122
+ type="connection_error", code="timeout" if timeout else "connection_failed")
123
+
124
+
125
+ class Pandafile(_Base):
126
+ """The sync client::
127
+
128
+ from pandafile import Pandafile
129
+ pf = Pandafile("pf_live_...") # or PANDAFILE_API_KEY
130
+ result = pf.transfers.send(["film.mov", "stills/"], recipients=["client@example.com"])
131
+ print(result.url)
132
+ """
133
+
134
+ def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, api_version: Optional[str] = None,
135
+ max_retries: int = 3, timeout: float = 60.0, http_client: Optional[httpx.Client] = None, app_info: Optional[str] = None) -> None:
136
+ super().__init__(api_key, base_url, api_version, max_retries, timeout, app_info)
137
+ self._own_http = http_client is None
138
+ self._http = http_client or httpx.Client(timeout=httpx.Timeout(timeout, connect=min(timeout, 30.0)), follow_redirects=False)
139
+
140
+ def request(self, method: str, path: str, *, query: Optional[Mapping[str, Any]] = None, json: Any = None, content: Optional[bytes] = None,
141
+ content_type: Optional[str] = None, binary: bool = False, idempotency_key: Optional[str] = None,
142
+ headers: Optional[Mapping[str, str]] = None, max_retries: Optional[int] = None, timeout: Optional[float] = None) -> Any:
143
+ """Any API call: ``pf.request("GET", "/me")``. POST/PATCH/PUT get an Idempotency-Key reused across retries."""
144
+ method = method.upper()
145
+ h, body = self._prepare(method, json, content, content_type, binary, idempotency_key, headers)
146
+ url = self._url(path, query)
147
+ retries = self.max_retries if max_retries is None else max_retries
148
+ attempt = 0
149
+ while True:
150
+ try:
151
+ r = self._http.request(method, url, headers=h, content=body, timeout=timeout if timeout is not None else self.timeout)
152
+ except httpx.TransportError as e:
153
+ if attempt < retries:
154
+ time.sleep(_backoff(attempt))
155
+ attempt += 1
156
+ continue
157
+ raise self._connection_error(e) from e
158
+ ok, value, err, wait = self._handle(r, binary)
159
+ if ok:
160
+ return value
161
+ assert err is not None
162
+ if value and attempt < retries:
163
+ time.sleep(wait if wait >= 0 else _backoff(attempt))
164
+ attempt += 1
165
+ continue
166
+ raise err
167
+
168
+ def list(self, path: str, params: Optional[Mapping[str, Any]] = None) -> SyncPager:
169
+ p = dict(params or {})
170
+ start = p.pop("starting_after", None)
171
+ return SyncPager(lambda after: self.request("GET", path, query={**p, "starting_after": after}), start)
172
+
173
+ def _send(self, files: Any, **options: Any) -> Any:
174
+ return send_sync(self, files, **options)
175
+
176
+ def close(self) -> None:
177
+ if self._own_http:
178
+ self._http.close()
179
+
180
+ def __enter__(self) -> "Pandafile":
181
+ return self
182
+
183
+ def __exit__(self, *exc: Any) -> None:
184
+ self.close()
185
+
186
+
187
+ class AsyncPandafile(_Base):
188
+ """The async client (same resources; methods are awaitable, lists support ``async for``)::
189
+
190
+ async with AsyncPandafile() as pf:
191
+ result = await pf.transfers.send(["film.mov"])
192
+ """
193
+
194
+ def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, api_version: Optional[str] = None,
195
+ max_retries: int = 3, timeout: float = 60.0, http_client: Optional[httpx.AsyncClient] = None, app_info: Optional[str] = None) -> None:
196
+ super().__init__(api_key, base_url, api_version, max_retries, timeout, app_info)
197
+ self._own_http = http_client is None
198
+ self._http = http_client or httpx.AsyncClient(timeout=httpx.Timeout(timeout, connect=min(timeout, 30.0)), follow_redirects=False)
199
+
200
+ async def request(self, method: str, path: str, *, query: Optional[Mapping[str, Any]] = None, json: Any = None, content: Optional[bytes] = None,
201
+ content_type: Optional[str] = None, binary: bool = False, idempotency_key: Optional[str] = None,
202
+ headers: Optional[Mapping[str, str]] = None, max_retries: Optional[int] = None, timeout: Optional[float] = None) -> Any:
203
+ method = method.upper()
204
+ h, body = self._prepare(method, json, content, content_type, binary, idempotency_key, headers)
205
+ url = self._url(path, query)
206
+ retries = self.max_retries if max_retries is None else max_retries
207
+ attempt = 0
208
+ while True:
209
+ try:
210
+ r = await self._http.request(method, url, headers=h, content=body, timeout=timeout if timeout is not None else self.timeout)
211
+ except httpx.TransportError as e:
212
+ if attempt < retries:
213
+ await asyncio.sleep(_backoff(attempt))
214
+ attempt += 1
215
+ continue
216
+ raise self._connection_error(e) from e
217
+ ok, value, err, wait = self._handle(r, binary)
218
+ if ok:
219
+ return value
220
+ assert err is not None
221
+ if value and attempt < retries:
222
+ await asyncio.sleep(wait if wait >= 0 else _backoff(attempt))
223
+ attempt += 1
224
+ continue
225
+ raise err
226
+
227
+ def list(self, path: str, params: Optional[Mapping[str, Any]] = None) -> AsyncPager:
228
+ p = dict(params or {})
229
+ start = p.pop("starting_after", None)
230
+ return AsyncPager(lambda after: self.request("GET", path, query={**p, "starting_after": after}), start)
231
+
232
+ async def _send(self, files: Any, **options: Any) -> Any:
233
+ return await send_async(self, files, **options)
234
+
235
+ async def aclose(self) -> None:
236
+ if self._own_http:
237
+ await self._http.aclose()
238
+
239
+ async def __aenter__(self) -> "AsyncPandafile":
240
+ return self
241
+
242
+ async def __aexit__(self, *exc: Any) -> None:
243
+ await self.aclose()
pandafile/_errors.py ADDED
@@ -0,0 +1,115 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Dict, Mapping, Optional
4
+
5
+
6
+ class PandafileError(Exception):
7
+ """Every error the SDK raises.
8
+
9
+ ``type`` is the category, ``code`` the stable machine-readable reason (resource_missing, parameter_invalid,
10
+ plan_required, rate_limited, ...), ``status`` the HTTP status (0 for network errors) and ``request_id`` the
11
+ X-Request-Id to quote to support.
12
+ """
13
+
14
+ def __init__(
15
+ self,
16
+ message: str,
17
+ *,
18
+ type: str = "api_error",
19
+ code: str = "unknown",
20
+ status: int = 0,
21
+ request_id: Optional[str] = None,
22
+ param: Optional[str] = None,
23
+ headers: Optional[Mapping[str, str]] = None,
24
+ raw: Any = None,
25
+ ) -> None:
26
+ super().__init__(message)
27
+ self.message = message
28
+ self.type = type
29
+ self.code = code
30
+ self.status = status
31
+ self.request_id = request_id
32
+ self.param = param
33
+ self.headers: Dict[str, str] = {k.lower(): v for k, v in (headers or {}).items()}
34
+ self.raw = raw
35
+
36
+ def __repr__(self) -> str:
37
+ return f"{self.__class__.__name__}(status={self.status}, code={self.code!r}, message={self.message!r}, request_id={self.request_id!r})"
38
+
39
+
40
+ class InvalidRequestError(PandafileError):
41
+ """400/404/409/410/413: a missing or invalid parameter, an unknown id, or a state that does not allow it."""
42
+
43
+
44
+ class NotFoundError(InvalidRequestError):
45
+ """404: the id does not exist (or belongs to another account / the other mode)."""
46
+
47
+
48
+ class AuthenticationError(PandafileError):
49
+ """401: no key, or the key is unknown, revoked or malformed."""
50
+
51
+
52
+ class PermissionDeniedError(PandafileError):
53
+ """403: plan, key scope, test mode or team role does not allow this."""
54
+
55
+
56
+ class IdempotencyError(PandafileError):
57
+ """409: the Idempotency-Key was used with a different request, or that request is still running."""
58
+
59
+
60
+ class RateLimitError(PandafileError):
61
+ """429: too many requests for this key."""
62
+
63
+ @property
64
+ def retry_after(self) -> Optional[float]:
65
+ try:
66
+ return float(self.headers.get("retry-after", ""))
67
+ except ValueError:
68
+ return None
69
+
70
+
71
+ class APIError(PandafileError):
72
+ """5xx: something went wrong on Pandafile's side. Safe to retry with the same Idempotency-Key."""
73
+
74
+
75
+ class APIConnectionError(PandafileError):
76
+ """The request never got an answer (DNS, connection reset, timeout)."""
77
+
78
+
79
+ class SignatureVerificationError(PandafileError):
80
+ """A webhook signature did not verify (wrong secret, modified body or too old)."""
81
+
82
+
83
+ class UploadError(PandafileError):
84
+ """A tus upload failed for good (after the retries)."""
85
+
86
+
87
+ def error_from_response(status: int, body: Any, headers: Mapping[str, str]) -> PandafileError:
88
+ h = {k.lower(): v for k, v in headers.items()}
89
+ request_id = h.get("x-request-id")
90
+ etype = code = message = param = None
91
+ e = body.get("error") if isinstance(body, dict) else None
92
+ if isinstance(e, dict):
93
+ etype = e.get("type") if isinstance(e.get("type"), str) else None
94
+ code = e.get("code") if isinstance(e.get("code"), str) else None
95
+ message = e.get("message") if isinstance(e.get("message"), str) else None
96
+ param = e.get("param") if isinstance(e.get("param"), str) else None
97
+ elif isinstance(e, str):
98
+ message = e # API version 2025-06-01
99
+ if not etype:
100
+ etype = ("authentication_error" if status == 401 else "permission_error" if status == 403 else "rate_limit_error" if status == 429
101
+ else "api_error" if status >= 500 else "invalid_request_error")
102
+ if not code:
103
+ code = "resource_missing" if status == 404 else "rate_limited" if status == 429 else f"http_{status}"
104
+ message = message or f"HTTP {status}"
105
+ kw = dict(type=etype, code=code, status=status, request_id=request_id, param=param, headers=h, raw=body)
106
+ cls = {
107
+ "authentication_error": AuthenticationError,
108
+ "permission_error": PermissionDeniedError,
109
+ "idempotency_error": IdempotencyError,
110
+ "rate_limit_error": RateLimitError,
111
+ "api_error": APIError,
112
+ }.get(etype)
113
+ if cls is None:
114
+ cls = NotFoundError if status == 404 else InvalidRequestError
115
+ return cls(message, **kw)
pandafile/_files.py ADDED
@@ -0,0 +1,159 @@
1
+ """Turns what people pass to ``transfers.send()`` into named upload sources.
2
+
3
+ Accepted: a path (str / os.PathLike; folders keep their structure, like dropping a folder on the website),
4
+ ``(name, bytes)``, ``{"name": ..., "data": bytes | str}``, ``{"path": ..., "name": optional}``, or a binary file object
5
+ with a ``name`` (seekable).
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import mimetypes
10
+ import os
11
+ import threading
12
+ from typing import Any, BinaryIO, List, Optional, Sequence, Union
13
+
14
+ from ._errors import PandafileError
15
+
16
+ SKIP = {".DS_Store", "Thumbs.db", "desktop.ini"}
17
+
18
+ FileInput = Union[str, "os.PathLike[str]", bytes, tuple, dict, BinaryIO]
19
+
20
+
21
+ def mime_of(name: str) -> str:
22
+ return mimetypes.guess_type(name)[0] or "application/octet-stream"
23
+
24
+
25
+ class Source:
26
+ size: int
27
+
28
+ def read(self, start: int, end: int) -> bytes: # pragma: no cover - interface
29
+ raise NotImplementedError
30
+
31
+ def close(self) -> None:
32
+ pass
33
+
34
+
35
+ class BytesSource(Source):
36
+ def __init__(self, data: bytes) -> None:
37
+ self._data = memoryview(data)
38
+ self.size = len(data)
39
+
40
+ def read(self, start: int, end: int) -> bytes:
41
+ return bytes(self._data[start:end])
42
+
43
+
44
+ class PathSource(Source):
45
+ def __init__(self, path: str, size: int) -> None:
46
+ self.path = path
47
+ self.size = size
48
+ self._fh: Optional[BinaryIO] = None
49
+ self._lock = threading.Lock()
50
+
51
+ def read(self, start: int, end: int) -> bytes:
52
+ with self._lock:
53
+ if self._fh is None:
54
+ self._fh = open(self.path, "rb")
55
+ self._fh.seek(start)
56
+ return self._fh.read(end - start)
57
+
58
+ def close(self) -> None:
59
+ with self._lock:
60
+ if self._fh is not None:
61
+ self._fh.close()
62
+ self._fh = None
63
+
64
+
65
+ class FileObjSource(Source):
66
+ def __init__(self, fh: BinaryIO) -> None:
67
+ self._fh = fh
68
+ self._lock = threading.Lock()
69
+ pos = fh.tell()
70
+ fh.seek(0, os.SEEK_END)
71
+ self.size = fh.tell() - pos
72
+ self._base = pos
73
+ fh.seek(pos)
74
+
75
+ def read(self, start: int, end: int) -> bytes:
76
+ with self._lock:
77
+ self._fh.seek(self._base + start)
78
+ return self._fh.read(end - start)
79
+
80
+
81
+ class PreparedFile:
82
+ def __init__(self, name: str, size: int, type: str, source: Source, fingerprint: str) -> None:
83
+ self.name = name
84
+ self.size = size
85
+ self.type = type
86
+ self.source = source
87
+ self.fingerprint = fingerprint
88
+
89
+ def __repr__(self) -> str:
90
+ return f"PreparedFile({self.name!r}, {self.size})"
91
+
92
+
93
+ def _from_path(p: Any, name: Optional[str], ftype: Optional[str], out: List[PreparedFile]) -> None:
94
+ abs_path = os.path.abspath(os.fspath(p))
95
+ if not os.path.exists(abs_path):
96
+ raise PandafileError(f"No such file or folder: {p}", code="file_not_found")
97
+ if os.path.isdir(abs_path):
98
+ root = name or os.path.basename(abs_path.rstrip(os.sep))
99
+ for dirpath, dirnames, filenames in os.walk(abs_path):
100
+ dirnames.sort()
101
+ rel_dir = os.path.relpath(dirpath, abs_path)
102
+ for fn in sorted(filenames):
103
+ if fn in SKIP:
104
+ continue
105
+ full = os.path.join(dirpath, fn)
106
+ if not os.path.isfile(full):
107
+ continue
108
+ st = os.stat(full)
109
+ rel = fn if rel_dir == "." else f"{rel_dir.replace(os.sep, '/')}/{fn}"
110
+ out.append(PreparedFile(f"{root}/{rel}", st.st_size, mime_of(fn), PathSource(full, st.st_size), f"{full}:{st.st_size}:{st.st_mtime}"))
111
+ return
112
+ st = os.stat(abs_path)
113
+ n = name or os.path.basename(abs_path)
114
+ out.append(PreparedFile(n, st.st_size, ftype or mime_of(n), PathSource(abs_path, st.st_size), f"{abs_path}:{st.st_size}:{st.st_mtime}"))
115
+
116
+
117
+ def prepare_files(files: Union[FileInput, Sequence[FileInput]]) -> List[PreparedFile]:
118
+ items: Sequence[Any]
119
+ if isinstance(files, (list, tuple)) and not (isinstance(files, tuple) and len(files) == 2 and isinstance(files[0], str) and isinstance(files[1], (bytes, bytearray, str))):
120
+ items = files
121
+ else:
122
+ items = [files]
123
+ out: List[PreparedFile] = []
124
+ for item in items:
125
+ if isinstance(item, (str, os.PathLike)):
126
+ _from_path(item, None, None, out)
127
+ elif isinstance(item, tuple) and len(item) == 2:
128
+ name, data = item
129
+ b = data.encode("utf-8") if isinstance(data, str) else bytes(data)
130
+ out.append(PreparedFile(str(name).lstrip("/"), len(b), mime_of(name), BytesSource(b), f"{name}:{len(b)}"))
131
+ elif isinstance(item, dict) and "path" in item:
132
+ _from_path(item["path"], item.get("name"), item.get("type"), out)
133
+ elif isinstance(item, dict) and "data" in item:
134
+ name = str(item.get("name") or "file").lstrip("/")
135
+ data = item["data"]
136
+ b = data.encode("utf-8") if isinstance(data, str) else bytes(data)
137
+ out.append(PreparedFile(name, len(b), item.get("type") or mime_of(name), BytesSource(b), f"{name}:{len(b)}"))
138
+ elif isinstance(item, (bytes, bytearray)):
139
+ raise PandafileError("Raw bytes need a name: pass (name, data) or {'name': ..., 'data': ...}.", code="parameter_invalid", param="files")
140
+ elif hasattr(item, "read") and hasattr(item, "seek"):
141
+ name = os.path.basename(str(getattr(item, "name", "file")))
142
+ src = FileObjSource(item)
143
+ out.append(PreparedFile(name, src.size, mime_of(name), src, f"{name}:{src.size}"))
144
+ else:
145
+ raise PandafileError("Each file must be a path, (name, bytes), {'name', 'data'}, {'path'} or a binary file object.", code="parameter_invalid", param="files")
146
+ if not out:
147
+ raise PandafileError("No files to send (empty folder?).", code="parameter_missing", param="files")
148
+ # Names are unique per transfer: "a.txt", "a (1).txt".
149
+ seen = set()
150
+ for f in out:
151
+ n, i = f.name, 1
152
+ while n in seen:
153
+ slash = f.name.rfind("/")
154
+ dot = f.name.rfind(".")
155
+ n = f"{f.name[:dot]} ({i}){f.name[dot:]}" if dot > slash + 1 else f"{f.name} ({i})"
156
+ i += 1
157
+ seen.add(n)
158
+ f.name = n
159
+ return out
@@ -0,0 +1,128 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Generator, Generic, Iterator, List, Optional, TypeVar
4
+
5
+ T = TypeVar("T")
6
+
7
+ FetchPage = Callable[[Optional[str]], Any] # starting_after -> dict (sync) or awaitable dict (async)
8
+
9
+
10
+ class Page(Generic[T]):
11
+ """One page of a list: ``data``, ``has_more``, ``next_cursor``."""
12
+
13
+ def __init__(self, raw: Dict[str, Any], fetch: FetchPage) -> None:
14
+ self.raw = raw or {}
15
+ self.data: List[T] = list(self.raw.get("data") or [])
16
+ self.has_more: bool = bool(self.raw.get("has_more"))
17
+ self.next_cursor: Optional[str] = self.raw.get("next_cursor")
18
+ self._fetch = fetch
19
+
20
+ def has_next_page(self) -> bool:
21
+ return self.has_more and bool(self.next_cursor)
22
+
23
+ def __iter__(self) -> Iterator[T]:
24
+ return iter(self.data)
25
+
26
+ def __len__(self) -> int:
27
+ return len(self.data)
28
+
29
+ def __repr__(self) -> str:
30
+ return f"Page(items={len(self.data)}, has_more={self.has_more}, next_cursor={self.next_cursor!r})"
31
+
32
+
33
+ class SyncPage(Page[T]):
34
+ def next_page(self) -> Optional["SyncPage[T]"]:
35
+ if not self.has_next_page():
36
+ return None
37
+ return SyncPage(self._fetch(self.next_cursor), self._fetch)
38
+
39
+
40
+ class AsyncPage(Page[T]):
41
+ async def next_page(self) -> Optional["AsyncPage[T]"]:
42
+ if not self.has_next_page():
43
+ return None
44
+ return AsyncPage(await self._fetch(self.next_cursor), self._fetch)
45
+
46
+
47
+ class SyncPager(Generic[T]):
48
+ """What list methods return on the sync client. Iterate it for every item across pages, or call ``.page()``
49
+ for the first page only::
50
+
51
+ for t in client.transfers.list():
52
+ print(t["id"])
53
+ page = client.transfers.list(limit=50).page()
54
+ """
55
+
56
+ def __init__(self, fetch: FetchPage, starting_after: Optional[str] = None) -> None:
57
+ self._fetch = fetch
58
+ self._start = starting_after
59
+ self._first: Optional[SyncPage[T]] = None
60
+
61
+ def page(self) -> SyncPage[T]:
62
+ if self._first is None:
63
+ self._first = SyncPage(self._fetch(self._start), self._fetch)
64
+ return self._first
65
+
66
+ # first-page shortcuts
67
+ @property
68
+ def data(self) -> List[T]:
69
+ return self.page().data
70
+
71
+ @property
72
+ def has_more(self) -> bool:
73
+ return self.page().has_more
74
+
75
+ @property
76
+ def next_cursor(self) -> Optional[str]:
77
+ return self.page().next_cursor
78
+
79
+ def __iter__(self) -> Iterator[T]:
80
+ p: Optional[SyncPage[T]] = self.page()
81
+ while p is not None:
82
+ yield from p.data
83
+ p = p.next_page()
84
+
85
+ def to_list(self, max_items: Optional[int] = None) -> List[T]:
86
+ out: List[T] = []
87
+ for item in self:
88
+ if max_items is not None and len(out) >= max_items:
89
+ break
90
+ out.append(item)
91
+ return out
92
+
93
+
94
+ class AsyncPager(Generic[T]):
95
+ """What list methods return on the async client. ``async for`` walks every item; ``await`` gives the first page::
96
+
97
+ async for t in client.transfers.list():
98
+ ...
99
+ page = await client.transfers.list(limit=50)
100
+ """
101
+
102
+ def __init__(self, fetch: Callable[[Optional[str]], Awaitable[Dict[str, Any]]], starting_after: Optional[str] = None) -> None:
103
+ self._fetch = fetch
104
+ self._start = starting_after
105
+ self._first: Optional[AsyncPage[T]] = None
106
+
107
+ async def page(self) -> AsyncPage[T]:
108
+ if self._first is None:
109
+ self._first = AsyncPage(await self._fetch(self._start), self._fetch)
110
+ return self._first
111
+
112
+ def __await__(self) -> Generator[Any, None, AsyncPage[T]]:
113
+ return self.page().__await__()
114
+
115
+ async def __aiter__(self) -> AsyncIterator[T]:
116
+ p: Optional[AsyncPage[T]] = await self.page()
117
+ while p is not None:
118
+ for item in p.data:
119
+ yield item
120
+ p = await p.next_page()
121
+
122
+ async def to_list(self, max_items: Optional[int] = None) -> List[T]:
123
+ out: List[T] = []
124
+ async for item in self:
125
+ if max_items is not None and len(out) >= max_items:
126
+ break
127
+ out.append(item)
128
+ return out