atli 0.5.1__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.
Files changed (58) hide show
  1. {atli-0.5.1 → atli-0.7.0}/PKG-INFO +1 -1
  2. {atli-0.5.1 → atli-0.7.0}/src/atli/__init__.py +1 -1
  3. atli-0.7.0/src/atli/client.py +553 -0
  4. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/client.py +431 -1
  5. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/commands.py +333 -1
  6. {atli-0.5.1 → atli-0.7.0}/src/atli/skills/atli-jira/SKILL.md +63 -1
  7. {atli-0.5.1 → atli-0.7.0}/src/atli/skills/using-atli/SKILL.md +4 -3
  8. atli-0.7.0/tests/test_client_download.py +635 -0
  9. atli-0.7.0/tests/test_jira_attachment_ops.py +1486 -0
  10. atli-0.7.0/tests/test_jira_attachments.py +581 -0
  11. atli-0.5.1/src/atli/client.py +0 -153
  12. {atli-0.5.1 → atli-0.7.0}/.gitignore +0 -0
  13. {atli-0.5.1 → atli-0.7.0}/CHANGELOG.md +0 -0
  14. {atli-0.5.1 → atli-0.7.0}/LICENSE +0 -0
  15. {atli-0.5.1 → atli-0.7.0}/README.md +0 -0
  16. {atli-0.5.1 → atli-0.7.0}/pyproject.toml +0 -0
  17. {atli-0.5.1 → atli-0.7.0}/src/atli/__main__.py +0 -0
  18. {atli-0.5.1 → atli-0.7.0}/src/atli/cli.py +0 -0
  19. {atli-0.5.1 → atli-0.7.0}/src/atli/commands_util.py +0 -0
  20. {atli-0.5.1 → atli-0.7.0}/src/atli/config.py +0 -0
  21. {atli-0.5.1 → atli-0.7.0}/src/atli/config_commands.py +0 -0
  22. {atli-0.5.1 → atli-0.7.0}/src/atli/confluence/__init__.py +0 -0
  23. {atli-0.5.1 → atli-0.7.0}/src/atli/confluence/client.py +0 -0
  24. {atli-0.5.1 → atli-0.7.0}/src/atli/confluence/commands.py +0 -0
  25. {atli-0.5.1 → atli-0.7.0}/src/atli/confluence/markdown.py +0 -0
  26. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/__init__.py +0 -0
  27. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/agile.py +0 -0
  28. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/agile_commands.py +0 -0
  29. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/body.py +0 -0
  30. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/fields.py +0 -0
  31. {atli-0.5.1 → atli-0.7.0}/src/atli/jira/jql.py +0 -0
  32. {atli-0.5.1 → atli-0.7.0}/src/atli/output.py +0 -0
  33. {atli-0.5.1 → atli-0.7.0}/src/atli/skills/atli-confluence/SKILL.md +0 -0
  34. {atli-0.5.1 → atli-0.7.0}/src/atli/skills_commands.py +0 -0
  35. {atli-0.5.1 → atli-0.7.0}/tests/__init__.py +0 -0
  36. {atli-0.5.1 → atli-0.7.0}/tests/test_client.py +0 -0
  37. {atli-0.5.1 → atli-0.7.0}/tests/test_config.py +0 -0
  38. {atli-0.5.1 → atli-0.7.0}/tests/test_config_commands.py +0 -0
  39. {atli-0.5.1 → atli-0.7.0}/tests/test_confluence.py +0 -0
  40. {atli-0.5.1 → atli-0.7.0}/tests/test_confluence_attach.py +0 -0
  41. {atli-0.5.1 → atli-0.7.0}/tests/test_confluence_attachment_dl.py +0 -0
  42. {atli-0.5.1 → atli-0.7.0}/tests/test_confluence_labels.py +0 -0
  43. {atli-0.5.1 → atli-0.7.0}/tests/test_confluence_property.py +0 -0
  44. {atli-0.5.1 → atli-0.7.0}/tests/test_confluence_space.py +0 -0
  45. {atli-0.5.1 → atli-0.7.0}/tests/test_followup_fixes.py +0 -0
  46. {atli-0.5.1 → atli-0.7.0}/tests/test_integration.py +0 -0
  47. {atli-0.5.1 → atli-0.7.0}/tests/test_jira.py +0 -0
  48. {atli-0.5.1 → atli-0.7.0}/tests/test_jira_agile.py +0 -0
  49. {atli-0.5.1 → atli-0.7.0}/tests/test_jira_bulk_meta.py +0 -0
  50. {atli-0.5.1 → atli-0.7.0}/tests/test_jira_fields.py +0 -0
  51. {atli-0.5.1 → atli-0.7.0}/tests/test_jira_helpers.py +0 -0
  52. {atli-0.5.1 → atli-0.7.0}/tests/test_jira_jql.py +0 -0
  53. {atli-0.5.1 → atli-0.7.0}/tests/test_jira_p3.py +0 -0
  54. {atli-0.5.1 → atli-0.7.0}/tests/test_markdown.py +0 -0
  55. {atli-0.5.1 → atli-0.7.0}/tests/test_review_findings.py +0 -0
  56. {atli-0.5.1 → atli-0.7.0}/tests/test_skills.py +0 -0
  57. {atli-0.5.1 → atli-0.7.0}/tests/test_sprint_move_search.py +0 -0
  58. {atli-0.5.1 → 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.5.1
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
@@ -1,3 +1,3 @@
1
1
  """atli — Lightweight CLI for self-hosted Jira and Confluence."""
2
2
 
3
- __version__ = "0.5.1"
3
+ __version__ = "0.7.0"
@@ -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