transynq 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.
- transynq/__init__.py +57 -0
- transynq/_client.py +282 -0
- transynq/_core/__init__.py +1 -0
- transynq/_core/credentials.py +264 -0
- transynq/_core/errors.py +158 -0
- transynq/_core/http.py +502 -0
- transynq/_core/jsonenc.py +102 -0
- transynq/_core/models.py +36 -0
- transynq/_core/paging.py +40 -0
- transynq/_core/types.py +205 -0
- transynq/_generated/__init__.py +3 -0
- transynq/_generated/client_services.py +286 -0
- transynq/_generated/models.py +6996 -0
- transynq/_generated/services/__init__.py +3 -0
- transynq/_generated/services/account_invoices.py +80 -0
- transynq/_generated/services/accounting_systems.py +222 -0
- transynq/_generated/services/admin.py +140 -0
- transynq/_generated/services/aged_debtors.py +74 -0
- transynq/_generated/services/ai.py +256 -0
- transynq/_generated/services/authentication.py +129 -0
- transynq/_generated/services/background_jobs.py +61 -0
- transynq/_generated/services/bookings.py +265 -0
- transynq/_generated/services/check_lists.py +75 -0
- transynq/_generated/services/company.py +86 -0
- transynq/_generated/services/company_settings.py +121 -0
- transynq/_generated/services/compliance.py +132 -0
- transynq/_generated/services/costing.py +142 -0
- transynq/_generated/services/custom_pages.py +84 -0
- transynq/_generated/services/customer_statements.py +100 -0
- transynq/_generated/services/customers.py +504 -0
- transynq/_generated/services/dashboard.py +72 -0
- transynq/_generated/services/delivery_reports.py +39 -0
- transynq/_generated/services/dispatch.py +543 -0
- transynq/_generated/services/documents.py +75 -0
- transynq/_generated/services/driver_app.py +461 -0
- transynq/_generated/services/drivers.py +134 -0
- transynq/_generated/services/fleet.py +142 -0
- transynq/_generated/services/geography.py +484 -0
- transynq/_generated/services/grids.py +208 -0
- transynq/_generated/services/imports.py +248 -0
- transynq/_generated/services/integrations.py +164 -0
- transynq/_generated/services/interest.py +76 -0
- transynq/_generated/services/invoicing.py +497 -0
- transynq/_generated/services/jobs.py +1200 -0
- transynq/_generated/services/leg_splits.py +63 -0
- transynq/_generated/services/leg_templates.py +87 -0
- transynq/_generated/services/long_operations.py +52 -0
- transynq/_generated/services/lookups.py +109 -0
- transynq/_generated/services/mail.py +37 -0
- transynq/_generated/services/meta.py +36 -0
- transynq/_generated/services/notifications.py +163 -0
- transynq/_generated/services/pallets.py +102 -0
- transynq/_generated/services/photo_galleries.py +116 -0
- transynq/_generated/services/planning.py +101 -0
- transynq/_generated/services/pricing.py +353 -0
- transynq/_generated/services/products.py +138 -0
- transynq/_generated/services/reference_data.py +252 -0
- transynq/_generated/services/report_setup.py +94 -0
- transynq/_generated/services/sales_ledger.py +327 -0
- transynq/_generated/services/settings.py +286 -0
- transynq/_generated/services/spa.py +342 -0
- transynq/_generated/services/subcontractors.py +222 -0
- transynq/_generated/services/tracking.py +87 -0
- transynq/_generated/services/users.py +252 -0
- transynq/_generated/services/whats_app.py +211 -0
- transynq/_generated/services/yard.py +182 -0
- transynq/py.typed +0 -0
- transynq-1.0.0.dist-info/METADATA +146 -0
- transynq-1.0.0.dist-info/RECORD +71 -0
- transynq-1.0.0.dist-info/WHEEL +4 -0
- transynq-1.0.0.dist-info/licenses/LICENSE +21 -0
transynq/__init__.py
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Official Python client for the Transynq TMS API."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from ._client import (
|
|
5
|
+
FAILED,
|
|
6
|
+
QUEUED,
|
|
7
|
+
RUNNING,
|
|
8
|
+
SUCCEEDED,
|
|
9
|
+
AsyncLongOperationPoller,
|
|
10
|
+
AsyncTransynqClient,
|
|
11
|
+
LongOperationPoller,
|
|
12
|
+
TransynqClient,
|
|
13
|
+
new_id,
|
|
14
|
+
new_idempotency_key,
|
|
15
|
+
read_modify_write,
|
|
16
|
+
read_modify_write_async,
|
|
17
|
+
)
|
|
18
|
+
from ._core.credentials import (
|
|
19
|
+
ApiKeyCredential,
|
|
20
|
+
Credential,
|
|
21
|
+
DriverLoginCredential,
|
|
22
|
+
DriverTokenCredential,
|
|
23
|
+
SessionCredential,
|
|
24
|
+
)
|
|
25
|
+
from ._core.errors import (
|
|
26
|
+
ApiError,
|
|
27
|
+
AuthenticationError,
|
|
28
|
+
BusinessRuleError,
|
|
29
|
+
ConflictError,
|
|
30
|
+
ConnectionError,
|
|
31
|
+
LongOperationFailedError,
|
|
32
|
+
NotFoundError,
|
|
33
|
+
PermissionDeniedError,
|
|
34
|
+
RateLimitError,
|
|
35
|
+
ServerError,
|
|
36
|
+
StaleVersionError,
|
|
37
|
+
TimeoutError,
|
|
38
|
+
TransynqError,
|
|
39
|
+
ValidationError,
|
|
40
|
+
)
|
|
41
|
+
from ._core.http import SDK_VERSION, ClientOptions
|
|
42
|
+
from ._core.models import PagedResponse, TransynqModel
|
|
43
|
+
from ._core.types import ApiResponse, FileDownload, FileUpload, RequestOptions, ResponseBody
|
|
44
|
+
from ._generated import models
|
|
45
|
+
from ._generated.client_services import API_VERSION, OPERATION_COUNT, SPEC_SHA256
|
|
46
|
+
|
|
47
|
+
__version__ = SDK_VERSION
|
|
48
|
+
|
|
49
|
+
__all__ = [
|
|
50
|
+
"API_VERSION", "FAILED", "OPERATION_COUNT", "QUEUED", "RUNNING", "SDK_VERSION", "SPEC_SHA256", "SUCCEEDED",
|
|
51
|
+
"ApiError", "ApiKeyCredential", "ApiResponse", "AsyncLongOperationPoller", "AsyncTransynqClient", "AuthenticationError",
|
|
52
|
+
"BusinessRuleError", "ClientOptions", "ConflictError", "ConnectionError", "Credential", "DriverLoginCredential",
|
|
53
|
+
"DriverTokenCredential", "FileDownload", "FileUpload", "LongOperationFailedError", "LongOperationPoller", "NotFoundError",
|
|
54
|
+
"PagedResponse", "PermissionDeniedError", "RateLimitError", "RequestOptions", "ResponseBody", "ServerError",
|
|
55
|
+
"SessionCredential", "StaleVersionError", "TimeoutError", "TransynqClient", "TransynqError", "TransynqModel",
|
|
56
|
+
"ValidationError", "models", "new_id", "new_idempotency_key", "read_modify_write", "read_modify_write_async",
|
|
57
|
+
]
|
transynq/_client.py
ADDED
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
"""The entry clients."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import uuid
|
|
5
|
+
from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Iterator, Optional, TypeVar, Union
|
|
6
|
+
|
|
7
|
+
import httpx
|
|
8
|
+
|
|
9
|
+
from ._core.credentials import Credential, DriverLoginCredential, SessionCredential
|
|
10
|
+
from ._core.errors import LongOperationFailedError, StaleVersionError
|
|
11
|
+
from ._core.http import AsyncTransport, ClientOptions, SyncTransport
|
|
12
|
+
from ._core.types import ApiResponse, FileDownload, RequestOptions, ResponseBody
|
|
13
|
+
from ._generated import models as m
|
|
14
|
+
from ._generated.client_services import AsyncServices, SyncServices
|
|
15
|
+
|
|
16
|
+
T = TypeVar("T")
|
|
17
|
+
R = TypeVar("R")
|
|
18
|
+
|
|
19
|
+
QUEUED, RUNNING, SUCCEEDED, FAILED = "Queued", "Running", "Succeeded", "Failed"
|
|
20
|
+
"""Long operation states (an open set: compare as strings)."""
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _options(
|
|
24
|
+
base_url: str, credential: Optional[Credential], timeout: float, max_retries: int, user_agent_suffix: Optional[str], **extra: Any
|
|
25
|
+
) -> ClientOptions:
|
|
26
|
+
return ClientOptions(base_url=base_url, credential=credential, timeout=timeout, max_retries=max_retries,
|
|
27
|
+
user_agent_suffix=user_agent_suffix, **extra)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def operation_id_from(response: "ApiResponse[ResponseBody]") -> uuid.UUID:
|
|
31
|
+
"""The long operation a 202 answer started (its ``Location``, else its body's ``id``)."""
|
|
32
|
+
location = response.location
|
|
33
|
+
if location and "/long-operations/" in location.lower():
|
|
34
|
+
try:
|
|
35
|
+
return uuid.UUID(location.split("?", 1)[0].rstrip("/").rsplit("/", 1)[-1])
|
|
36
|
+
except ValueError:
|
|
37
|
+
pass
|
|
38
|
+
body = response.data.json() if isinstance(response.data, ResponseBody) else None
|
|
39
|
+
if isinstance(body, dict) and isinstance(body.get("id"), str):
|
|
40
|
+
return uuid.UUID(body["id"])
|
|
41
|
+
raise ValueError("the response is not a long-operation answer (no Location and no id)")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _check(op: m.LongOperationResponse, operation_id: uuid.UUID) -> bool:
|
|
45
|
+
if op.status.lower() == SUCCEEDED.lower():
|
|
46
|
+
return True
|
|
47
|
+
if op.status.lower() == FAILED.lower():
|
|
48
|
+
raise LongOperationFailedError(f"Long operation {operation_id} ({op.kind}) failed: {op.error or 'no reason given'}.", op)
|
|
49
|
+
return False
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class LongOperationPoller:
|
|
53
|
+
"""Follows a long-running operation (``GET /api/v1/long-operations/{id}``) to its end."""
|
|
54
|
+
|
|
55
|
+
def __init__(self, client: "TransynqClient", operation_id: uuid.UUID) -> None:
|
|
56
|
+
self._client = client
|
|
57
|
+
self.id = operation_id
|
|
58
|
+
self.last: Optional[m.LongOperationResponse] = None
|
|
59
|
+
|
|
60
|
+
def status(self) -> m.LongOperationResponse:
|
|
61
|
+
self.last = self._client.long_operations.get_long_operation(self.id).data
|
|
62
|
+
return self.last
|
|
63
|
+
|
|
64
|
+
def wait(self, poll_interval: float = 2.0, timeout: float = 1800.0,
|
|
65
|
+
on_progress: Optional[Callable[[m.LongOperationResponse], None]] = None) -> m.LongOperationResponse:
|
|
66
|
+
"""Polls until ``Succeeded`` (returns it) or ``Failed`` (raises :class:`LongOperationFailedError`)."""
|
|
67
|
+
waited = 0.0
|
|
68
|
+
while True:
|
|
69
|
+
op = self.status()
|
|
70
|
+
if on_progress:
|
|
71
|
+
on_progress(op)
|
|
72
|
+
if _check(op, self.id):
|
|
73
|
+
return op
|
|
74
|
+
if waited >= timeout:
|
|
75
|
+
raise TimeoutError(f"long operation {self.id} did not finish within {timeout} s")
|
|
76
|
+
self._client._transport._sleep(poll_interval)
|
|
77
|
+
waited += poll_interval
|
|
78
|
+
|
|
79
|
+
def download_result(self) -> FileDownload:
|
|
80
|
+
"""The operation's result file (a workbook or PDF). Close it after reading."""
|
|
81
|
+
return self._client.long_operations.get_long_operation_file(self.id).data
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class AsyncLongOperationPoller:
|
|
85
|
+
"""Async version of :class:`LongOperationPoller`."""
|
|
86
|
+
|
|
87
|
+
def __init__(self, client: "AsyncTransynqClient", operation_id: uuid.UUID) -> None:
|
|
88
|
+
self._client = client
|
|
89
|
+
self.id = operation_id
|
|
90
|
+
self.last: Optional[m.LongOperationResponse] = None
|
|
91
|
+
|
|
92
|
+
async def status(self) -> m.LongOperationResponse:
|
|
93
|
+
self.last = (await self._client.long_operations.get_long_operation(self.id)).data
|
|
94
|
+
return self.last
|
|
95
|
+
|
|
96
|
+
async def wait(self, poll_interval: float = 2.0, timeout: float = 1800.0,
|
|
97
|
+
on_progress: Optional[Callable[[m.LongOperationResponse], None]] = None) -> m.LongOperationResponse:
|
|
98
|
+
waited = 0.0
|
|
99
|
+
while True:
|
|
100
|
+
op = await self.status()
|
|
101
|
+
if on_progress:
|
|
102
|
+
on_progress(op)
|
|
103
|
+
if _check(op, self.id):
|
|
104
|
+
return op
|
|
105
|
+
if waited >= timeout:
|
|
106
|
+
raise TimeoutError(f"long operation {self.id} did not finish within {timeout} s")
|
|
107
|
+
await self._client._transport._sleep(poll_interval)
|
|
108
|
+
waited += poll_interval
|
|
109
|
+
|
|
110
|
+
async def download_result(self) -> FileDownload:
|
|
111
|
+
return (await self._client.long_operations.get_long_operation_file(self.id)).data
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
class TransynqClient(SyncServices):
|
|
115
|
+
"""
|
|
116
|
+
The Transynq TMS API client (blocking). One attribute per API area (``client.jobs``, ``client.customers``...),
|
|
117
|
+
one method per operation. Thread-safe; create one and reuse it. Use as a context manager or call :meth:`close`.
|
|
118
|
+
"""
|
|
119
|
+
|
|
120
|
+
def __init__(
|
|
121
|
+
self,
|
|
122
|
+
base_url: str,
|
|
123
|
+
*,
|
|
124
|
+
credential: Optional[Credential] = None,
|
|
125
|
+
timeout: float = 60.0,
|
|
126
|
+
max_retries: int = 2,
|
|
127
|
+
user_agent_suffix: Optional[str] = None,
|
|
128
|
+
http_client: Optional[httpx.Client] = None,
|
|
129
|
+
**options: Any,
|
|
130
|
+
) -> None:
|
|
131
|
+
self.options = _options(base_url, credential, timeout, max_retries, user_agent_suffix, **options)
|
|
132
|
+
self._transport = SyncTransport(self.options, http_client)
|
|
133
|
+
self._init_services(self._transport)
|
|
134
|
+
|
|
135
|
+
@property
|
|
136
|
+
def user_agent(self) -> str:
|
|
137
|
+
return self._transport.user_agent
|
|
138
|
+
|
|
139
|
+
def poll_long_operation(self, accepted: Union["ApiResponse[ResponseBody]", uuid.UUID]) -> LongOperationPoller:
|
|
140
|
+
"""A poller for the long operation a 202 answer started, or for an operation id."""
|
|
141
|
+
return LongOperationPoller(self, accepted if isinstance(accepted, uuid.UUID) else operation_id_from(accepted))
|
|
142
|
+
|
|
143
|
+
def iter_grid_rows(self, grid_id: str, request: m.GridQueryRequest, options: Optional[RequestOptions] = None) -> Iterator[Dict[str, Any]]:
|
|
144
|
+
"""Every row of ``POST /api/v1/grids/{grid_id}/query``, page by page (page size default 500, the maximum)."""
|
|
145
|
+
page, size = request.page or 1, request.page_size or 500
|
|
146
|
+
while True:
|
|
147
|
+
data = self.grids.query_grid(grid_id, request.model_copy(update={"page": page, "page_size": size}), options=options).data
|
|
148
|
+
if not data.rows:
|
|
149
|
+
return
|
|
150
|
+
yield from data.rows
|
|
151
|
+
if data.page * data.page_size >= data.total:
|
|
152
|
+
return
|
|
153
|
+
page += 1
|
|
154
|
+
|
|
155
|
+
def sign_out(self) -> None:
|
|
156
|
+
"""Ends a session or driver sign-in on the server and forgets it locally."""
|
|
157
|
+
credential = self.options.credential
|
|
158
|
+
if isinstance(credential, SessionCredential) and credential.state is not None:
|
|
159
|
+
self.authentication.logout()
|
|
160
|
+
credential.reset()
|
|
161
|
+
elif isinstance(credential, DriverLoginCredential) and credential.state is not None:
|
|
162
|
+
self.driver_app.driver_logout()
|
|
163
|
+
credential.reset()
|
|
164
|
+
|
|
165
|
+
def close(self) -> None:
|
|
166
|
+
self._transport.close()
|
|
167
|
+
|
|
168
|
+
def __enter__(self) -> "TransynqClient":
|
|
169
|
+
return self
|
|
170
|
+
|
|
171
|
+
def __exit__(self, *exc: object) -> None:
|
|
172
|
+
self.close()
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
class AsyncTransynqClient(AsyncServices):
|
|
176
|
+
"""The Transynq TMS API client (asyncio). Same surface as :class:`TransynqClient`, every method awaitable."""
|
|
177
|
+
|
|
178
|
+
def __init__(
|
|
179
|
+
self,
|
|
180
|
+
base_url: str,
|
|
181
|
+
*,
|
|
182
|
+
credential: Optional[Credential] = None,
|
|
183
|
+
timeout: float = 60.0,
|
|
184
|
+
max_retries: int = 2,
|
|
185
|
+
user_agent_suffix: Optional[str] = None,
|
|
186
|
+
http_client: Optional[httpx.AsyncClient] = None,
|
|
187
|
+
**options: Any,
|
|
188
|
+
) -> None:
|
|
189
|
+
self.options = _options(base_url, credential, timeout, max_retries, user_agent_suffix, **options)
|
|
190
|
+
self._transport = AsyncTransport(self.options, http_client)
|
|
191
|
+
self._init_services(self._transport)
|
|
192
|
+
|
|
193
|
+
@property
|
|
194
|
+
def user_agent(self) -> str:
|
|
195
|
+
return self._transport.user_agent
|
|
196
|
+
|
|
197
|
+
def poll_long_operation(self, accepted: Union["ApiResponse[ResponseBody]", uuid.UUID]) -> AsyncLongOperationPoller:
|
|
198
|
+
return AsyncLongOperationPoller(self, accepted if isinstance(accepted, uuid.UUID) else operation_id_from(accepted))
|
|
199
|
+
|
|
200
|
+
async def iter_grid_rows(self, grid_id: str, request: m.GridQueryRequest,
|
|
201
|
+
options: Optional[RequestOptions] = None) -> AsyncIterator[Dict[str, Any]]:
|
|
202
|
+
page, size = request.page or 1, request.page_size or 500
|
|
203
|
+
while True:
|
|
204
|
+
data = (await self.grids.query_grid(grid_id, request.model_copy(update={"page": page, "page_size": size}), options=options)).data
|
|
205
|
+
if not data.rows:
|
|
206
|
+
return
|
|
207
|
+
for row in data.rows:
|
|
208
|
+
yield row
|
|
209
|
+
if data.page * data.page_size >= data.total:
|
|
210
|
+
return
|
|
211
|
+
page += 1
|
|
212
|
+
|
|
213
|
+
async def sign_out(self) -> None:
|
|
214
|
+
credential = self.options.credential
|
|
215
|
+
if isinstance(credential, SessionCredential) and credential.state is not None:
|
|
216
|
+
await self.authentication.logout()
|
|
217
|
+
credential.reset()
|
|
218
|
+
elif isinstance(credential, DriverLoginCredential) and credential.state is not None:
|
|
219
|
+
await self.driver_app.driver_logout()
|
|
220
|
+
credential.reset()
|
|
221
|
+
|
|
222
|
+
async def aclose(self) -> None:
|
|
223
|
+
await self._transport.aclose()
|
|
224
|
+
|
|
225
|
+
async def __aenter__(self) -> "AsyncTransynqClient":
|
|
226
|
+
return self
|
|
227
|
+
|
|
228
|
+
async def __aexit__(self, *exc: object) -> None:
|
|
229
|
+
await self.aclose()
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
def read_modify_write(
|
|
233
|
+
load: Callable[[], "ApiResponse[T]"],
|
|
234
|
+
save: Callable[[T, RequestOptions], "ApiResponse[R]"],
|
|
235
|
+
max_attempts: int = 3,
|
|
236
|
+
) -> "ApiResponse[R]":
|
|
237
|
+
"""Loads (with its ETag), saves with ``If-Match``; on :class:`StaleVersionError` reloads and repeats."""
|
|
238
|
+
if max_attempts < 1:
|
|
239
|
+
raise ValueError("max_attempts must be at least 1")
|
|
240
|
+
attempt = 0
|
|
241
|
+
while True:
|
|
242
|
+
attempt += 1
|
|
243
|
+
current = load()
|
|
244
|
+
if not current.etag:
|
|
245
|
+
raise ValueError("the loaded record has no ETag")
|
|
246
|
+
try:
|
|
247
|
+
return save(current.data, RequestOptions.with_if_match(current.etag))
|
|
248
|
+
except StaleVersionError:
|
|
249
|
+
if attempt >= max_attempts:
|
|
250
|
+
raise
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
async def read_modify_write_async(
|
|
254
|
+
load: Callable[[], Awaitable["ApiResponse[T]"]],
|
|
255
|
+
save: Callable[[T, RequestOptions], Awaitable["ApiResponse[R]"]],
|
|
256
|
+
max_attempts: int = 3,
|
|
257
|
+
) -> "ApiResponse[R]":
|
|
258
|
+
"""Async version of :func:`read_modify_write`."""
|
|
259
|
+
if max_attempts < 1:
|
|
260
|
+
raise ValueError("max_attempts must be at least 1")
|
|
261
|
+
attempt = 0
|
|
262
|
+
while True:
|
|
263
|
+
attempt += 1
|
|
264
|
+
current = await load()
|
|
265
|
+
if not current.etag:
|
|
266
|
+
raise ValueError("the loaded record has no ETag")
|
|
267
|
+
try:
|
|
268
|
+
return await save(current.data, RequestOptions.with_if_match(current.etag))
|
|
269
|
+
except StaleVersionError:
|
|
270
|
+
if attempt >= max_attempts:
|
|
271
|
+
raise
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
def new_id() -> uuid.UUID:
|
|
275
|
+
"""A new client id for an idempotent create (``POST`` with ``id`` in the body)."""
|
|
276
|
+
return uuid.uuid4()
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def new_idempotency_key() -> str:
|
|
280
|
+
return uuid.uuid4().hex
|
|
281
|
+
|
|
282
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Hand-written core of the Transynq SDK (transport, auth, errors, types)."""
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
"""Credentials matching the API's real mechanisms (docs/design.md section 3)."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import asyncio
|
|
5
|
+
import datetime as _dt
|
|
6
|
+
import json
|
|
7
|
+
import threading
|
|
8
|
+
from abc import ABC, abstractmethod
|
|
9
|
+
from typing import Any, Callable, Generic, Iterable, Optional, TypeVar
|
|
10
|
+
|
|
11
|
+
from .errors import AuthenticationError
|
|
12
|
+
from .http import API_KEY_HEADER, CSRF_HEADER, CredentialRequest, SignInResponse
|
|
13
|
+
|
|
14
|
+
S = TypeVar("S")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class Credential(ABC):
|
|
18
|
+
"""How requests authenticate. Implementations must be safe to share between threads (sync) or tasks (async)."""
|
|
19
|
+
|
|
20
|
+
@abstractmethod
|
|
21
|
+
def apply(self, request: CredentialRequest) -> None:
|
|
22
|
+
"""Adds headers before a request is sent (sync clients), signing in first when needed."""
|
|
23
|
+
|
|
24
|
+
async def apply_async(self, request: CredentialRequest) -> None:
|
|
25
|
+
"""Adds headers before a request is sent (async clients)."""
|
|
26
|
+
self.apply(request)
|
|
27
|
+
|
|
28
|
+
def refresh_after_unauthorized(self, request: CredentialRequest) -> bool:
|
|
29
|
+
"""Called on a 401; True when one retry with fresh credentials is worthwhile."""
|
|
30
|
+
return False
|
|
31
|
+
|
|
32
|
+
async def refresh_after_unauthorized_async(self, request: CredentialRequest) -> bool:
|
|
33
|
+
return self.refresh_after_unauthorized(request)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class ApiKeyCredential(Credential):
|
|
37
|
+
"""An API client key, sent as ``X-Transynq-APIKey``. The key's company is the tenant; no cookie, no CSRF."""
|
|
38
|
+
|
|
39
|
+
def __init__(self, api_key: str) -> None:
|
|
40
|
+
if not api_key or not api_key.strip():
|
|
41
|
+
raise ValueError("api_key is required")
|
|
42
|
+
self._key = api_key
|
|
43
|
+
|
|
44
|
+
def apply(self, request: CredentialRequest) -> None:
|
|
45
|
+
request.set_header(API_KEY_HEADER, self._key)
|
|
46
|
+
|
|
47
|
+
def __repr__(self) -> str:
|
|
48
|
+
return "ApiKeyCredential([redacted])"
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class DriverTokenCredential(Credential):
|
|
52
|
+
"""An existing driver-app token (``Authorization: Bearer <token>``), valid for ``/api/v1/driver/*``."""
|
|
53
|
+
|
|
54
|
+
def __init__(self, token: str) -> None:
|
|
55
|
+
if not token or not token.strip():
|
|
56
|
+
raise ValueError("token is required")
|
|
57
|
+
self._token = token
|
|
58
|
+
|
|
59
|
+
def apply(self, request: CredentialRequest) -> None:
|
|
60
|
+
request.set_header("Authorization", "Bearer " + self._token)
|
|
61
|
+
|
|
62
|
+
def __repr__(self) -> str:
|
|
63
|
+
return "DriverTokenCredential([redacted])"
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _parse_instant(value: Any) -> Optional[_dt.datetime]:
|
|
67
|
+
if not isinstance(value, str):
|
|
68
|
+
return None
|
|
69
|
+
try:
|
|
70
|
+
parsed = _dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
|
|
71
|
+
except ValueError:
|
|
72
|
+
return None
|
|
73
|
+
return parsed if parsed.tzinfo else parsed.replace(tzinfo=_dt.timezone.utc)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class SignInCredential(Credential, Generic[S]):
|
|
77
|
+
"""Base of credentials that sign in: single-flight sign-in, refresh before expiry and once after a 401."""
|
|
78
|
+
|
|
79
|
+
refresh_margin = _dt.timedelta(seconds=60)
|
|
80
|
+
|
|
81
|
+
def __init__(self) -> None:
|
|
82
|
+
self._state: Optional[S] = None
|
|
83
|
+
self._lock = threading.Lock()
|
|
84
|
+
self._async_lock: Optional[asyncio.Lock] = None
|
|
85
|
+
self.sign_in_count = 0
|
|
86
|
+
self.clock: Callable[[], _dt.datetime] = lambda: _dt.datetime.now(_dt.timezone.utc)
|
|
87
|
+
|
|
88
|
+
@property
|
|
89
|
+
def state(self) -> Optional[S]:
|
|
90
|
+
return self._state
|
|
91
|
+
|
|
92
|
+
def reset(self) -> None:
|
|
93
|
+
"""Forgets the signed-in state (after a sign-out); the next request signs in again."""
|
|
94
|
+
self._state = None
|
|
95
|
+
|
|
96
|
+
def _fresh(self, state: Optional[S]) -> bool:
|
|
97
|
+
if state is None:
|
|
98
|
+
return False
|
|
99
|
+
expires = self._expires(state)
|
|
100
|
+
return expires is None or expires - self.refresh_margin > self.clock()
|
|
101
|
+
|
|
102
|
+
def apply(self, request: CredentialRequest) -> None:
|
|
103
|
+
state = self._state
|
|
104
|
+
if not self._fresh(state):
|
|
105
|
+
with self._lock:
|
|
106
|
+
state = self._state
|
|
107
|
+
if not self._fresh(state):
|
|
108
|
+
state = self._from_answer(self._sign_in_call(request.transport.post_json))
|
|
109
|
+
self.sign_in_count += 1
|
|
110
|
+
self._state = state
|
|
111
|
+
assert state is not None
|
|
112
|
+
request.applied_state = state
|
|
113
|
+
self._apply(request, state)
|
|
114
|
+
|
|
115
|
+
async def apply_async(self, request: CredentialRequest) -> None:
|
|
116
|
+
state = self._state
|
|
117
|
+
if not self._fresh(state):
|
|
118
|
+
if self._async_lock is None:
|
|
119
|
+
self._async_lock = asyncio.Lock()
|
|
120
|
+
async with self._async_lock:
|
|
121
|
+
state = self._state
|
|
122
|
+
if not self._fresh(state):
|
|
123
|
+
state = self._from_answer(await self._sign_in_call(request.transport.post_json))
|
|
124
|
+
self.sign_in_count += 1
|
|
125
|
+
self._state = state
|
|
126
|
+
assert state is not None
|
|
127
|
+
request.applied_state = state
|
|
128
|
+
self._apply(request, state)
|
|
129
|
+
|
|
130
|
+
def refresh_after_unauthorized(self, request: CredentialRequest) -> bool:
|
|
131
|
+
with self._lock:
|
|
132
|
+
# only drop the state the failed request used; another caller may already have signed in again
|
|
133
|
+
if self._state is request.applied_state:
|
|
134
|
+
self._state = None
|
|
135
|
+
return True
|
|
136
|
+
|
|
137
|
+
async def refresh_after_unauthorized_async(self, request: CredentialRequest) -> bool:
|
|
138
|
+
if self._state is request.applied_state:
|
|
139
|
+
self._state = None
|
|
140
|
+
return True
|
|
141
|
+
|
|
142
|
+
@abstractmethod
|
|
143
|
+
def _sign_in_call(self, post_json: Callable[..., Any]) -> Any:
|
|
144
|
+
"""Calls ``post_json(path, body, headers, operation_id)`` (returns its result or awaitable)."""
|
|
145
|
+
|
|
146
|
+
@abstractmethod
|
|
147
|
+
def _from_answer(self, answer: SignInResponse) -> S: ...
|
|
148
|
+
|
|
149
|
+
@abstractmethod
|
|
150
|
+
def _expires(self, state: S) -> Optional[_dt.datetime]: ...
|
|
151
|
+
|
|
152
|
+
@abstractmethod
|
|
153
|
+
def _apply(self, request: CredentialRequest, state: S) -> None: ...
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
class Session:
|
|
157
|
+
"""A signed-in session (the cookie and CSRF token are never printed)."""
|
|
158
|
+
|
|
159
|
+
def __init__(self, cookie: str, csrf_token: str, expires_utc: Optional[_dt.datetime], me: Any) -> None:
|
|
160
|
+
self.cookie = cookie
|
|
161
|
+
self.csrf_token = csrf_token
|
|
162
|
+
self.expires_utc = expires_utc
|
|
163
|
+
self.me = me
|
|
164
|
+
|
|
165
|
+
def __repr__(self) -> str:
|
|
166
|
+
return f"Session(expires_utc={self.expires_utc!r}, [redacted])"
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def session_cookie(set_cookies: Iterable[str]) -> Optional[str]:
|
|
170
|
+
"""The ``name=value`` of the session cookie (``tq_session`` or ``__Host-tq_session``)."""
|
|
171
|
+
for header in set_cookies:
|
|
172
|
+
pair = header.split(";", 1)[0].strip()
|
|
173
|
+
name, sep, value = pair.partition("=")
|
|
174
|
+
if sep and value and name.endswith("tq_session"):
|
|
175
|
+
return pair
|
|
176
|
+
return None
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class SessionCredential(SignInCredential[Session]):
|
|
180
|
+
"""
|
|
181
|
+
A user session: ``POST /api/v1/auth/login`` with user name and password, then the session cookie on every request
|
|
182
|
+
and ``X-CSRF-Token`` on every unsafe one. Signs in again before the session expires and once after a 401.
|
|
183
|
+
"""
|
|
184
|
+
|
|
185
|
+
def __init__(self, user_name: str, password: str) -> None:
|
|
186
|
+
super().__init__()
|
|
187
|
+
if not user_name or not password:
|
|
188
|
+
raise ValueError("user_name and password are required")
|
|
189
|
+
self._user_name = user_name
|
|
190
|
+
self._password = password
|
|
191
|
+
|
|
192
|
+
@property
|
|
193
|
+
def me(self) -> Any:
|
|
194
|
+
"""The login answer (``MeResponse`` as a dict), or ``None`` before the first request."""
|
|
195
|
+
return self._state.me if self._state else None
|
|
196
|
+
|
|
197
|
+
def _sign_in_call(self, post_json: Callable[..., Any]) -> Any:
|
|
198
|
+
body = json.dumps({"userName": self._user_name, "password": self._password}).encode("utf-8")
|
|
199
|
+
# without a session the CSRF check only needs a non-empty value
|
|
200
|
+
return post_json("/api/v1/auth/login", body, {CSRF_HEADER: "transynq-sdk"}, "Login")
|
|
201
|
+
|
|
202
|
+
def _from_answer(self, answer: SignInResponse) -> Session:
|
|
203
|
+
cookie = session_cookie(answer.set_cookies)
|
|
204
|
+
if cookie is None:
|
|
205
|
+
raise AuthenticationError("Login answered without a session cookie.", status=answer.status_code, operation_id="Login")
|
|
206
|
+
me = json.loads(answer.body) if answer.body else {}
|
|
207
|
+
csrf = me.get("csrfToken") if isinstance(me, dict) else None
|
|
208
|
+
if not csrf:
|
|
209
|
+
raise AuthenticationError("Login answered without a csrfToken.", status=answer.status_code, operation_id="Login")
|
|
210
|
+
return Session(cookie, csrf, _parse_instant(me.get("sessionExpiresUtc")), me)
|
|
211
|
+
|
|
212
|
+
def _expires(self, state: Session) -> Optional[_dt.datetime]:
|
|
213
|
+
return state.expires_utc
|
|
214
|
+
|
|
215
|
+
def _apply(self, request: CredentialRequest, state: Session) -> None:
|
|
216
|
+
request.set_header("Cookie", state.cookie)
|
|
217
|
+
if request.is_unsafe:
|
|
218
|
+
request.set_header(CSRF_HEADER, state.csrf_token)
|
|
219
|
+
|
|
220
|
+
def __repr__(self) -> str:
|
|
221
|
+
return f"SessionCredential({self._user_name!r}, [redacted])"
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
class DriverToken:
|
|
225
|
+
def __init__(self, token: str, expires_utc: Optional[_dt.datetime], session: Any) -> None:
|
|
226
|
+
self.token = token
|
|
227
|
+
self.expires_utc = expires_utc
|
|
228
|
+
self.session = session
|
|
229
|
+
|
|
230
|
+
def __repr__(self) -> str:
|
|
231
|
+
return f"DriverToken(expires_utc={self.expires_utc!r}, [redacted])"
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
class DriverLoginCredential(SignInCredential[DriverToken]):
|
|
235
|
+
"""Driver-app sign-in (``POST /api/v1/driver/login``), then ``Authorization: Bearer <token>``."""
|
|
236
|
+
|
|
237
|
+
def __init__(self, company_code: str, pin: str, device_id: str, push_token: str, app_version: str, platform: str) -> None:
|
|
238
|
+
super().__init__()
|
|
239
|
+
self._login = {"companyCode": company_code, "pin": pin, "deviceId": device_id, "pushToken": push_token,
|
|
240
|
+
"appVersion": app_version, "platform": platform}
|
|
241
|
+
|
|
242
|
+
@property
|
|
243
|
+
def session(self) -> Any:
|
|
244
|
+
"""The last ``DriverSession`` (as a dict), or ``None``."""
|
|
245
|
+
return self._state.session if self._state else None
|
|
246
|
+
|
|
247
|
+
def _sign_in_call(self, post_json: Callable[..., Any]) -> Any:
|
|
248
|
+
return post_json("/api/v1/driver/login", json.dumps(self._login).encode("utf-8"), {}, "DriverLogin")
|
|
249
|
+
|
|
250
|
+
def _from_answer(self, answer: SignInResponse) -> DriverToken:
|
|
251
|
+
session = json.loads(answer.body) if answer.body else {}
|
|
252
|
+
token = session.get("token") if isinstance(session, dict) else None
|
|
253
|
+
if not token:
|
|
254
|
+
raise AuthenticationError("DriverLogin answered without a token.", status=answer.status_code, operation_id="DriverLogin")
|
|
255
|
+
return DriverToken(token, _parse_instant(session.get("expiresUtc")), session)
|
|
256
|
+
|
|
257
|
+
def _expires(self, state: DriverToken) -> Optional[_dt.datetime]:
|
|
258
|
+
return state.expires_utc
|
|
259
|
+
|
|
260
|
+
def _apply(self, request: CredentialRequest, state: DriverToken) -> None:
|
|
261
|
+
request.set_header("Authorization", "Bearer " + state.token)
|
|
262
|
+
|
|
263
|
+
def __repr__(self) -> str:
|
|
264
|
+
return "DriverLoginCredential([redacted])"
|