Coverage for icloudpy/services/drive.py: 100%

205 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-05 06:42 +0000

1"""Drive service.""" 

2 

3import io 

4import json 

5import mimetypes 

6import os 

7import time 

8from datetime import datetime, timedelta 

9from re import search 

10 

11from requests import Response 

12 

13 

14class DriveService: 

15 """The 'Drive' iCloud service.""" 

16 

17 def __init__(self, service_root, document_root, session, params): 

18 self._service_root = service_root 

19 self._document_root = document_root 

20 self.session = session 

21 self.params = dict(params) 

22 self._root = None 

23 

24 def _get_token_from_cookie(self): 

25 for cookie in self.session.cookies: 

26 if cookie.name == "X-APPLE-WEBAUTH-VALIDATE": 

27 match = search(r"\bt=([^:]+)", cookie.value) 

28 if match is None: 

29 raise Exception(f"Can't extract token from {cookie.value}") 

30 return {"token": match.group(1)} 

31 raise Exception("Token cookie not found") 

32 

33 def get_node_data(self, drivewsid): 

34 """Returns the node data.""" 

35 request = self.session.post( 

36 self._service_root + "/retrieveItemDetailsInFolders", 

37 params=self.params, 

38 data=json.dumps( 

39 [ 

40 { 

41 "drivewsid": drivewsid, 

42 "partialData": False, 

43 }, 

44 ], 

45 ), 

46 ) 

47 if not request.ok: 

48 self.session.raise_error(request.status_code, request.reason) 

49 return request.json()[0] 

50 

51 def get_file(self, file_id, zone="com.apple.CloudDocs", **kwargs): 

52 """Returns iCloud Drive file.""" 

53 file_params = dict(self.params) 

54 file_params.update({"document_id": file_id}) 

55 # The lookup and the transfer are separate requests. A timeout given 

56 # only to the transfer leaves the lookup free to stall its thread 

57 # forever, so forward it here too. ``stream`` is deliberately not 

58 # forwarded: the lookup is a small JSON reply read in full. 

59 lookup_kwargs = {"timeout": kwargs["timeout"]} if "timeout" in kwargs else {} 

60 response = self.session.get( 

61 self._document_root + f"/ws/{zone}/download/by_id", 

62 params=file_params, 

63 **lookup_kwargs, 

64 ) 

65 if not response.ok: 

66 self.session.raise_error(response.status_code, response.reason) 

67 package_token = response.json().get("package_token") 

68 data_token = response.json().get("data_token") 

69 if data_token and data_token.get("url"): 

70 return self.session.get(data_token["url"], params=self.params, **kwargs) 

71 elif package_token and package_token.get("url"): 

72 return self.session.get(package_token["url"], params=self.params, **kwargs) 

73 else: 

74 raise KeyError("'data_token' nor 'package_token' found in response.") 

75 

76 def get_recent_docs(self, limit=20, next_page=None, zone="com.apple.CloudDocs"): 

77 """Returns the recently opened iCloud Drive documents, newest first. 

78 

79 Apple returns at most ``limit`` documents. When more exist the result's 

80 ``status`` is ``MORE_AVAILABLE`` and its ``next_page`` cursor continues 

81 the listing:: 

82 

83 page = drive.get_recent_docs() 

84 while page.more_available and page.next_page: 

85 page = drive.get_recent_docs(next_page=page.next_page) 

86 

87 Each page is returned as its own list; pages are not merged or 

88 de-duplicated, so pass the cursor back rather than re-requesting the 

89 first page. Pass the same ``zone`` on every page. The ordering is 

90 Apple's: the documents come back newest first, but which timestamp 

91 orders them is not documented. 

92 

93 :param limit: maximum documents to return (Apple caps this itself) 

94 :param next_page: ``next_page`` from a previous result, or ``None`` 

95 :param zone: the Drive zone to list, defaulting to the main Drive 

96 zone. ``_all_`` asks for every zone, but Apple does not serve 

97 that for every account, so it is opt-in. 

98 :returns: :class:`RecentDocs` 

99 """ 

100 params = dict(self.params) 

101 params.update({"unified_format": "true", "limit": limit}) 

