aw3-sdk 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.
- aw3_sdk/__init__.py +485 -0
- aw3_sdk/py.typed +0 -0
- aw3_sdk-1.0.0.dist-info/METADATA +268 -0
- aw3_sdk-1.0.0.dist-info/RECORD +6 -0
- aw3_sdk-1.0.0.dist-info/WHEEL +4 -0
- aw3_sdk-1.0.0.dist-info/licenses/LICENSE +21 -0
aw3_sdk/__init__.py
ADDED
|
@@ -0,0 +1,485 @@
|
|
|
1
|
+
"""
|
|
2
|
+
AW3 Python SDK
|
|
3
|
+
==============
|
|
4
|
+
|
|
5
|
+
Multi-cloud deployment control plane client for Python.
|
|
6
|
+
|
|
7
|
+
Installation:
|
|
8
|
+
pip install httpx # Required dependency
|
|
9
|
+
|
|
10
|
+
Usage:
|
|
11
|
+
from aw3_sdk import AW3Client
|
|
12
|
+
|
|
13
|
+
client = AW3Client(base_url="https://app.aw3.host/api", token="your-api-token")
|
|
14
|
+
|
|
15
|
+
# Deploy a service
|
|
16
|
+
deployment = client.deploy("my-service-id", commit_sha="abc123")
|
|
17
|
+
print(f"Deployment: {deployment['id']}")
|
|
18
|
+
|
|
19
|
+
# Stream logs
|
|
20
|
+
for line in client.stream_logs("my-service-id"):
|
|
21
|
+
print(line)
|
|
22
|
+
|
|
23
|
+
# Roll back
|
|
24
|
+
rollback = client.rollback("my-service-id")
|
|
25
|
+
print(f"Rolled back: {rollback['id']}")
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from __future__ import annotations
|
|
29
|
+
|
|
30
|
+
import json
|
|
31
|
+
import os
|
|
32
|
+
import time
|
|
33
|
+
from dataclasses import dataclass, field
|
|
34
|
+
from typing import Any, Dict, Generator, Iterator, List, Optional
|
|
35
|
+
|
|
36
|
+
try:
|
|
37
|
+
import httpx
|
|
38
|
+
except ImportError:
|
|
39
|
+
raise ImportError(
|
|
40
|
+
"httpx is required for the AW3 SDK. Install it with: pip install httpx"
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
# ── Data Classes ──────────────────────────────────────────────────────────────
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass
|
|
48
|
+
class Deployment:
|
|
49
|
+
id: str
|
|
50
|
+
service_id: str
|
|
51
|
+
status: str
|
|
52
|
+
created_at: str
|
|
53
|
+
deploy_url: Optional[str] = None
|
|
54
|
+
commit_sha: Optional[str] = None
|
|
55
|
+
commit_message: Optional[str] = None
|
|
56
|
+
image_tag: Optional[str] = None
|
|
57
|
+
error: Optional[str] = None
|
|
58
|
+
branch: Optional[str] = None
|
|
59
|
+
raw: Dict[str, Any] = field(default_factory=dict)
|
|
60
|
+
|
|
61
|
+
@classmethod
|
|
62
|
+
def from_dict(cls, data: Dict[str, Any]) -> "Deployment":
|
|
63
|
+
return cls(
|
|
64
|
+
id=data.get("id", ""),
|
|
65
|
+
service_id=data.get("serviceId", ""),
|
|
66
|
+
status=data.get("status", ""),
|
|
67
|
+
created_at=data.get("createdAt", ""),
|
|
68
|
+
deploy_url=data.get("deployUrl"),
|
|
69
|
+
commit_sha=data.get("commitSha"),
|
|
70
|
+
commit_message=data.get("commitMessage"),
|
|
71
|
+
image_tag=data.get("imageTag"),
|
|
72
|
+
error=data.get("error"),
|
|
73
|
+
branch=data.get("branch"),
|
|
74
|
+
raw=data,
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@dataclass
|
|
79
|
+
class Service:
|
|
80
|
+
id: str
|
|
81
|
+
name: str
|
|
82
|
+
type: str
|
|
83
|
+
status: Optional[str] = None
|
|
84
|
+
deploy_url: Optional[str] = None
|
|
85
|
+
last_deployed_at: Optional[str] = None
|
|
86
|
+
raw: Dict[str, Any] = field(default_factory=dict)
|
|
87
|
+
|
|
88
|
+
@classmethod
|
|
89
|
+
def from_dict(cls, data: Dict[str, Any]) -> "Service":
|
|
90
|
+
return cls(
|
|
91
|
+
id=data.get("id", ""),
|
|
92
|
+
name=data.get("name", ""),
|
|
93
|
+
type=data.get("type", "web"),
|
|
94
|
+
status=data.get("status"),
|
|
95
|
+
deploy_url=data.get("deployUrl"),
|
|
96
|
+
last_deployed_at=data.get("lastDeployedAt"),
|
|
97
|
+
raw=data,
|
|
98
|
+
)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
@dataclass
|
|
102
|
+
class LogLine:
|
|
103
|
+
timestamp: str
|
|
104
|
+
message: str
|
|
105
|
+
level: str = "info"
|
|
106
|
+
service_id: Optional[str] = None
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
class AW3Error(Exception):
|
|
110
|
+
"""AW3 API error with status code and message."""
|
|
111
|
+
|
|
112
|
+
def __init__(self, status_code: int, message: str, raw: Optional[Dict] = None):
|
|
113
|
+
super().__init__(f"AW3 API error {status_code}: {message}")
|
|
114
|
+
self.status_code = status_code
|
|
115
|
+
self.message = message
|
|
116
|
+
self.raw = raw or {}
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
# ── Main Client ───────────────────────────────────────────────────────────────
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
class AW3Client:
|
|
123
|
+
"""
|
|
124
|
+
AW3 multi-cloud deployment control plane client.
|
|
125
|
+
|
|
126
|
+
Args:
|
|
127
|
+
base_url: AW3 API base URL (default: AW3_BASE_URL env var or https://app.aw3.host/api)
|
|
128
|
+
token: API authentication token (default: AW3_TOKEN env var)
|
|
129
|
+
timeout: Request timeout in seconds (default: 30)
|
|
130
|
+
max_retries: Maximum number of retries for transient errors (default: 3)
|
|
131
|
+
"""
|
|
132
|
+
|
|
133
|
+
TERMINAL_STATUSES = frozenset(["deployed", "failed", "cancelled", "rolled_back", "success"])
|
|
134
|
+
|
|
135
|
+
def __init__(
|
|
136
|
+
self,
|
|
137
|
+
base_url: Optional[str] = None,
|
|
138
|
+
token: Optional[str] = None,
|
|
139
|
+
timeout: float = 30.0,
|
|
140
|
+
max_retries: int = 3,
|
|
141
|
+
) -> None:
|
|
142
|
+
self.base_url = (base_url or os.environ.get("AW3_BASE_URL", "https://app.aw3.host/api")).rstrip("/")
|
|
143
|
+
self.token = token or os.environ.get("AW3_TOKEN", "")
|
|
144
|
+
self.timeout = timeout
|
|
145
|
+
self.max_retries = max_retries
|
|
146
|
+
|
|
147
|
+
self._client = httpx.Client(
|
|
148
|
+
base_url=self.base_url,
|
|
149
|
+
timeout=timeout,
|
|
150
|
+
headers=self._build_headers(),
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
def _build_headers(self) -> Dict[str, str]:
|
|
154
|
+
headers = {
|
|
155
|
+
"Content-Type": "application/json",
|
|
156
|
+
"Accept": "application/json",
|
|
157
|
+
"User-Agent": "aw3-python-sdk/1.0.0",
|
|
158
|
+
}
|
|
159
|
+
if self.token:
|
|
160
|
+
headers["Authorization"] = f"Bearer {self.token}"
|
|
161
|
+
return headers
|
|
162
|
+
|
|
163
|
+
def _request(
|
|
164
|
+
self,
|
|
165
|
+
method: str,
|
|
166
|
+
path: str,
|
|
167
|
+
json_body: Optional[Dict] = None,
|
|
168
|
+
params: Optional[Dict] = None,
|
|
169
|
+
) -> Dict[str, Any]:
|
|
170
|
+
"""Execute an HTTP request with retry logic."""
|
|
171
|
+
last_error: Optional[Exception] = None
|
|
172
|
+
|
|
173
|
+
for attempt in range(self.max_retries):
|
|
174
|
+
try:
|
|
175
|
+
response = self._client.request(
|
|
176
|
+
method=method,
|
|
177
|
+
url=path,
|
|
178
|
+
json=json_body,
|
|
179
|
+
params=params,
|
|
180
|
+
)
|
|
181
|
+
|
|
182
|
+
if response.status_code >= 400:
|
|
183
|
+
try:
|
|
184
|
+
error_data = response.json()
|
|
185
|
+
except Exception:
|
|
186
|
+
error_data = {}
|
|
187
|
+
message = error_data.get("error") or error_data.get("message") or response.text
|
|
188
|
+
raise AW3Error(response.status_code, message, error_data)
|
|
189
|
+
|
|
190
|
+
if response.status_code == 204:
|
|
191
|
+
return {}
|
|
192
|
+
|
|
193
|
+
return response.json()
|
|
194
|
+
|
|
195
|
+
except AW3Error:
|
|
196
|
+
raise
|
|
197
|
+
except httpx.TimeoutException as e:
|
|
198
|
+
last_error = e
|
|
199
|
+
if attempt < self.max_retries - 1:
|
|
200
|
+
time.sleep(2 ** attempt) # Exponential backoff
|
|
201
|
+
except httpx.RequestError as e:
|
|
202
|
+
last_error = e
|
|
203
|
+
if attempt < self.max_retries - 1:
|
|
204
|
+
time.sleep(2 ** attempt)
|
|
205
|
+
|
|
206
|
+
raise AW3Error(0, f"Request failed after {self.max_retries} attempts: {last_error}")
|
|
207
|
+
|
|
208
|
+
# ── Deployments ───────────────────────────────────────────────────────────
|
|
209
|
+
|
|
210
|
+
def deploy(
|
|
211
|
+
self,
|
|
212
|
+
service_id: str,
|
|
213
|
+
commit_sha: Optional[str] = None,
|
|
214
|
+
commit_message: Optional[str] = None,
|
|
215
|
+
branch: Optional[str] = None,
|
|
216
|
+
strategy: Optional[str] = None,
|
|
217
|
+
canary_percent: Optional[int] = None,
|
|
218
|
+
wait: bool = False,
|
|
219
|
+
poll_interval: float = 2.0,
|
|
220
|
+
timeout_minutes: float = 30.0,
|
|
221
|
+
) -> Deployment:
|
|
222
|
+
"""
|
|
223
|
+
Deploy a service.
|
|
224
|
+
|
|
225
|
+
Args:
|
|
226
|
+
service_id: Service ID to deploy
|
|
227
|
+
commit_sha: Git commit SHA to deploy
|
|
228
|
+
commit_message: Commit message for this deployment
|
|
229
|
+
branch: Git branch to deploy from
|
|
230
|
+
strategy: Deployment strategy ('standard', 'blue-green', 'canary')
|
|
231
|
+
canary_percent: Initial canary traffic percentage (0-100)
|
|
232
|
+
wait: If True, poll until deployment completes
|
|
233
|
+
poll_interval: Polling interval in seconds when wait=True
|
|
234
|
+
timeout_minutes: Maximum time to wait in minutes
|
|
235
|
+
|
|
236
|
+
Returns:
|
|
237
|
+
Deployment object
|
|
238
|
+
|
|
239
|
+
Example:
|
|
240
|
+
deployment = client.deploy("my-api", commit_sha="abc123", wait=True)
|
|
241
|
+
print(f"Status: {deployment.status}")
|
|
242
|
+
"""
|
|
243
|
+
body: Dict[str, Any] = {"serviceId": service_id}
|
|
244
|
+
if commit_sha:
|
|
245
|
+
body["commitSha"] = commit_sha
|
|
246
|
+
if commit_message:
|
|
247
|
+
body["commitMessage"] = commit_message
|
|
248
|
+
if branch:
|
|
249
|
+
body["branch"] = branch
|
|
250
|
+
if strategy:
|
|
251
|
+
body["strategy"] = strategy
|
|
252
|
+
if canary_percent is not None:
|
|
253
|
+
body["canaryPercent"] = canary_percent
|
|
254
|
+
|
|
255
|
+
data = self._request("POST", "/deployments", json_body=body)
|
|
256
|
+
deployment = Deployment.from_dict(data.get("deployment", data))
|
|
257
|
+
|
|
258
|
+
if wait:
|
|
259
|
+
deadline = time.time() + timeout_minutes * 60
|
|
260
|
+
while deployment.status not in self.TERMINAL_STATUSES:
|
|
261
|
+
if time.time() > deadline:
|
|
262
|
+
raise TimeoutError(
|
|
263
|
+
f"Deployment {deployment.id} did not complete within {timeout_minutes} minutes"
|
|
264
|
+
)
|
|
265
|
+
time.sleep(poll_interval)
|
|
266
|
+
deployment = self.get_deployment(deployment.id)
|
|
267
|
+
|
|
268
|
+
return deployment
|
|
269
|
+
|
|
270
|
+
def get_deployment(self, deployment_id: str) -> Deployment:
|
|
271
|
+
"""Get a deployment by ID."""
|
|
272
|
+
data = self._request("GET", f"/deployments/{deployment_id}")
|
|
273
|
+
return Deployment.from_dict(data.get("deployment", data))
|
|
274
|
+
|
|
275
|
+
def list_deployments(
|
|
276
|
+
self,
|
|
277
|
+
service_id: Optional[str] = None,
|
|
278
|
+
limit: int = 20,
|
|
279
|
+
status: Optional[str] = None,
|
|
280
|
+
) -> List[Deployment]:
|
|
281
|
+
"""List deployments, optionally filtered by service ID and status."""
|
|
282
|
+
params: Dict[str, Any] = {"take": limit}
|
|
283
|
+
if service_id:
|
|
284
|
+
params["serviceId"] = service_id
|
|
285
|
+
if status:
|
|
286
|
+
params["status"] = status
|
|
287
|
+
|
|
288
|
+
data = self._request("GET", "/deployments", params=params)
|
|
289
|
+
items = data.get("deployments") or data.get("data") or []
|
|
290
|
+
return [Deployment.from_dict(d) for d in items]
|
|
291
|
+
|
|
292
|
+
def rollback(
|
|
293
|
+
self,
|
|
294
|
+
service_id: str,
|
|
295
|
+
target_deployment_id: Optional[str] = None,
|
|
296
|
+
) -> Deployment:
|
|
297
|
+
"""
|
|
298
|
+
Roll back a service to the previous (or specified) deployment.
|
|
299
|
+
|
|
300
|
+
Args:
|
|
301
|
+
service_id: Service ID to roll back
|
|
302
|
+
target_deployment_id: Specific deployment to roll back to (optional)
|
|
303
|
+
|
|
304
|
+
Returns:
|
|
305
|
+
The rollback deployment record
|
|
306
|
+
"""
|
|
307
|
+
# Find the latest deployment for this service to get its ID
|
|
308
|
+
deployments = self.list_deployments(service_id=service_id, limit=2)
|
|
309
|
+
if not deployments:
|
|
310
|
+
raise AW3Error(404, f"No deployments found for service {service_id}")
|
|
311
|
+
|
|
312
|
+
deploy_id = deployments[0].id
|
|
313
|
+
body: Dict[str, Any] = {}
|
|
314
|
+
if target_deployment_id:
|
|
315
|
+
body["targetDeploymentId"] = target_deployment_id
|
|
316
|
+
|
|
317
|
+
data = self._request("POST", f"/deployments/{deploy_id}/rollback", json_body=body)
|
|
318
|
+
return Deployment.from_dict(data.get("deployment", data))
|
|
319
|
+
|
|
320
|
+
# ── Logs ──────────────────────────────────────────────────────────────────
|
|
321
|
+
|
|
322
|
+
def get_logs(
|
|
323
|
+
self,
|
|
324
|
+
service_id: str,
|
|
325
|
+
deployment_id: Optional[str] = None,
|
|
326
|
+
lines: int = 100,
|
|
327
|
+
) -> List[LogLine]:
|
|
328
|
+
"""
|
|
329
|
+
Fetch the build/deploy log of a deployment.
|
|
330
|
+
|
|
331
|
+
Args:
|
|
332
|
+
service_id: Service the deployment belongs to
|
|
333
|
+
deployment_id: Deployment to read; defaults to the service's latest deployment
|
|
334
|
+
lines: Maximum number of (most recent) log lines to return
|
|
335
|
+
|
|
336
|
+
Returns:
|
|
337
|
+
List of LogLine objects
|
|
338
|
+
"""
|
|
339
|
+
if not deployment_id:
|
|
340
|
+
latest = self.list_deployments(service_id=service_id, limit=1)
|
|
341
|
+
if not latest:
|
|
342
|
+
return []
|
|
343
|
+
deployment_id = latest[0].id
|
|
344
|
+
|
|
345
|
+
data = self._request("GET", f"/deployments/{deployment_id}/logs")
|
|
346
|
+
raw = data.get("logs") or ""
|
|
347
|
+
raw_lines = raw.splitlines() if isinstance(raw, str) else [str(x) for x in raw]
|
|
348
|
+
|
|
349
|
+
return [
|
|
350
|
+
LogLine(timestamp="", message=line, level="info", service_id=service_id)
|
|
351
|
+
for line in raw_lines[-lines:]
|
|
352
|
+
]
|
|
353
|
+
|
|
354
|
+
def stream_logs(
|
|
355
|
+
self,
|
|
356
|
+
service_id: str,
|
|
357
|
+
deployment_id: Optional[str] = None,
|
|
358
|
+
follow: bool = True,
|
|
359
|
+
) -> Generator[LogLine, None, None]:
|
|
360
|
+
"""
|
|
361
|
+
Stream logs for a service as a generator.
|
|
362
|
+
|
|
363
|
+
Args:
|
|
364
|
+
service_id: Service to stream logs for
|
|
365
|
+
deployment_id: Specific deployment to stream logs for
|
|
366
|
+
follow: If True, keep streaming new logs
|
|
367
|
+
|
|
368
|
+
Yields:
|
|
369
|
+
LogLine objects
|
|
370
|
+
|
|
371
|
+
Example:
|
|
372
|
+
for log in client.stream_logs("my-api"):
|
|
373
|
+
print(f"[{log.timestamp}] {log.message}")
|
|
374
|
+
"""
|
|
375
|
+
if not deployment_id:
|
|
376
|
+
# Get the latest deployment ID
|
|
377
|
+
deployments = self.list_deployments(service_id=service_id, limit=1)
|
|
378
|
+
if deployments:
|
|
379
|
+
deployment_id = deployments[0].id
|
|
380
|
+
|
|
381
|
+
if not deployment_id:
|
|
382
|
+
return
|
|
383
|
+
|
|
384
|
+
# Try SSE streaming first
|
|
385
|
+
sse_url = f"{self.base_url}/deployments/{deployment_id}/logs/stream"
|
|
386
|
+
try:
|
|
387
|
+
with httpx.stream(
|
|
388
|
+
"GET",
|
|
389
|
+
sse_url,
|
|
390
|
+
headers=self._build_headers(),
|
|
391
|
+
timeout=300.0,
|
|
392
|
+
) as response:
|
|
393
|
+
if response.status_code == 200:
|
|
394
|
+
for line in response.iter_lines():
|
|
395
|
+
if line.startswith("data: "):
|
|
396
|
+
raw = line[6:]
|
|
397
|
+
try:
|
|
398
|
+
data = json.loads(raw)
|
|
399
|
+
yield LogLine(
|
|
400
|
+
timestamp=data.get("timestamp", ""),
|
|
401
|
+
message=data.get("message", raw),
|
|
402
|
+
level=data.get("level", "info"),
|
|
403
|
+
service_id=service_id,
|
|
404
|
+
)
|
|
405
|
+
except json.JSONDecodeError:
|
|
406
|
+
yield LogLine(timestamp="", message=raw)
|
|
407
|
+
return
|
|
408
|
+
except Exception:
|
|
409
|
+
pass
|
|
410
|
+
|
|
411
|
+
# Fallback: poll get_logs
|
|
412
|
+
seen_messages: set = set()
|
|
413
|
+
while True:
|
|
414
|
+
logs = self.get_logs(service_id, deployment_id)
|
|
415
|
+
for log in logs:
|
|
416
|
+
key = f"{log.timestamp}:{log.message}"
|
|
417
|
+
if key not in seen_messages:
|
|
418
|
+
seen_messages.add(key)
|
|
419
|
+
yield log
|
|
420
|
+
if not follow:
|
|
421
|
+
break
|
|
422
|
+
time.sleep(2)
|
|
423
|
+
|
|
424
|
+
# ── Services ──────────────────────────────────────────────────────────────
|
|
425
|
+
|
|
426
|
+
def list_services(
|
|
427
|
+
self,
|
|
428
|
+
project_id: Optional[str] = None,
|
|
429
|
+
limit: int = 50,
|
|
430
|
+
) -> List[Service]:
|
|
431
|
+
"""
|
|
432
|
+
List services.
|
|
433
|
+
|
|
434
|
+
Args:
|
|
435
|
+
project_id: Filter by project ID
|
|
436
|
+
limit: Maximum number of services to return
|
|
437
|
+
|
|
438
|
+
Returns:
|
|
439
|
+
List of Service objects
|
|
440
|
+
"""
|
|
441
|
+
params: Dict[str, Any] = {"take": limit}
|
|
442
|
+
if project_id:
|
|
443
|
+
params["projectId"] = project_id
|
|
444
|
+
|
|
445
|
+
data = self._request("GET", "/services", params=params)
|
|
446
|
+
items = data.get("services") or data.get("data") or []
|
|
447
|
+
return [Service.from_dict(s) for s in items]
|
|
448
|
+
|
|
449
|
+
def get_service(self, service_id: str) -> Service:
|
|
450
|
+
"""Get a service by ID."""
|
|
451
|
+
data = self._request("GET", f"/services/{service_id}")
|
|
452
|
+
return Service.from_dict(data.get("service", data))
|
|
453
|
+
|
|
454
|
+
def get_status(self, service_id: str) -> Dict[str, Any]:
|
|
455
|
+
"""
|
|
456
|
+
Get current deployment status and health for a service.
|
|
457
|
+
|
|
458
|
+
Returns dict with keys: service, latestDeployment, health, providers
|
|
459
|
+
"""
|
|
460
|
+
deployments = self.list_deployments(service_id=service_id, limit=1)
|
|
461
|
+
latest = deployments[0] if deployments else None
|
|
462
|
+
|
|
463
|
+
return {
|
|
464
|
+
"serviceId": service_id,
|
|
465
|
+
"status": latest.status if latest else "unknown",
|
|
466
|
+
"deploymentId": latest.id if latest else None,
|
|
467
|
+
"deployUrl": latest.deploy_url if latest else None,
|
|
468
|
+
"lastDeployedAt": latest.created_at if latest else None,
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
# ── Context manager ───────────────────────────────────────────────────────
|
|
472
|
+
|
|
473
|
+
def __enter__(self) -> "AW3Client":
|
|
474
|
+
return self
|
|
475
|
+
|
|
476
|
+
def __exit__(self, *args: Any) -> None:
|
|
477
|
+
self.close()
|
|
478
|
+
|
|
479
|
+
def close(self) -> None:
|
|
480
|
+
"""Close the HTTP client."""
|
|
481
|
+
self._client.close()
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
__all__ = ["AW3Client", "Deployment", "Service", "LogLine", "AW3Error"]
|
|
485
|
+
__version__ = "1.0.0"
|
aw3_sdk/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: aw3-sdk
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Python client for AW3 Host, the multi-cloud deployment control plane: deploy to 17 clouds from one API.
|
|
5
|
+
Project-URL: Homepage, https://aw3.host
|
|
6
|
+
Project-URL: Documentation, https://aw3.host/docs
|
|
7
|
+
Project-URL: Source, https://github.com/aw3-technology/aw3-sdk
|
|
8
|
+
Project-URL: Issues, https://github.com/aw3-technology/aw3-sdk/issues
|
|
9
|
+
Author-email: "AW3 Technology, Inc." <contact@aw3.tech>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: aw3,aws,blue-green,canary,cloudflare,deployment,devops,multi-cloud,railway,vercel
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
17
|
+
Classifier: Topic :: System :: Systems Administration
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.8
|
|
20
|
+
Requires-Dist: httpx>=0.24
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# aw3-sdk — AW3 Python SDK
|
|
24
|
+
|
|
25
|
+
The official Python client for the [AW3](https://aw3.host) multi-cloud deployment control plane.
|
|
26
|
+
|
|
27
|
+
## Requirements
|
|
28
|
+
|
|
29
|
+
- Python 3.8+
|
|
30
|
+
- `httpx` (installed automatically)
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install aw3-sdk
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Quick Start
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
from aw3_sdk import AW3Client
|
|
42
|
+
|
|
43
|
+
client = AW3Client(
|
|
44
|
+
base_url="https://app.aw3.host/api",
|
|
45
|
+
token="aw3_abc123...", # or set AW3_TOKEN env var
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
# Deploy a service (blocks until terminal state)
|
|
49
|
+
deployment = client.deploy("svc-abc123", commit_sha="a1b2c3d", wait=True)
|
|
50
|
+
print(f"Status: {deployment.status}")
|
|
51
|
+
print(f"URL: {deployment.deploy_url}")
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Configuration
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
client = AW3Client(
|
|
58
|
+
base_url="https://app.aw3.host/api", # or AW3_BASE_URL env var
|
|
59
|
+
token="aw3_abc123...", # or AW3_TOKEN env var
|
|
60
|
+
timeout=30.0, # default: 30s
|
|
61
|
+
max_retries=3, # default: 3 (exponential backoff on 5xx)
|
|
62
|
+
)
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The client can also be used as a context manager:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
with AW3Client(token="aw3_...") as client:
|
|
69
|
+
deployment = client.deploy("svc-abc123", wait=True)
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## API Reference
|
|
73
|
+
|
|
74
|
+
### Deployments
|
|
75
|
+
|
|
76
|
+
#### `deploy(service_id, **kwargs)`
|
|
77
|
+
|
|
78
|
+
Trigger a deployment.
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
deployment = client.deploy(
|
|
82
|
+
service_id="svc-abc123",
|
|
83
|
+
commit_sha="a1b2c3d", # optional git commit SHA
|
|
84
|
+
commit_message="fix: auth bug", # optional audit message
|
|
85
|
+
branch="main", # optional branch override
|
|
86
|
+
strategy="canary", # "standard" | "blue-green" | "canary"
|
|
87
|
+
canary_percent=5, # initial canary traffic %
|
|
88
|
+
wait=True, # block until terminal state
|
|
89
|
+
poll_interval=2.0, # polling interval in seconds
|
|
90
|
+
timeout_minutes=30.0, # max wait time
|
|
91
|
+
)
|
|
92
|
+
print(deployment.id) # "dep-abc123"
|
|
93
|
+
print(deployment.status) # "RUNNING"
|
|
94
|
+
print(deployment.deploy_url)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**Deployment statuses:** `PENDING`, `BUILDING`, `DEPLOYING`, `RUNNING`, `FAILED`, `CANCELLED`, `ROLLED_BACK`
|
|
98
|
+
|
|
99
|
+
#### `get_deployment(deployment_id)`
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
deployment = client.get_deployment("dep-abc123")
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
#### `list_deployments(service_id=None, limit=20, status=None)`
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
deployments = client.list_deployments(service_id="svc-abc123", limit=10)
|
|
109
|
+
for d in deployments:
|
|
110
|
+
print(f"{d.id}: {d.status}")
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
#### `rollback(service_id, target_deployment_id=None)`
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
# Roll back to the last successful deployment
|
|
117
|
+
deployment = client.rollback("svc-abc123")
|
|
118
|
+
|
|
119
|
+
# Roll back to a specific deployment
|
|
120
|
+
deployment = client.rollback("svc-abc123", target_deployment_id="dep-xyz789")
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Logs
|
|
124
|
+
|
|
125
|
+
#### `get_logs(service_id, deployment_id=None, lines=100)`
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
logs = client.get_logs("svc-abc123", lines=50)
|
|
129
|
+
for log in logs:
|
|
130
|
+
print(f"[{log.timestamp}] {log.level.upper()}: {log.message}")
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
#### `stream_logs(service_id, deployment_id=None, follow=True)`
|
|
134
|
+
|
|
135
|
+
Streams logs as a generator. Uses SSE when available, falls back to polling.
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
for log in client.stream_logs("svc-abc123"):
|
|
139
|
+
print(f"[{log.timestamp}] {log.message}")
|
|
140
|
+
if log.message == "Deployment complete":
|
|
141
|
+
break
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Services
|
|
145
|
+
|
|
146
|
+
#### `list_services(project_id=None, limit=50)`
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
services = client.list_services(project_id="proj-abc123")
|
|
150
|
+
for svc in services:
|
|
151
|
+
print(f"{svc.name} ({svc.id}): {svc.status}")
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
#### `get_service(service_id)`
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
service = client.get_service("svc-abc123")
|
|
158
|
+
print(service.deploy_url)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
#### `get_status(service_id)`
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
status = client.get_status("svc-abc123")
|
|
165
|
+
print(status["status"]) # "RUNNING"
|
|
166
|
+
print(status["deployUrl"]) # the provider URL of the latest deploy
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Error Handling
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
from aw3_sdk import AW3Client, AW3Error
|
|
173
|
+
|
|
174
|
+
client = AW3Client(token="aw3_...")
|
|
175
|
+
|
|
176
|
+
try:
|
|
177
|
+
deployment = client.deploy("svc-abc123", wait=True)
|
|
178
|
+
except AW3Error as e:
|
|
179
|
+
print(f"API error {e.status_code}: {e.message}")
|
|
180
|
+
if e.status_code == 401:
|
|
181
|
+
print("Invalid or expired token")
|
|
182
|
+
elif e.status_code == 404:
|
|
183
|
+
print("Service not found")
|
|
184
|
+
elif e.status_code == 429:
|
|
185
|
+
print("Rate limit exceeded")
|
|
186
|
+
except TimeoutError as e:
|
|
187
|
+
print(f"Deployment timed out: {e}")
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The client automatically retries on `5xx` server errors and network failures up to `max_retries` times with exponential backoff (`1s`, `2s`, `4s`, ...). Client errors (`4xx`) are never retried.
|
|
191
|
+
|
|
192
|
+
## Data Classes
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
@dataclass
|
|
196
|
+
class Deployment:
|
|
197
|
+
id: str
|
|
198
|
+
service_id: str
|
|
199
|
+
status: str
|
|
200
|
+
created_at: str
|
|
201
|
+
deploy_url: Optional[str]
|
|
202
|
+
commit_sha: Optional[str]
|
|
203
|
+
commit_message: Optional[str]
|
|
204
|
+
image_tag: Optional[str]
|
|
205
|
+
error: Optional[str]
|
|
206
|
+
branch: Optional[str]
|
|
207
|
+
raw: Dict[str, Any] # original API response
|
|
208
|
+
|
|
209
|
+
@dataclass
|
|
210
|
+
class Service:
|
|
211
|
+
id: str
|
|
212
|
+
name: str
|
|
213
|
+
type: str
|
|
214
|
+
status: Optional[str]
|
|
215
|
+
deploy_url: Optional[str]
|
|
216
|
+
last_deployed_at: Optional[str]
|
|
217
|
+
raw: Dict[str, Any]
|
|
218
|
+
|
|
219
|
+
@dataclass
|
|
220
|
+
class LogLine:
|
|
221
|
+
timestamp: str
|
|
222
|
+
message: str
|
|
223
|
+
level: str # "info" | "warn" | "error" | "debug"
|
|
224
|
+
service_id: Optional[str]
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## CI/CD Example
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
import os
|
|
231
|
+
from aw3_sdk import AW3Client, AW3Error
|
|
232
|
+
|
|
233
|
+
client = AW3Client(token=os.environ["AW3_TOKEN"])
|
|
234
|
+
|
|
235
|
+
try:
|
|
236
|
+
# Deploy as canary at 5%
|
|
237
|
+
deployment = client.deploy(
|
|
238
|
+
service_id=os.environ["SERVICE_ID"],
|
|
239
|
+
commit_sha=os.environ.get("GITHUB_SHA"),
|
|
240
|
+
strategy="canary",
|
|
241
|
+
canary_percent=5,
|
|
242
|
+
wait=True,
|
|
243
|
+
)
|
|
244
|
+
print(f"Canary deployed: {deployment.id}")
|
|
245
|
+
|
|
246
|
+
# Stream logs
|
|
247
|
+
print("Streaming logs...")
|
|
248
|
+
for log in client.stream_logs(os.environ["SERVICE_ID"], follow=False):
|
|
249
|
+
print(f" {log.message}")
|
|
250
|
+
|
|
251
|
+
except AW3Error as e:
|
|
252
|
+
print(f"Deployment failed: {e}")
|
|
253
|
+
# Optionally roll back
|
|
254
|
+
rollback = client.rollback(os.environ["SERVICE_ID"])
|
|
255
|
+
print(f"Rolled back to: {rollback.id}")
|
|
256
|
+
raise SystemExit(1)
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## Environment Variables
|
|
260
|
+
|
|
261
|
+
| Variable | Description |
|
|
262
|
+
|----------|-------------|
|
|
263
|
+
| `AW3_TOKEN` | API authentication token |
|
|
264
|
+
| `AW3_BASE_URL` | API base URL (default: `https://app.aw3.host/api`) |
|
|
265
|
+
|
|
266
|
+
## License
|
|
267
|
+
|
|
268
|
+
MIT
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
aw3_sdk/__init__.py,sha256=-lI2d_0Bbe1_qd41RvoIGZnxztopgf6BV2R6WljsYkY,16698
|
|
2
|
+
aw3_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
3
|
+
aw3_sdk-1.0.0.dist-info/METADATA,sha256=8-9lPVKhUGD7_22LKjjJyw5V_LqSVaQCAB66ZY19NjE,7002
|
|
4
|
+
aw3_sdk-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
5
|
+
aw3_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=CB7h3RePiY-HWsoJg-I5Na5L8BtpFZNIuQ77xcz5w04,1077
|
|
6
|
+
aw3_sdk-1.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AW3 Technology, Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|