atli 0.5.1__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.
- atli/__init__.py +3 -0
- atli/__main__.py +6 -0
- atli/cli.py +66 -0
- atli/client.py +153 -0
- atli/commands_util.py +45 -0
- atli/config.py +110 -0
- atli/config_commands.py +256 -0
- atli/confluence/__init__.py +1 -0
- atli/confluence/client.py +422 -0
- atli/confluence/commands.py +1129 -0
- atli/confluence/markdown.py +181 -0
- atli/jira/__init__.py +1 -0
- atli/jira/agile.py +282 -0
- atli/jira/agile_commands.py +454 -0
- atli/jira/body.py +36 -0
- atli/jira/client.py +491 -0
- atli/jira/commands.py +1525 -0
- atli/jira/fields.py +75 -0
- atli/jira/jql.py +69 -0
- atli/output.py +54 -0
- atli/skills/atli-confluence/SKILL.md +173 -0
- atli/skills/atli-jira/SKILL.md +209 -0
- atli/skills/using-atli/SKILL.md +96 -0
- atli/skills_commands.py +144 -0
- atli-0.5.1.dist-info/METADATA +91 -0
- atli-0.5.1.dist-info/RECORD +29 -0
- atli-0.5.1.dist-info/WHEEL +4 -0
- atli-0.5.1.dist-info/entry_points.txt +2 -0
- atli-0.5.1.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,422 @@
|
|
|
1
|
+
"""Confluence REST API client (Server / Data Center)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from atli.client import AtlassianAPIError, AtlassianClient, _extract_error
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class ConfluenceClient(AtlassianClient):
|
|
12
|
+
API = "/rest/api"
|
|
13
|
+
|
|
14
|
+
# ----------------------------- read -----------------------------
|
|
15
|
+
|
|
16
|
+
def find_page(self, space: str, title: str, expand: str = "body.storage,version") -> dict | None:
|
|
17
|
+
"""Return the first page in `space` matching `title`, or None."""
|
|
18
|
+
result = self.get(
|
|
19
|
+
f"{self.API}/content",
|
|
20
|
+
params={"spaceKey": space, "title": title, "expand": expand, "limit": 1},
|
|
21
|
+
)
|
|
22
|
+
results = result.get("results", [])
|
|
23
|
+
return results[0] if results else None
|
|
24
|
+
|
|
25
|
+
def require_page(self, space: str, title: str, expand: str = "body.storage,version") -> dict:
|
|
26
|
+
page = self.find_page(space, title, expand=expand)
|
|
27
|
+
if page is None:
|
|
28
|
+
raise AtlassianAPIError(404, f"page not found: space={space} title={title!r}")
|
|
29
|
+
return page
|
|
30
|
+
|
|
31
|
+
def get_page(self, page_id: str, expand: str = "body.storage,version") -> dict:
|
|
32
|
+
return self.get(f"{self.API}/content/{page_id}", params={"expand": expand})
|
|
33
|
+
|
|
34
|
+
def list_pages(self, space: str, limit: int = 25, start: int = 0) -> dict:
|
|
35
|
+
return self.get(
|
|
36
|
+
f"{self.API}/content",
|
|
37
|
+
params={"spaceKey": space, "type": "page", "limit": limit, "start": start},
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
def search(self, cql: str, limit: int = 25) -> dict:
|
|
41
|
+
return self.get(f"{self.API}/content/search", params={"cql": cql, "limit": limit})
|
|
42
|
+
|
|
43
|
+
def search_pages(
|
|
44
|
+
self,
|
|
45
|
+
*,
|
|
46
|
+
space: str | None = None,
|
|
47
|
+
title: str | None = None,
|
|
48
|
+
label: str | None = None,
|
|
49
|
+
text: str | None = None,
|
|
50
|
+
limit: int = 25,
|
|
51
|
+
) -> dict:
|
|
52
|
+
"""Search pages with convenience filters (builds CQL internally)."""
|
|
53
|
+
parts: list[str] = ["type=page"]
|
|
54
|
+
if space:
|
|
55
|
+
parts.append(f"space={space}")
|
|
56
|
+
if title:
|
|
57
|
+
parts.append(f'title~"{self._escape_cql_string(title)}"')
|
|
58
|
+
if label:
|
|
59
|
+
parts.append(f"label={label}")
|
|
60
|
+
if text:
|
|
61
|
+
parts.append(f'text~"{self._escape_cql_string(text)}"')
|
|
62
|
+
cql = " AND ".join(parts)
|
|
63
|
+
return self.search(cql, limit=limit)
|
|
64
|
+
|
|
65
|
+
@staticmethod
|
|
66
|
+
def _escape_cql_string(value: str) -> str:
|
|
67
|
+
"""Escape quotes and backslashes for CQL string literals."""
|
|
68
|
+
return value.replace("\\", "\\\\").replace('"', '\\"')
|
|
69
|
+
|
|
70
|
+
# ----------------------------- write -----------------------------
|
|
71
|
+
|
|
72
|
+
def create_page(
|
|
73
|
+
self,
|
|
74
|
+
space: str,
|
|
75
|
+
title: str,
|
|
76
|
+
content: str,
|
|
77
|
+
parent_id: str | None = None,
|
|
78
|
+
representation: str = "storage",
|
|
79
|
+
) -> dict:
|
|
80
|
+
payload: dict[str, Any] = {
|
|
81
|
+
"type": "page",
|
|
82
|
+
"title": title,
|
|
83
|
+
"space": {"key": space},
|
|
84
|
+
"body": {representation: {"value": content, "representation": representation}},
|
|
85
|
+
}
|
|
86
|
+
if parent_id:
|
|
87
|
+
payload["ancestors"] = [{"id": parent_id}]
|
|
88
|
+
return self.post(f"{self.API}/content", json=payload)
|
|
89
|
+
|
|
90
|
+
def update_page(
|
|
91
|
+
self,
|
|
92
|
+
page_id: str,
|
|
93
|
+
title: str,
|
|
94
|
+
content: str,
|
|
95
|
+
version: int,
|
|
96
|
+
representation: str = "storage",
|
|
97
|
+
) -> dict:
|
|
98
|
+
payload = {
|
|
99
|
+
"id": page_id,
|
|
100
|
+
"type": "page",
|
|
101
|
+
"title": title,
|
|
102
|
+
"body": {representation: {"value": content, "representation": representation}},
|
|
103
|
+
"version": {"number": version + 1},
|
|
104
|
+
}
|
|
105
|
+
return self.put(f"{self.API}/content/{page_id}", json=payload)
|
|
106
|
+
|
|
107
|
+
def delete_page(self, page_id: str) -> dict:
|
|
108
|
+
"""Soft-delete a page (sends to Confluence trash).
|
|
109
|
+
|
|
110
|
+
Returns an empty dict; HTTP 204 has no body.
|
|
111
|
+
"""
|
|
112
|
+
return self.delete(f"{self.API}/content/{page_id}")
|
|
113
|
+
|
|
114
|
+
# ----------------------------- attachments -----------------------------
|
|
115
|
+
|
|
116
|
+
def list_attachments(self, page_id: str, limit: int = 50) -> dict:
|
|
117
|
+
"""List attachments on a page."""
|
|
118
|
+
return self.get(
|
|
119
|
+
f"{self.API}/content/{page_id}/child/attachment",
|
|
120
|
+
params={"limit": limit},
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
def download_attachment(self, attachment_id: str) -> bytes:
|
|
124
|
+
"""Download an attachment and return raw bytes.
|
|
125
|
+
|
|
126
|
+
Uses the base client's underlying httpx client directly so we can
|
|
127
|
+
get the raw response content without JSON-decoding.
|
|
128
|
+
"""
|
|
129
|
+
url = f"{self.base_url}{self.API}/content/{attachment_id}/download"
|
|
130
|
+
try:
|
|
131
|
+
resp = self.client.get(url)
|
|
132
|
+
except Exception as e:
|
|
133
|
+
from atli.client import AtlassianAPIError
|
|
134
|
+
raise AtlassianAPIError(0, f"network error: {e}", url) from e
|
|
135
|
+
if resp.status_code >= 400:
|
|
136
|
+
from atli.client import _extract_error, AtlassianAPIError
|
|
137
|
+
raise AtlassianAPIError(resp.status_code, _extract_error(resp), url)
|
|
138
|
+
return resp.content
|
|
139
|
+
|
|
140
|
+
def upload_attachment(self, page_id: str, file_path: str) -> dict:
|
|
141
|
+
"""Upload a file as an attachment to a page.
|
|
142
|
+
|
|
143
|
+
Uses multipart/form-data. If an attachment with the same filename
|
|
144
|
+
already exists, Confluence creates a new version.
|
|
145
|
+
|
|
146
|
+
Raises AtlassianAPIError if file is larger than 100 MB.
|
|
147
|
+
"""
|
|
148
|
+
import mimetypes
|
|
149
|
+
|
|
150
|
+
path = Path(file_path)
|
|
151
|
+
if not path.exists():
|
|
152
|
+
raise AtlassianAPIError(0, f"file not found: {file_path}")
|
|
153
|
+
|
|
154
|
+
# Validate file size (100 MB limit)
|
|
155
|
+
file_size = path.stat().st_size
|
|
156
|
+
if file_size > 100 * 1024 * 1024:
|
|
157
|
+
raise AtlassianAPIError(
|
|
158
|
+
400, f"file too large: {file_size} bytes (max 100 MB)"
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
content_type, _ = mimetypes.guess_type(str(path))
|
|
162
|
+
content_type = content_type or "application/octet-stream"
|
|
163
|
+
|
|
164
|
+
# Use the base client's unified request() method with files parameter.
|
|
165
|
+
# The base client will automatically remove Content-Type header for multipart uploads.
|
|
166
|
+
with path.open("rb") as f:
|
|
167
|
+
return self.request(
|
|
168
|
+
"POST",
|
|
169
|
+
f"{self.API}/content/{page_id}/child/attachment",
|
|
170
|
+
headers={"X-Atlassian-Token": "no-check"},
|
|
171
|
+
files={"file": (path.name, f, content_type)},
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
def delete_attachment(self, attachment_id: str) -> dict:
|
|
175
|
+
"""Delete an attachment by its content ID."""
|
|
176
|
+
return self.delete(f"{self.API}/content/{attachment_id}")
|
|
177
|
+
|
|
178
|
+
# ----------------------------- labels -----------------------------
|
|
179
|
+
|
|
180
|
+
def list_labels(self, page_id: str) -> dict:
|
|
181
|
+
"""List all labels on a page."""
|
|
182
|
+
return self.get(f"{self.API}/content/{page_id}/label")
|
|
183
|
+
|
|
184
|
+
def add_labels(self, page_id: str, labels: list[str]) -> dict:
|
|
185
|
+
"""Add one or more labels to a page."""
|
|
186
|
+
payload = [{"prefix": "global", "name": name} for name in labels]
|
|
187
|
+
return self.post(f"{self.API}/content/{page_id}/label", json=payload)
|
|
188
|
+
|
|
189
|
+
def remove_label(self, page_id: str, label: str) -> dict:
|
|
190
|
+
"""Remove a single label from a page by name."""
|
|
191
|
+
return self.delete(
|
|
192
|
+
f"{self.API}/content/{page_id}/label",
|
|
193
|
+
params={"name": label},
|
|
194
|
+
)
|
|
195
|
+
|
|
196
|
+
# ----------------------------- content properties -----------------------------
|
|
197
|
+
|
|
198
|
+
def list_properties(self, page_id: str) -> dict:
|
|
199
|
+
"""List all content properties on a page."""
|
|
200
|
+
return self.get(f"{self.API}/content/{page_id}/property")
|
|
201
|
+
|
|
202
|
+
def get_property(self, page_id: str, key: str) -> dict:
|
|
203
|
+
"""Get a single content property by key."""
|
|
204
|
+
return self.get(f"{self.API}/content/{page_id}/property/{key}")
|
|
205
|
+
|
|
206
|
+
def set_property(self, page_id: str, key: str, value: Any) -> dict:
|
|
207
|
+
"""Create or update a content property (upsert by key).
|
|
208
|
+
|
|
209
|
+
``value`` must be JSON-serialisable. The API requires a version bump
|
|
210
|
+
when updating; we GET first and increment automatically.
|
|
211
|
+
"""
|
|
212
|
+
try:
|
|
213
|
+
existing = self.get_property(page_id, key)
|
|
214
|
+
version = (existing.get("version") or {}).get("number", 0)
|
|
215
|
+
payload = {"key": key, "value": value, "version": {"number": version + 1}}
|
|
216
|
+
return self.put(
|
|
217
|
+
f"{self.API}/content/{page_id}/property/{key}", json=payload
|
|
218
|
+
)
|
|
219
|
+
except AtlassianAPIError as e:
|
|
220
|
+
if e.status == 404:
|
|
221
|
+
# Property doesn't exist yet — create it
|
|
222
|
+
return self.post(
|
|
223
|
+
f"{self.API}/content/{page_id}/property",
|
|
224
|
+
json={"key": key, "value": value},
|
|
225
|
+
)
|
|
226
|
+
raise
|
|
227
|
+
|
|
228
|
+
def delete_property(self, page_id: str, key: str) -> dict:
|
|
229
|
+
"""Delete a content property."""
|
|
230
|
+
return self.delete(f"{self.API}/content/{page_id}/property/{key}")
|
|
231
|
+
|
|
232
|
+
# ----------------------------- spaces -----------------------------
|
|
233
|
+
|
|
234
|
+
def list_spaces(self, limit: int = 100, typ: str | None = None) -> dict:
|
|
235
|
+
"""List all spaces the caller can access."""
|
|
236
|
+
params: dict[str, Any] = {"limit": limit}
|
|
237
|
+
if typ:
|
|
238
|
+
params["type"] = typ
|
|
239
|
+
return self.get(f"{self.API}/space", params=params)
|
|
240
|
+
|
|
241
|
+
def get_space(self, space_key: str) -> dict:
|
|
242
|
+
"""Get details of a single space by key."""
|
|
243
|
+
return self.get(f"{self.API}/space/{space_key}")
|
|
244
|
+
|
|
245
|
+
def create_space(
|
|
246
|
+
self,
|
|
247
|
+
key: str,
|
|
248
|
+
name: str,
|
|
249
|
+
description: str | None = None,
|
|
250
|
+
) -> dict:
|
|
251
|
+
"""Create a new space."""
|
|
252
|
+
payload: dict[str, Any] = {"key": key, "name": name}
|
|
253
|
+
if description:
|
|
254
|
+
payload["description"] = {
|
|
255
|
+
"plain": {"value": description, "representation": "plain"}
|
|
256
|
+
}
|
|
257
|
+
return self.post(f"{self.API}/space", json=payload)
|
|
258
|
+
|
|
259
|
+
def update_space(self, space_key: str, name: str | None = None, description: str | None = None) -> dict:
|
|
260
|
+
"""Update a space's name and/or description."""
|
|
261
|
+
payload: dict[str, Any] = {}
|
|
262
|
+
if name:
|
|
263
|
+
payload["name"] = name
|
|
264
|
+
if description:
|
|
265
|
+
payload["description"] = {
|
|
266
|
+
"plain": {"value": description, "representation": "plain"}
|
|
267
|
+
}
|
|
268
|
+
if not payload:
|
|
269
|
+
raise AtlassianAPIError(400, "provide --name or --description to update")
|
|
270
|
+
return self.put(f"{self.API}/space/{space_key}", json=payload)
|
|
271
|
+
|
|
272
|
+
def delete_space(self, space_key: str) -> dict:
|
|
273
|
+
"""Delete a space and all its content (irreversible)."""
|
|
274
|
+
return self.delete(f"{self.API}/space/{space_key}")
|
|
275
|
+
|
|
276
|
+
# ----------------------------- page hierarchy -----------------------------
|
|
277
|
+
|
|
278
|
+
def get_child_pages(self, page_id: str, limit: int = 100) -> dict:
|
|
279
|
+
"""Return the direct child pages of a page."""
|
|
280
|
+
return self.get(
|
|
281
|
+
f"{self.API}/content/{page_id}/child/page",
|
|
282
|
+
params={"limit": limit},
|
|
283
|
+
)
|
|
284
|
+
|
|
285
|
+
def get_descendants(self, page_id: str, limit: int = 100) -> dict:
|
|
286
|
+
"""Return all descendant pages recursively."""
|
|
287
|
+
return self.get(
|
|
288
|
+
f"{self.API}/content/{page_id}/descendant",
|
|
289
|
+
params={"type": "page", "limit": limit},
|
|
290
|
+
)
|
|
291
|
+
|
|
292
|
+
def move_page(self, page_id: str, new_parent_id: str) -> dict:
|
|
293
|
+
"""Move a page by changing its parent.
|
|
294
|
+
|
|
295
|
+
Fetches current version, increments it, and PUTs with new ancestors.
|
|
296
|
+
"""
|
|
297
|
+
page = self.get_page(page_id, expand="version,ancestors")
|
|
298
|
+
current_version = (page.get("version") or {}).get("number", 1)
|
|
299
|
+
payload = {
|
|
300
|
+
"type": "page",
|
|
301
|
+
"title": page["title"],
|
|
302
|
+
"version": {"number": current_version + 1},
|
|
303
|
+
"ancestors": [{"id": new_parent_id}],
|
|
304
|
+
}
|
|
305
|
+
return self.put(f"{self.API}/content/{page_id}", json=payload)
|
|
306
|
+
|
|
307
|
+
# convenience: upsert by space+title (create if missing, else update)
|
|
308
|
+
def upsert_page(
|
|
309
|
+
self,
|
|
310
|
+
space: str,
|
|
311
|
+
title: str,
|
|
312
|
+
content: str,
|
|
313
|
+
representation: str = "storage",
|
|
314
|
+
parent_id: str | None = None,
|
|
315
|
+
) -> tuple[str, dict]:
|
|
316
|
+
"""Create-or-update a page identified by (space, title).
|
|
317
|
+
|
|
318
|
+
Returns ('created'|'updated', page_dict).
|
|
319
|
+
"""
|
|
320
|
+
existing = self.find_page(space, title)
|
|
321
|
+
if existing is None:
|
|
322
|
+
return "created", self.create_page(
|
|
323
|
+
space=space,
|
|
324
|
+
title=title,
|
|
325
|
+
content=content,
|
|
326
|
+
parent_id=parent_id,
|
|
327
|
+
representation=representation,
|
|
328
|
+
)
|
|
329
|
+
# Defensive: version may be None or missing 'number' key; default to 0.
|
|
330
|
+
version = (existing.get("version") or {}).get("number", 0)
|
|
331
|
+
return "updated", self.update_page(
|
|
332
|
+
page_id=existing["id"],
|
|
333
|
+
title=title,
|
|
334
|
+
content=content,
|
|
335
|
+
version=version,
|
|
336
|
+
representation=representation,
|
|
337
|
+
)
|
|
338
|
+
|
|
339
|
+
# ----------------------------- version history -----------------------------
|
|
340
|
+
|
|
341
|
+
def get_page_versions(self, page_id: str, limit: int = 25) -> dict:
|
|
342
|
+
"""Get version history for a page."""
|
|
343
|
+
return self.get(
|
|
344
|
+
f"{self.API}/content/{page_id}/version",
|
|
345
|
+
params={"limit": limit, "expand": "content"},
|
|
346
|
+
)
|
|
347
|
+
|
|
348
|
+
def get_page_version(self, page_id: str, version_number: int) -> dict:
|
|
349
|
+
"""Get a specific version of a page."""
|
|
350
|
+
return self.get(
|
|
351
|
+
f"{self.API}/content/{page_id}/version/{version_number}",
|
|
352
|
+
params={"expand": "content.view,content.storage"},
|
|
353
|
+
)
|
|
354
|
+
|
|
355
|
+
def restore_page_version(self, page_id: str, version_number: int) -> dict:
|
|
356
|
+
"""Restore a page to a previous version."""
|
|
357
|
+
# Get the old version content
|
|
358
|
+
old_version = self.get_page_version(page_id, version_number)
|
|
359
|
+
old_content = old_version.get("content", {}).get("storage", {}).get("value", "")
|
|
360
|
+
|
|
361
|
+
# Get current page to get latest version number
|
|
362
|
+
current = self.get_page(page_id, expand="version")
|
|
363
|
+
current_version = current.get("version", {}).get("number", 0)
|
|
364
|
+
title = current.get("title", "")
|
|
365
|
+
|
|
366
|
+
# Update to old content with current version (update_page will increment)
|
|
367
|
+
return self.update_page(
|
|
368
|
+
page_id=page_id,
|
|
369
|
+
title=title,
|
|
370
|
+
content=old_content,
|
|
371
|
+
version=current_version,
|
|
372
|
+
representation="storage",
|
|
373
|
+
)
|
|
374
|
+
|
|
375
|
+
# ----------------------------- permissions -----------------------------
|
|
376
|
+
|
|
377
|
+
def get_page_restrictions(self, page_id: str) -> dict:
|
|
378
|
+
"""Get page restrictions (permissions)."""
|
|
379
|
+
return self.get(
|
|
380
|
+
f"{self.API}/content/{page_id}/restriction",
|
|
381
|
+
params={"expand": "read.restrictions.user,read.restrictions.group,"
|
|
382
|
+
"update.restrictions.user,update.restrictions.group"},
|
|
383
|
+
)
|
|
384
|
+
|
|
385
|
+
def get_space_permissions(self, space_key: str) -> dict:
|
|
386
|
+
"""Get space-level permissions."""
|
|
387
|
+
return self.get(f"{self.API}/space/{space_key}", params={"expand": "permissions"})
|
|
388
|
+
|
|
389
|
+
# ----------------------------- export -----------------------------
|
|
390
|
+
|
|
391
|
+
def export_space_pages(self, space_key: str, limit: int = 1000) -> list[dict]:
|
|
392
|
+
"""Get all pages in a space for export."""
|
|
393
|
+
all_pages = []
|
|
394
|
+
start = 0
|
|
395
|
+
page_limit = min(limit, 100) # API max per request
|
|
396
|
+
|
|
397
|
+
while len(all_pages) < limit:
|
|
398
|
+
result = self.get(
|
|
399
|
+
f"{self.API}/content",
|
|
400
|
+
params={
|
|
401
|
+
"spaceKey": space_key,
|
|
402
|
+
"type": "page",
|
|
403
|
+
"limit": page_limit,
|
|
404
|
+
"start": start,
|
|
405
|
+
"expand": "body.storage,version",
|
|
406
|
+
},
|
|
407
|
+
)
|
|
408
|
+
pages = result.get("results", [])
|
|
409
|
+
if not pages:
|
|
410
|
+
break
|
|
411
|
+
all_pages.extend(pages)
|
|
412
|
+
|
|
413
|
+
# Check if there are more pages based on response metadata
|
|
414
|
+
size = result.get("size", len(pages))
|
|
415
|
+
is_last = len(pages) < size or result.get("_links", {}).get("next") is None
|
|
416
|
+
if is_last:
|
|
417
|
+
break
|
|
418
|
+
|
|
419
|
+
start += len(pages)
|
|
420
|
+
|
|
421
|
+
return all_pages[:limit]
|
|
422
|
+
|