102 if next_page: 

103 params["nextPage"] = next_page 

104 request = self.session.get( 

105 self._document_root + f"/ws/{zone}/list/enumerate/recentDocs", 

106 params=params, 

107 ) 

108 if not request.ok: 

109 self.session.raise_error(request.status_code, request.reason) 

110 payload = request.json() 

111 if not isinstance(payload, dict): 

112 raise KeyError("Unexpected 'recent documents' response.") 

113 raw_documents = payload.get("documents") 

114 documents = [ 

115 DriveNode(self, item) 

116 for item in (raw_documents if isinstance(raw_documents, list) else []) 

117 if isinstance(item, dict) 

118 ] 

119 return RecentDocs( 

120 documents, 

121 status=payload.get("status"), 

122 next_page=payload.get("continuationMarker"), 

123 ) 

124 

125 def get_app_data(self): 

126 """Returns the app library.""" 

127 request = self.session.get( 

128 self._service_root + "/retrieveAppLibraries", 

129 params=self.params, 

130 ) 

131 if not request.ok: 

132 self.session.raise_error(request.status_code, request.reason) 

133 return request.json()["items"] 

134 

135 def get_app_node(self, app_id, folder="documents"): 

136 """Returns the node of the app.""" 

137 return DriveNode(self, self.get_node_data("FOLDER::" + app_id + "::" + folder)) 

138 

139 def _get_upload_contentws_url(self, file_object, zone="com.apple.CloudDocs"): 

140 """Get the contentWS endpoint URL to add a new file.""" 

141 content_type = mimetypes.guess_type(file_object.name)[0] 

142 if content_type is None: 

143 content_type = "" 

144 

145 # Get filesize from file object 

146 orig_pos = file_object.tell() 

147 file_object.seek(0, os.SEEK_END) 

148 file_size = file_object.tell() 

149 file_object.seek(orig_pos, os.SEEK_SET) 

150 

151 file_params = self.params 

152 file_params.update(self._get_token_from_cookie()) 

153 

154 request = self.session.post( 

155 self._document_root + f"/ws/{zone}/upload/web", 

156 params=file_params, 

157 headers={"Content-Type": "text/plain"}, 

158 data=json.dumps( 

159 { 

160 "filename": file_object.name, 

161 "type": "FILE", 

162 "content_type": content_type, 

163 "size": file_size, 

164 }, 

165 ), 

166 ) 

167 if not request.ok: 

168 self.session.raise_error(request.status_code, request.reason) 

169 return (request.json()[0]["document_id"], request.json()[0]["url"]) 

170 

171 def _update_contentws( 

172 self, 

173 folder_id, 

174 sf_info, 

175 document_id, 

176 file_object, 

177 zone="com.apple.CloudDocs", 

178 ): 

179 data = { 

180 "data": { 

181 "signature": sf_info["fileChecksum"], 

182 "wrapping_key": sf_info["wrappingKey"], 

183 "reference_signature": sf_info["referenceChecksum"], 

184 "size": sf_info["size"], 

185 }, 

186 "command": "add_file", 

187 "create_short_guid": True, 

188 "document_id": document_id, 

189 "path": { 

190 "starting_document_id": folder_id, 

191 "path": os.path.basename(file_object.name), 

192 }, 

193 "allow_conflict": True, 

194 "file_flags": { 

195 "is_writable": True, 

196 "is_executable": False, 

197 "is_hidden": False, 

198 }, 

199 "mtime": int(time.time() * 1000), 

200 "btime": int(time.time() * 1000), 

201 } 

202 

203 # Add the receipt if we have one. Will be absent for 0-sized files 

204 if sf_info.get("receipt"): 

205 data["data"].update({"receipt": sf_info["receipt"]}) 

206 

207 request = self.session.post( 

208 self._document_root + f"/ws/{zone}/update/documents", 

209 params=self.params, 

210 headers={"Content-Type": "text/plain"}, 

211 data=json.dumps(data), 

212 ) 

213 if not request.ok: 

214 self.session.raise_error(request.status_code, request.reason) 

215 return request.json() 

216 

