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
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-05 06:42 +0000
1"""Drive service."""
3import io
4import json
5import mimetypes
6import os
7import time
8from datetime import datetime, timedelta
9from re import search
11from requests import Response
14class DriveService:
15 """The 'Drive' iCloud service."""
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
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")
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]
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.")
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.
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::
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)
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.
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 )
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"]
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))
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 = ""
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)
151 file_params = self.params
152 file_params.update(self._get_token_from_cookie())
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"])
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 }
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"]})
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()
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)
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"]
226 self._update_contentws(
227 folder_id,
228 content_response,
229 document_id,
230 file_object,
231 zone,
232 )
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()
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()
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()
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
304 def __getattr__(self, attr):
305 return getattr(self.root, attr)
307 def __getitem__(self, key):
308 return self.root[key]
311class RecentDocs(list):
312 """Recently opened iCloud Drive documents, plus Apple's paging state.
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 """
321 def __init__(self, documents, status=None, next_page=None):
322 super().__init__(documents)
323 self.status = status
324 self.next_page = next_page
326 @property
327 def more_available(self):
328 """True when Apple reported more documents than were returned."""
329 return self.status == "MORE_AVAILABLE"
332class DriveNode:
333 """Drive node."""
335 def __init__(self, conn, data):
336 self.data = data
337 self.connection = conn
338 self._children = None
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"]
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()
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
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)
371 @property
372 def date_created(self):
373 """Gets the node created date (in UTC)."""
374 return _date_to_utc(self.data.get("dateCreated"))
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
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
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
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 )
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 )
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()]
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)
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 )
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 )
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]
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
454 def __unicode__(self):
455 return f"{{type: {self.type}, name: {self.name}}}"
457 def __str__(self):
458 return self.__unicode__()
460 def __repr__(self):
461 return f"<{type(self).__name__}: {str(self)}>"
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