atli 0.6.0__tar.gz → 0.7.0__tar.gz
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-0.6.0 → atli-0.7.0}/PKG-INFO +1 -1
- {atli-0.6.0 → atli-0.7.0}/src/atli/__init__.py +1 -1
- atli-0.7.0/src/atli/client.py +553 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/client.py +331 -1
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/commands.py +287 -1
- {atli-0.6.0 → atli-0.7.0}/src/atli/skills/atli-jira/SKILL.md +48 -4
- {atli-0.6.0 → atli-0.7.0}/src/atli/skills/using-atli/SKILL.md +4 -3
- atli-0.7.0/tests/test_client_download.py +635 -0
- atli-0.7.0/tests/test_jira_attachment_ops.py +1486 -0
- atli-0.6.0/src/atli/client.py +0 -153
- {atli-0.6.0 → atli-0.7.0}/.gitignore +0 -0
- {atli-0.6.0 → atli-0.7.0}/CHANGELOG.md +0 -0
- {atli-0.6.0 → atli-0.7.0}/LICENSE +0 -0
- {atli-0.6.0 → atli-0.7.0}/README.md +0 -0
- {atli-0.6.0 → atli-0.7.0}/pyproject.toml +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/__main__.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/cli.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/commands_util.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/config.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/config_commands.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/confluence/__init__.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/confluence/client.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/confluence/commands.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/confluence/markdown.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/__init__.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/agile.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/agile_commands.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/body.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/fields.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/jira/jql.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/output.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/skills/atli-confluence/SKILL.md +0 -0
- {atli-0.6.0 → atli-0.7.0}/src/atli/skills_commands.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/__init__.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_client.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_config.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_config_commands.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_confluence.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_confluence_attach.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_confluence_attachment_dl.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_confluence_labels.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_confluence_property.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_confluence_space.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_followup_fixes.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_integration.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira_agile.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira_attachments.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira_bulk_meta.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira_fields.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira_helpers.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira_jql.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_jira_p3.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_markdown.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_review_findings.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_skills.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_sprint_move_search.py +0 -0
- {atli-0.6.0 → atli-0.7.0}/tests/test_stage5_features.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: atli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.0
|
|
4
4
|
Summary: Lightweight CLI for self-hosted Jira and Confluence (Server / Data Center)
|
|
5
5
|
Project-URL: Homepage, https://github.com/yuanyuan06/atli-kit
|
|
6
6
|
Project-URL: Repository, https://github.com/yuanyuan06/atli-kit
|
|
@@ -0,0 +1,553 @@
|
|
|
1
|
+
"""Base HTTP client for Atlassian REST APIs.
|
|
2
|
+
|
|
3
|
+
Wraps `httpx.Client` with bearer-token auth, JSON content type, and
|
|
4
|
+
exception wrapping that turns HTTPStatusError into a friendly
|
|
5
|
+
`AtlassianAPIError` so command code can show clean errors instead of
|
|
6
|
+
tracebacks.
|
|
7
|
+
|
|
8
|
+
`download_to` is the one non-JSON operation: it streams a binary body into a
|
|
9
|
+
file. It lives here because the rules it enforces (same origin, no overwrite)
|
|
10
|
+
are properties of the transport, not of any one product's endpoint.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import os
|
|
16
|
+
import secrets
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
from typing import Any
|
|
19
|
+
from urllib.parse import SplitResult, urljoin, urlsplit, urlunsplit
|
|
20
|
+
|
|
21
|
+
import httpx
|
|
22
|
+
|
|
23
|
+
# Attachment downloads are transfers, not calls: keep each network phase
|
|
24
|
+
# generous while still bounding a socket that stops making progress.
|
|
25
|
+
_DOWNLOAD_TIMEOUT = 120.0
|
|
26
|
+
_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
|
|
27
|
+
# Jira redirects attachment content to its own login/error flows; a handful of
|
|
28
|
+
# hops is normal, an unbounded chain is a loop.
|
|
29
|
+
_MAX_REDIRECTS = 5
|
|
30
|
+
_CHUNK_SIZE = 64 * 1024
|
|
31
|
+
_TEMP_PREFIX = ".atli-download-"
|
|
32
|
+
_DEFAULT_PORTS = {"http": 80, "https": 443}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class AtlassianAPIError(Exception):
|
|
36
|
+
"""Raised when an Atlassian REST call returns a non-2xx response."""
|
|
37
|
+
|
|
38
|
+
def __init__(self, status: int, message: str, url: str = "") -> None:
|
|
39
|
+
super().__init__(f"HTTP {status}: {message} ({url})" if url else f"HTTP {status}: {message}")
|
|
40
|
+
self.status = status
|
|
41
|
+
self.message = message
|
|
42
|
+
self.url = url
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class DownloadRefused(Exception):
|
|
46
|
+
"""Raised when a download must not be attempted, saved, or completed.
|
|
47
|
+
|
|
48
|
+
Covers URL policy refusals (foreign origin, credentials in the URL,
|
|
49
|
+
non-HTTP scheme), HTML login pages, and a destination that already exists.
|
|
50
|
+
No final file is created when this is raised, and the caller can report a
|
|
51
|
+
definite failure rather than an unconfirmed outcome; the temporary file is
|
|
52
|
+
removed best-effort and named in the error if it survives.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class DownloadCleanupFailed(Exception):
|
|
57
|
+
"""Raised when a committed download's temporary file could not be removed.
|
|
58
|
+
|
|
59
|
+
``destination`` holds the downloaded bytes and is the user's file now, so
|
|
60
|
+
the caller must leave it alone and report the item as committed-but-not-
|
|
61
|
+
cleaned-up rather than as a failure that saved nothing. That path is the one
|
|
62
|
+
this call committed; another process may have replaced it since.
|
|
63
|
+
``temporary`` is the leftover name in the same directory, ``reason`` the
|
|
64
|
+
filesystem error, and ``size`` the bytes written to ``destination``.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
def __init__(self, destination: Path, temporary: Path, reason: str, size: int) -> None:
|
|
68
|
+
super().__init__(
|
|
69
|
+
f"{destination} was written, but the temporary file {temporary} could not "
|
|
70
|
+
f"be removed ({reason}); the file is committed and the temporary name "
|
|
71
|
+
"must be removed manually"
|
|
72
|
+
)
|
|
73
|
+
self.destination = destination
|
|
74
|
+
self.temporary = temporary
|
|
75
|
+
self.reason = reason
|
|
76
|
+
self.size = size
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class AtlassianClient:
|
|
80
|
+
"""Thin HTTP wrapper for Jira / Confluence REST APIs.
|
|
81
|
+
|
|
82
|
+
`base_url` should be the host root (e.g. `https://jira.company.com`),
|
|
83
|
+
and each method takes the API path (e.g. `/rest/api/2/issue/PROJ-1`).
|
|
84
|
+
"""
|
|
85
|
+
|
|
86
|
+
def __init__(
|
|
87
|
+
self,
|
|
88
|
+
base_url: str,
|
|
89
|
+
token: str,
|
|
90
|
+
*,
|
|
91
|
+
timeout: float = 30.0,
|
|
92
|
+
client: httpx.Client | None = None,
|
|
93
|
+
) -> None:
|
|
94
|
+
if not base_url or not token:
|
|
95
|
+
raise ValueError("base_url and token must be non-empty")
|
|
96
|
+
self.base_url = base_url.rstrip("/")
|
|
97
|
+
self.token = token
|
|
98
|
+
self._owned_client = client is None
|
|
99
|
+
self.client = client or httpx.Client(
|
|
100
|
+
headers={
|
|
101
|
+
"Authorization": f"Bearer {token}",
|
|
102
|
+
"Content-Type": "application/json",
|
|
103
|
+
"Accept": "application/json",
|
|
104
|
+
},
|
|
105
|
+
timeout=timeout,
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
def close(self) -> None:
|
|
109
|
+
if self._owned_client:
|
|
110
|
+
self.client.close()
|
|
111
|
+
|
|
112
|
+
def __enter__(self) -> "AtlassianClient":
|
|
113
|
+
return self
|
|
114
|
+
|
|
115
|
+
def __exit__(self, *exc_info: Any) -> None:
|
|
116
|
+
self.close()
|
|
117
|
+
|
|
118
|
+
def request(self, method: str, path: str, **kwargs: Any) -> dict:
|
|
119
|
+
url = f"{self.base_url}{path}"
|
|
120
|
+
|
|
121
|
+
# Special handling for file uploads: httpx needs to set Content-Type with boundary.
|
|
122
|
+
# Temporarily remove Content-Type from client headers, let httpx auto-set it,
|
|
123
|
+
# then restore. This is cleaner than trying to merge headers manually.
|
|
124
|
+
if "files" in kwargs:
|
|
125
|
+
original_content_type = self.client.headers.get("content-type")
|
|
126
|
+
if original_content_type:
|
|
127
|
+
del self.client.headers["content-type"]
|
|
128
|
+
try:
|
|
129
|
+
resp = self.client.request(method, url, **kwargs)
|
|
130
|
+
except httpx.RequestError as e:
|
|
131
|
+
raise AtlassianAPIError(0, f"network error: {e}", url) from e
|
|
132
|
+
finally:
|
|
133
|
+
if original_content_type:
|
|
134
|
+
self.client.headers["content-type"] = original_content_type
|
|
135
|
+
else:
|
|
136
|
+
# Normal request: merge any caller-supplied headers.
|
|
137
|
+
# A value of None means "remove this header".
|
|
138
|
+
extra_headers = kwargs.pop("headers", {})
|
|
139
|
+
if extra_headers:
|
|
140
|
+
headers: dict[str, str] = {}
|
|
141
|
+
for key, value in self.client.headers.items():
|
|
142
|
+
headers[key] = value
|
|
143
|
+
for key, value in extra_headers.items():
|
|
144
|
+
lower_key = key.lower()
|
|
145
|
+
if value is None:
|
|
146
|
+
headers.pop(lower_key, None)
|
|
147
|
+
else:
|
|
148
|
+
headers[lower_key] = value
|
|
149
|
+
kwargs["headers"] = headers
|
|
150
|
+
|
|
151
|
+
try:
|
|
152
|
+
resp = self.client.request(method, url, **kwargs)
|
|
153
|
+
except httpx.RequestError as e:
|
|
154
|
+
raise AtlassianAPIError(0, f"network error: {e}", url) from e
|
|
155
|
+
|
|
156
|
+
# Common response handling: only 2xx is success
|
|
157
|
+
if not (200 <= resp.status_code < 300):
|
|
158
|
+
raise AtlassianAPIError(resp.status_code, _extract_error(resp), url)
|
|
159
|
+
|
|
160
|
+
if not resp.content:
|
|
161
|
+
return {}
|
|
162
|
+
try:
|
|
163
|
+
return resp.json()
|
|
164
|
+
except ValueError:
|
|
165
|
+
# Non-JSON response with 2xx status
|
|
166
|
+
if resp.content.strip():
|
|
167
|
+
# Non-empty non-JSON is unexpected for successful API calls
|
|
168
|
+
raise AtlassianAPIError(
|
|
169
|
+
resp.status_code,
|
|
170
|
+
f"unexpected non-JSON response: {resp.text[:200]}",
|
|
171
|
+
url,
|
|
172
|
+
)
|
|
173
|
+
# Empty body or whitespace-only: treat as empty dict
|
|
174
|
+
return {}
|
|
175
|
+
|
|
176
|
+
def download_to(
|
|
177
|
+
self,
|
|
178
|
+
url: str,
|
|
179
|
+
destination: str | Path,
|
|
180
|
+
*,
|
|
181
|
+
timeout: float = _DOWNLOAD_TIMEOUT,
|
|
182
|
+
) -> int:
|
|
183
|
+
"""Stream ``url`` into ``destination`` and return the bytes written.
|
|
184
|
+
|
|
185
|
+
``url`` may be absolute, root-relative, or relative to ``base_url`` (so
|
|
186
|
+
a Jira context path is preserved). Only the configured origin is ever
|
|
187
|
+
contacted; redirects are followed by hand, one hop at a time, and each
|
|
188
|
+
hop is checked before the next request is sent.
|
|
189
|
+
|
|
190
|
+
The body is streamed into a fresh ``0600`` temporary file inside the
|
|
191
|
+
destination directory and published with a hard link, so an existing
|
|
192
|
+
file — or one created meanwhile — is never replaced. The parent
|
|
193
|
+
directory must exist and must not itself be a symlink.
|
|
194
|
+
|
|
195
|
+
Raises ``DownloadRefused`` for policy refusals, ``AtlassianAPIError``
|
|
196
|
+
for HTTP/transport failures, ``OSError`` for local filesystem failures,
|
|
197
|
+
and ``DownloadCleanupFailed`` when the body was committed but its
|
|
198
|
+
temporary name could not be removed. A failure before the commit leaves
|
|
199
|
+
no final file behind and removes this call's temporary file, naming it
|
|
200
|
+
in the error when even that removal fails; after the commit the final
|
|
201
|
+
file is never removed.
|
|
202
|
+
"""
|
|
203
|
+
target = Path(destination)
|
|
204
|
+
name = _destination_name(target)
|
|
205
|
+
directory_fd = _open_directory(target.parent)
|
|
206
|
+
try:
|
|
207
|
+
# Refused before the transfer, and again by the link below if the
|
|
208
|
+
# name appears while the body is being written.
|
|
209
|
+
_require_absent(directory_fd, name, target)
|
|
210
|
+
response, display = self._open_download(url, timeout)
|
|
211
|
+
try:
|
|
212
|
+
_require_savable(response, display)
|
|
213
|
+
return _write_atomically(response, directory_fd, name, target, display)
|
|
214
|
+
finally:
|
|
215
|
+
response.close()
|
|
216
|
+
finally:
|
|
217
|
+
os.close(directory_fd)
|
|
218
|
+
|
|
219
|
+
def get(self, path: str, **kwargs: Any) -> dict:
|
|
220
|
+
return self.request("GET", path, **kwargs)
|
|
221
|
+
|
|
222
|
+
def post(self, path: str, **kwargs: Any) -> dict:
|
|
223
|
+
return self.request("POST", path, **kwargs)
|
|
224
|
+
|
|
225
|
+
def put(self, path: str, **kwargs: Any) -> dict:
|
|
226
|
+
return self.request("PUT", path, **kwargs)
|
|
227
|
+
|
|
228
|
+
def delete(self, path: str, **kwargs: Any) -> dict:
|
|
229
|
+
return self.request("DELETE", path, **kwargs)
|
|
230
|
+
|
|
231
|
+
# ----------------------------- downloads -----------------------------
|
|
232
|
+
|
|
233
|
+
def _open_download(self, url: str, timeout: float) -> tuple[httpx.Response, str]:
|
|
234
|
+
"""Send the download request, following same-origin redirects by hand.
|
|
235
|
+
|
|
236
|
+
Returns the unread final response plus the URL to quote in messages.
|
|
237
|
+
The caller owns (and must close) the response.
|
|
238
|
+
"""
|
|
239
|
+
current = self._validated_download_url(urljoin(f"{self.base_url}/", url))
|
|
240
|
+
hops = 0
|
|
241
|
+
while True:
|
|
242
|
+
try:
|
|
243
|
+
request = self.client.build_request(
|
|
244
|
+
"GET", current, headers={"accept": "*/*"}, timeout=timeout
|
|
245
|
+
)
|
|
246
|
+
except (httpx.InvalidURL, ValueError) as e:
|
|
247
|
+
raise DownloadRefused(
|
|
248
|
+
f"cannot request download URL {_display_url(current)!r}: {e}"
|
|
249
|
+
) from e
|
|
250
|
+
# The client's default Content-Type describes JSON calls; a GET has
|
|
251
|
+
# no body, and Jira's content endpoint should not see one.
|
|
252
|
+
request.headers.pop("content-type", None)
|
|
253
|
+
try:
|
|
254
|
+
response = self.client.send(request, stream=True, follow_redirects=False)
|
|
255
|
+
except httpx.RequestError as e:
|
|
256
|
+
raise AtlassianAPIError(0, f"network error: {e}", _display_url(current)) from e
|
|
257
|
+
|
|
258
|
+
if response.status_code not in _REDIRECT_STATUSES:
|
|
259
|
+
return response, _display_url(current)
|
|
260
|
+
|
|
261
|
+
location = response.headers.get("location")
|
|
262
|
+
try:
|
|
263
|
+
if not location:
|
|
264
|
+
raise DownloadRefused(
|
|
265
|
+
f"redirect without a Location header from {_display_url(current)}"
|
|
266
|
+
)
|
|
267
|
+
hops += 1
|
|
268
|
+
if hops > _MAX_REDIRECTS:
|
|
269
|
+
raise DownloadRefused(
|
|
270
|
+
f"stopped after {_MAX_REDIRECTS} redirects at {_display_url(current)}"
|
|
271
|
+
)
|
|
272
|
+
# Checked before the next request is built: a foreign hop is
|
|
273
|
+
# never contacted, and the redirect response is already closed.
|
|
274
|
+
current = self._validated_download_url(urljoin(current, location))
|
|
275
|
+
finally:
|
|
276
|
+
response.close()
|
|
277
|
+
|
|
278
|
+
def _validated_download_url(self, candidate: str) -> str:
|
|
279
|
+
"""Return ``candidate`` if it stays on the configured origin."""
|
|
280
|
+
try:
|
|
281
|
+
parts = urlsplit(candidate)
|
|
282
|
+
origin = _origin(parts)
|
|
283
|
+
base_origin = _origin(urlsplit(self.base_url))
|
|
284
|
+
except ValueError as e:
|
|
285
|
+
raise DownloadRefused(
|
|
286
|
+
f"cannot parse download URL {_display_url(candidate)!r}: {e}"
|
|
287
|
+
) from e
|
|
288
|
+
scheme = parts.scheme.lower()
|
|
289
|
+
if scheme not in _DEFAULT_PORTS:
|
|
290
|
+
raise DownloadRefused(
|
|
291
|
+
f"refusing to download from {_display_url(candidate)}: only http(s) is allowed"
|
|
292
|
+
)
|
|
293
|
+
if parts.username is not None or parts.password is not None:
|
|
294
|
+
raise DownloadRefused(
|
|
295
|
+
f"refusing to download from {_display_url(candidate)}: "
|
|
296
|
+
"credentials in the URL are not allowed"
|
|
297
|
+
)
|
|
298
|
+
if origin != base_origin:
|
|
299
|
+
raise DownloadRefused(
|
|
300
|
+
f"refusing to download from {_display_url(candidate)}: "
|
|
301
|
+
f"outside the configured origin {self.base_url}"
|
|
302
|
+
)
|
|
303
|
+
return candidate
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def _origin(parts: SplitResult) -> tuple[str, str, int | None]:
|
|
307
|
+
"""Normalised (scheme, host, effective port) used for same-origin checks.
|
|
308
|
+
|
|
309
|
+
``parts.port`` raises ``ValueError`` for a malformed port, which the caller
|
|
310
|
+
turns into a refusal rather than letting httpx fail later.
|
|
311
|
+
"""
|
|
312
|
+
scheme = parts.scheme.lower()
|
|
313
|
+
port = parts.port
|
|
314
|
+
if port is None:
|
|
315
|
+
port = _DEFAULT_PORTS.get(scheme)
|
|
316
|
+
return scheme, (parts.hostname or "").lower(), port
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
def _display_url(url: str) -> str:
|
|
320
|
+
"""Quote a URL in errors without credentials, query, or fragment.
|
|
321
|
+
|
|
322
|
+
Content URLs can carry signed query parameters, so they must not be
|
|
323
|
+
echoed back into logs.
|
|
324
|
+
"""
|
|
325
|
+
parts = urlsplit(url)
|
|
326
|
+
host = parts.hostname or ""
|
|
327
|
+
try:
|
|
328
|
+
port = parts.port
|
|
329
|
+
except ValueError:
|
|
330
|
+
port = None
|
|
331
|
+
netloc = f"{host}:{port}" if port is not None else host
|
|
332
|
+
return urlunsplit((parts.scheme, netloc, parts.path, "", ""))
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
def _destination_name(target: Path) -> str:
|
|
336
|
+
name = target.name
|
|
337
|
+
if not name or name in {".", ".."}:
|
|
338
|
+
raise DownloadRefused(f"invalid destination path: {target}")
|
|
339
|
+
return name
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
def _open_directory(path: Path) -> int:
|
|
343
|
+
"""Pin the destination directory, refusing a symlinked final component."""
|
|
344
|
+
flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
|
|
345
|
+
try:
|
|
346
|
+
return os.open(path, flags)
|
|
347
|
+
except OSError as e:
|
|
348
|
+
raise DownloadRefused(
|
|
349
|
+
f"cannot use {path} as a download directory: {e.strerror or e}"
|
|
350
|
+
) from e
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def _require_absent(directory_fd: int, name: str, target: Path) -> None:
|
|
354
|
+
try:
|
|
355
|
+
os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
|
|
356
|
+
except FileNotFoundError:
|
|
357
|
+
return
|
|
358
|
+
raise DownloadRefused(f"destination already exists, refusing to overwrite: {target}")
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
def _require_savable(response: httpx.Response, display: str) -> None:
|
|
362
|
+
if not (200 <= response.status_code < 300):
|
|
363
|
+
# Error bodies are small and _extract_error needs them; the stream is
|
|
364
|
+
# closed by the caller either way. Reading can fail on its own (the
|
|
365
|
+
# server aborted after the headers), which must stay a normal item
|
|
366
|
+
# failure instead of escaping the per-item handling in the caller.
|
|
367
|
+
try:
|
|
368
|
+
response.read()
|
|
369
|
+
except httpx.RequestError as e:
|
|
370
|
+
raise AtlassianAPIError(
|
|
371
|
+
response.status_code,
|
|
372
|
+
f"could not read the error response body: {e}",
|
|
373
|
+
display,
|
|
374
|
+
) from e
|
|
375
|
+
raise AtlassianAPIError(response.status_code, _extract_error(response), display)
|
|
376
|
+
media_type = response.headers.get("content-type", "").split(";")[0].strip().lower()
|
|
377
|
+
if media_type == "text/html":
|
|
378
|
+
# The usual cause is a PAT that Jira redirected to its login page; saving
|
|
379
|
+
# that page as the attachment would look like a successful download.
|
|
380
|
+
raise DownloadRefused(
|
|
381
|
+
f"refusing to save {display}: the server answered with an HTML page "
|
|
382
|
+
"(Content-Type: text/html), typically a login or error page"
|
|
383
|
+
)
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
def _declared_length(response: httpx.Response) -> int | None:
|
|
387
|
+
"""Content-Length in bytes, when it describes the body we are writing."""
|
|
388
|
+
encoding = response.headers.get("content-encoding", "identity").strip().lower()
|
|
389
|
+
if encoding not in {"", "identity"}:
|
|
390
|
+
return None
|
|
391
|
+
raw = response.headers.get("content-length")
|
|
392
|
+
if raw is None:
|
|
393
|
+
return None
|
|
394
|
+
try:
|
|
395
|
+
value = int(raw)
|
|
396
|
+
except ValueError:
|
|
397
|
+
return None
|
|
398
|
+
return value if value >= 0 else None
|
|
399
|
+
|
|
400
|
+
|
|
401
|
+
def _write_atomically(
|
|
402
|
+
response: httpx.Response,
|
|
403
|
+
directory_fd: int,
|
|
404
|
+
name: str,
|
|
405
|
+
target: Path,
|
|
406
|
+
display: str,
|
|
407
|
+
) -> int:
|
|
408
|
+
"""Stream into a temporary file, then publish it without overwriting."""
|
|
409
|
+
expected = _declared_length(response)
|
|
410
|
+
temp_name = f"{_TEMP_PREFIX}{secrets.token_hex(8)}.part"
|
|
411
|
+
fd = os.open(
|
|
412
|
+
temp_name,
|
|
413
|
+
os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
|
|
414
|
+
0o600,
|
|
415
|
+
dir_fd=directory_fd,
|
|
416
|
+
)
|
|
417
|
+
try:
|
|
418
|
+
written = _copy_body(fd, response, display)
|
|
419
|
+
if expected is not None and written != expected:
|
|
420
|
+
raise AtlassianAPIError(
|
|
421
|
+
0, f"download truncated: expected {expected} bytes, got {written}", display
|
|
422
|
+
)
|
|
423
|
+
_publish(directory_fd, temp_name, name, target)
|
|
424
|
+
except BaseException as exc:
|
|
425
|
+
# Nothing was committed: drop this call's temporary name only, and keep
|
|
426
|
+
# the original error class so the caller's failure classification
|
|
427
|
+
# (failed vs unconfirmed) is untouched.
|
|
428
|
+
_discard_temporary(directory_fd, temp_name, target, exc)
|
|
429
|
+
raise
|
|
430
|
+
# Committed: the link left the same inode under two names.
|
|
431
|
+
_drop_temporary(directory_fd, temp_name, target, written)
|
|
432
|
+
return written
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
def _copy_body(fd: int, response: httpx.Response, display: str) -> int:
|
|
436
|
+
written = 0
|
|
437
|
+
try:
|
|
438
|
+
with os.fdopen(fd, "wb") as handle:
|
|
439
|
+
for chunk in response.iter_bytes(_CHUNK_SIZE):
|
|
440
|
+
handle.write(chunk)
|
|
441
|
+
written += len(chunk)
|
|
442
|
+
except httpx.RequestError as e:
|
|
443
|
+
raise AtlassianAPIError(0, f"download interrupted: {e}", display) from e
|
|
444
|
+
return written
|
|
445
|
+
|
|
446
|
+
|
|
447
|
+
def _publish(directory_fd: int, temp_name: str, name: str, target: Path) -> None:
|
|
448
|
+
"""Give the finished temporary file its final name, never replacing one."""
|
|
449
|
+
try:
|
|
450
|
+
os.link(
|
|
451
|
+
temp_name,
|
|
452
|
+
name,
|
|
453
|
+
src_dir_fd=directory_fd,
|
|
454
|
+
dst_dir_fd=directory_fd,
|
|
455
|
+
follow_symlinks=False,
|
|
456
|
+
)
|
|
457
|
+
except FileExistsError as e:
|
|
458
|
+
raise DownloadRefused(f"destination already exists, refusing to overwrite: {target}") from e
|
|
459
|
+
except OSError as e:
|
|
460
|
+
raise DownloadRefused(
|
|
461
|
+
f"cannot publish {target} atomically (hard link failed: {e.strerror or e}); "
|
|
462
|
+
"this filesystem may not support hard links"
|
|
463
|
+
) from e
|
|
464
|
+
|
|
465
|
+
|
|
466
|
+
def _drop_temporary(directory_fd: int, temp_name: str, target: Path, size: int) -> None:
|
|
467
|
+
"""Remove the temporary name of a committed download.
|
|
468
|
+
|
|
469
|
+
The committed file is the only durable result of this call and is never
|
|
470
|
+
removed here: another process may have replaced that name since the link,
|
|
471
|
+
and a ``stat`` followed by ``unlink`` is two separate steps, so a check
|
|
472
|
+
cannot make the removal safe. A failure therefore keeps the file and raises
|
|
473
|
+
``DownloadCleanupFailed`` naming the destination, the leftover temporary
|
|
474
|
+
path, and the filesystem reason.
|
|
475
|
+
"""
|
|
476
|
+
try:
|
|
477
|
+
os.unlink(temp_name, dir_fd=directory_fd)
|
|
478
|
+
except FileNotFoundError:
|
|
479
|
+
return
|
|
480
|
+
except OSError as cleanup_error:
|
|
481
|
+
raise DownloadCleanupFailed(
|
|
482
|
+
target,
|
|
483
|
+
target.parent / temp_name,
|
|
484
|
+
cleanup_error.strerror or str(cleanup_error),
|
|
485
|
+
size,
|
|
486
|
+
) from cleanup_error
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
def _discard_temporary(
|
|
490
|
+
directory_fd: int, temp_name: str, target: Path, cause: BaseException
|
|
491
|
+
) -> None:
|
|
492
|
+
"""Remove the temporary name of a download that was never committed.
|
|
493
|
+
|
|
494
|
+
The caller re-raises ``cause`` whatever happens here. When the temporary
|
|
495
|
+
file survives, its path is added to ``cause``'s message while the class
|
|
496
|
+
stays the same, so a 5xx stays ``unconfirmed`` rather than becoming a plain
|
|
497
|
+
local error.
|
|
498
|
+
"""
|
|
499
|
+
try:
|
|
500
|
+
os.unlink(temp_name, dir_fd=directory_fd)
|
|
501
|
+
except FileNotFoundError:
|
|
502
|
+
return
|
|
503
|
+
except OSError as cleanup_error:
|
|
504
|
+
_note_leftover(
|
|
505
|
+
cause,
|
|
506
|
+
target.parent / temp_name,
|
|
507
|
+
cleanup_error.strerror or str(cleanup_error),
|
|
508
|
+
)
|
|
509
|
+
|
|
510
|
+
|
|
511
|
+
def _note_leftover(cause: BaseException, temporary: Path, reason: str) -> None:
|
|
512
|
+
"""Append a surviving temporary path to ``cause``'s message in place.
|
|
513
|
+
|
|
514
|
+
``add_note`` is Python 3.11+, and this package supports 3.10, so the note
|
|
515
|
+
goes into the exception's own message. An ``OSError`` renders ``strerror``,
|
|
516
|
+
not ``args``, so both are updated for the note to reach ``str(exc)``; the
|
|
517
|
+
errno, ``filename``/``filename2`` attributes and the class stay untouched,
|
|
518
|
+
keeping the caller's failed/unconfirmed classification.
|
|
519
|
+
"""
|
|
520
|
+
note = (
|
|
521
|
+
f"the temporary file {temporary} could not be removed ({reason}); "
|
|
522
|
+
"it must be removed manually"
|
|
523
|
+
)
|
|
524
|
+
if isinstance(cause, OSError) and cause.errno is not None:
|
|
525
|
+
cause.strerror = f"{cause.strerror}; {note}" if cause.strerror else note
|
|
526
|
+
extra = cause.args[2:] if cause.args[:1] == (cause.errno,) else ()
|
|
527
|
+
cause.args = (cause.errno, cause.strerror, *extra)
|
|
528
|
+
return
|
|
529
|
+
args = cause.args
|
|
530
|
+
if len(args) == 1 and isinstance(args[0], str):
|
|
531
|
+
cause.args = (f"{args[0]}; {note}",)
|
|
532
|
+
else:
|
|
533
|
+
cause.args = (*args, note)
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def _extract_error(resp: httpx.Response) -> str:
|
|
537
|
+
"""Pull a useful message out of an Atlassian error response."""
|
|
538
|
+
try:
|
|
539
|
+
data = resp.json()
|
|
540
|
+
except ValueError:
|
|
541
|
+
return resp.text.strip()[:200] or resp.reason_phrase
|
|
542
|
+
|
|
543
|
+
# Atlassian shapes vary: errorMessages list, errors dict, or message field.
|
|
544
|
+
if isinstance(data, dict):
|
|
545
|
+
if msgs := data.get("errorMessages"):
|
|
546
|
+
return "; ".join(str(m) for m in msgs)
|
|
547
|
+
if errors := data.get("errors"):
|
|
548
|
+
if isinstance(errors, dict):
|
|
549
|
+
return "; ".join(f"{k}: {v}" for k, v in errors.items())
|
|
550
|
+
return str(errors)
|
|
551
|
+
if msg := data.get("message"):
|
|
552
|
+
return str(msg)
|
|
553
|
+
return resp.text.strip()[:200] or resp.reason_phrase
|