217 def send_file(self, folder_id, file_object, zone="com.apple.CloudDocs"): 

218 """Send new file to iCloud Drive.""" 

219 document_id, content_url = self._get_upload_contentws_url(file_object, zone) 

220 

221 request = self.session.post(content_url, files={file_object.name: file_object}) 

222 if not request.ok: 

223 self.session.raise_error(request.status_code, request.reason) 

224 content_response = request.json()["singleFile"] 

225 

226 self._update_contentws( 

227 folder_id, 

228 content_response, 

229 document_id, 

230 file_object, 

231 zone, 

232 ) 

233 

234 def create_folders(self, parent, name): 

235 """Creates a new iCloud Drive folder""" 

236 request = self.session.post( 

237 self._service_root + "/createFolders", 

238 params=self.params, 

239 headers={"Content-Type": "text/plain"}, 

240 data=json.dumps( 

241 { 

242 "destinationDrivewsId": parent, 

243 "folders": [ 

244 { 

245 "clientId": self.params["clientId"], 

246 "name": name, 

247 }, 

248 ], 

249 }, 

250 ), 

251 ) 

252 return request.json() 

253 

254 def rename_items(self, node_id, etag, name): 

255 """Renames an iCloud Drive node""" 

256 request = self.session.post( 

257 self._service_root + "/renameItems", 

258 params=self.params, 

259 data=json.dumps( 

260 { 

261 "items": [ 

262 { 

263 "drivewsid": node_id, 

264 "etag": etag, 

265 "name": name, 

266 }, 

267 ], 

268 }, 

269 ), 

270 ) 

271 return request.json() 

272 

273 def move_items_to_trash(self, node_id, etag): 

274 """Moves an iCloud Drive node to the trash bin""" 

275 request = self.session.post( 

276 self._service_root + "/moveItemsToTrash", 

277 params=self.params, 

278 data=json.dumps( 

279 { 

280 "items": [ 

281 { 

282 "drivewsid": node_id, 

283 "etag": etag, 

284 "clientId": self.params["clientId"], 

285 }, 

286 ], 

287 }, 

288 ), 

289 ) 

290 if not request.ok: 

291 self.session.raise_error(request.status_code, request.reason) 

292 return request.json() 

293 

294 @property 

295 def root(self): 

296 """Returns the root node.""" 

297 if not self._root: 

298 self._root = DriveNode( 

299 self, 

300 self.get_node_data("FOLDER::com.apple.CloudDocs::root"), 

301 ) 

302 return self._root 

303 

304 def __getattr__(self, attr): 

305 return getattr(self.root, attr) 

306 

307 def __getitem__(self, key): 

308 return self.root[key] 

309 

310 

311class RecentDocs(list): 

312 """Recently opened iCloud Drive documents, plus Apple's paging state. 

313 

314 A plain list of :class:`DriveNode` objects, so iteration, indexing and 

315 slicing behave as usual. ``status`` is Apple's list status — 

316 ``"CONSISTENT"`` when the list is complete, ``"MORE_AVAILABLE"`` when more 

317 documents exist beyond the requested limit — and ``next_page`` is the 

318 cursor to pass back to :meth:`DriveService.get_recent_docs`. 

319 """ 

320 

321 def __init__(self, documents, status=None, next_page=None): 

322 super().__init__(documents) 

323 self.status = status 

324 self.next_page = next_page 

325 

326 @property 

327 def more_available(self): 

328 """True when Apple reported more documents than were returned.""" 

329 return self.status == "MORE_AVAILABLE" 

330 

331 

332class DriveNode: 

333 """Drive node.""" 

334 

335 def __init__(self, conn, data): 

336 self.data = data 

337 self.connection = conn 

338 self._children = None 

339 

340 @property 

341 def name(self): 

342 """Gets the node name.""" 

343 if "extension" in self.data: 

344 return f"{self.data['name']}.{self.data['extension']}" 

345 return self.data["name"] 

346 

347 @property 

348 def type(self): 

349 """Gets the node type.""" 

350 node_type = self.data.get("type") 

351 return node_type and node_type.lower() 

352 

353 def get_children(self): 

354 """Gets the node children.""" 

