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 +37 -0
- pandafile/_client.py +243 -0
- pandafile/_errors.py +115 -0
- pandafile/_files.py +159 -0
- pandafile/_pagination.py +128 -0
- pandafile/_resources.py +288 -0
- pandafile/_send.py +284 -0
- pandafile/_tus.py +290 -0
- pandafile/_version.py +1 -0
- pandafile/py.typed +0 -0
- pandafile/types.py +753 -0
- pandafile/webhooks.py +69 -0
- pandafile-0.2.0.dist-info/METADATA +169 -0
- pandafile-0.2.0.dist-info/RECORD +16 -0
- pandafile-0.2.0.dist-info/WHEEL +4 -0
- pandafile-0.2.0.dist-info/licenses/LICENSE +21 -0
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
|
pandafile/_pagination.py
ADDED
|
@@ -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
|