355 if not self._children: 

356 if "items" not in self.data: 

357 self.data.update(self.connection.get_node_data(self.data["drivewsid"])) 

358 if "items" not in self.data: 

359 raise KeyError(f"No items in folder, status: {self.data['status']}") 

360 self._children = [DriveNode(self.connection, item_data) for item_data in self.data["items"]] 

361 return self._children 

362 

363 @property 

364 def size(self): 

365 """Gets the node size.""" 

366 size = self.data.get("size") # Folder does not have size 

367 if not size: 

368 return None 

369 return int(size) 

370 

371 @property 

372 def date_created(self): 

373 """Gets the node created date (in UTC).""" 

374 return _date_to_utc(self.data.get("dateCreated")) 

375 

376 @property 

377 def date_changed(self): 

378 """Gets the node changed date (in UTC).""" 

379 return _date_to_utc(self.data.get("dateChanged")) # Folder does not have date 

380 

381 @property 

382 def date_modified(self): 

383 """Gets the node modified date (in UTC).""" 

384 return _date_to_utc(self.data.get("dateModified")) # Folder does not have date 

385 

386 @property 

387 def date_last_open(self): 

388 """Gets the node last open date (in UTC).""" 

389 return _date_to_utc(self.data.get("lastOpenTime")) # Folder does not have date 

390 

391 def open(self, **kwargs): 

392 """Gets the node file.""" 

393 # iCloud returns 400 Bad Request for 0-byte files 

394 if self.data["size"] == 0: 

395 response = Response() 

396 response.raw = io.BytesIO() 

397 return response 

398 return self.connection.get_file( 

399 self.data["docwsid"], 

400 zone=self.data["zone"], 

401 **kwargs, 

402 ) 

403 

404 def upload(self, file_object, **kwargs): 

405 """ "Upload a new file.""" 

406 return self.connection.send_file( 

407 self.data["docwsid"], 

408 file_object, 

409 zone=self.data["zone"], 

410 **kwargs, 

411 ) 

412 

413 def dir(self): 

414 """Gets the node list of directories.""" 

415 if self.type == "file": 

416 return None 

417 return [child.name for child in self.get_children()] 

418 

419 def mkdir(self, folder): 

420 """Create a new directory directory.""" 

421 # remove cached entries information first so that it will be re-read on next get_children() 

422 self._children = None 

423 if "items" in self.data: 

424 self.data.pop("items") 

425 return self.connection.create_folders(self.data["drivewsid"], folder) 

426 

427 def rename(self, name): 

428 """Rename an iCloud Drive item.""" 

429 return self.connection.rename_items( 

430 self.data["drivewsid"], 

431 self.data["etag"], 

432 name, 

433 ) 

434 

435 def delete(self): 

436 """Delete an iCloud Drive item.""" 

437 return self.connection.move_items_to_trash( 

438 self.data["drivewsid"], 

439 self.data["etag"], 

440 ) 

441 

442 def get(self, name): 

443 """Gets the node child.""" 

444 if self.type == "file": 

445 return None 

446 return [child for child in self.get_children() if child.name == name][0] 

447 

448 def __getitem__(self, key): 

449 try: 

450 return self.get(key) 

451 except IndexError as error: 

452 raise KeyError(f"No child named '{key}' exists") from error 

453 

454 def __unicode__(self): 

455 return f"{{type: {self.type}, name: {self.name}}}" 

456 

457 def __str__(self): 

458 return self.__unicode__() 

459 

460 def __repr__(self): 

461 return f"<{type(self).__name__}: {str(self)}>" 

462 

463 

464def _date_to_utc(date): 

465 if not date: 

466 return None 

467 # jump through hoops to return time in UTC rather than California time 

468 match = search(r"^(.+?)([\+\-]\d+):(\d\d)$", date) 

469 if not match: 

470 # Already in UTC 

471 return datetime.strptime(date, "%Y-%m-%dT%H:%M:%SZ") 

472 base = datetime.strptime(match.group(1), "%Y-%m-%dT%H:%M:%S") 

473 diff = timedelta(hours=int(match.group(2)), minutes=int(match.group(3))) 

474 return base - diff