Coverage for icloudpy/services/photos.py: 94%

299 statements  

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

1"""Photo service.""" 

2 

3import base64 

4import json 

5import logging 

6from datetime import UTC, datetime 

7from urllib.parse import urlencode # pylint: disable=bad-option-value,relative-import 

8 

9from icloudpy.exceptions import ( 

10 ICloudPyAPIResponseException, 

11 ICloudPyLibraryUnavailableException, 

12 ICloudPyServiceNotActivatedException, 

13) 

14 

15LOGGER = logging.getLogger(__name__) 

16 

17# Apple rejects a zone it cannot index (or has dropped) with a definitive 

18# error -- 400 "Index has invalid data", ZONE_NOT_FOUND. Those mean "this 

19# library is unusable" and are safe to skip per library. Auth failures and 

20# 5xx are account-wide or transient and must surface exactly as they always have. 

21_DEFINITIVE_ZONE_ERRORS = frozenset({"BAD_REQUEST", "ZONE_NOT_FOUND"}) 

22 

23# BAD_REQUEST alone is broad: every zone-scoped 400 carries it, including one 

24# caused by a bug in our own query template rather than by a dead zone. Only 

25# the known dead-zone reason text is a verdict on the zone; a 400 with any 

26# other reason propagates unconverted (the consumer sees exactly the raise it 

27# sees today) instead of silently dropping a possibly-healthy library. 

28_DEFINITIVE_ZONE_REASONS = ("Index has invalid data",) 

29 

30 

31def _zone_name(zone_id): 

32 """Best-effort zone name for messages; zone_id is a dict or a bare name.""" 

33 return zone_id.get("zoneName") if isinstance(zone_id, dict) else zone_id 

34 

35 

36def _zone_post(session, url, data, zone_name): 

37 """POST a zone-scoped query, labelling definitive zone rejections. 

38 

39 Raises ICloudPyLibraryUnavailableException (carrying ``zone_name``) when 

40 Apple definitively rejects the zone; every other error propagates untouched. 

41 """ 

42 try: 

43 return session.post(url, data=data, headers={"Content-type": "text/plain"}) 

44 except ICloudPyAPIResponseException as err: 

45 if err.code in _DEFINITIVE_ZONE_ERRORS and ( 

46 err.code == "ZONE_NOT_FOUND" or any(text in (err.reason or "") for text in _DEFINITIVE_ZONE_REASONS) 

47 ): 

48 raise ICloudPyLibraryUnavailableException( 

49 err.reason, 

50 err.code, 

51 zone_name=zone_name, 

52 ) from err 

53 raise 

54 

55 

56class PhotoLibrary: 

57 """Represents a library in the user's photos. 

58 

59 This provides access to all the albums as well as the photos. 

60 """ 

61 

62 SMART_FOLDERS = { 

63 "All Photos": { 

64 "obj_type": "CPLAssetByAddedDate", 

65 "list_type": "CPLAssetAndMasterByAddedDate", 

66 "direction": "ASCENDING", 

67 "query_filter": None, 

68 }, 

69 "Time-lapse": { 

70 "obj_type": "CPLAssetInSmartAlbumByAssetDate:Timelapse", 

71 "list_type": "CPLAssetAndMasterInSmartAlbumByAssetDate", 

72 "direction": "ASCENDING", 

73 "query_filter": [ 

74 { 

75 "fieldName": "smartAlbum", 

76 "comparator": "EQUALS", 

77 "fieldValue": {"type": "STRING", "value": "TIMELAPSE"}, 

78 }, 

79 ], 

80 }, 

81 "Videos": { 

82 "obj_type": "CPLAssetInSmartAlbumByAssetDate:Video", 

83 "list_type": "CPLAssetAndMasterInSmartAlbumByAssetDate", 

84 "direction": "ASCENDING", 

85 "query_filter": [ 

86 { 

87 "fieldName": "smartAlbum", 

88 "comparator": "EQUALS", 

89 "fieldValue": {"type": "STRING", "value": "VIDEO"}, 

90 }, 

91 ], 

92 }, 

93 "Slo-mo": { 

94 "obj_type": "CPLAssetInSmartAlbumByAssetDate:Slomo", 

95 "list_type": "CPLAssetAndMasterInSmartAlbumByAssetDate", 

96 "direction": "ASCENDING", 

97 "query_filter": [ 

98 { 

99 "fieldName": "smartAlbum", 

100 "comparator": "EQUALS", 

101 "fieldValue": {"type": "STRING", "value": "SLOMO"}, 

102 }, 

103 ], 

104 }, 

105 "Bursts": { 

106 "obj_type": "CPLAssetBurstStackAssetByAssetDate", 

107 "list_type": "CPLBurstStackAssetAndMasterByAssetDate", 

108 "direction": "ASCENDING", 

109 "query_filter": None, 

110 }, 

111 "Favorites": { 

112 "obj_type": "CPLAssetInSmartAlbumByAssetDate:Favorite", 

113 "list_type": "CPLAssetAndMasterInSmartAlbumByAssetDate", 

114 "direction": "ASCENDING", 

115 "query_filter": [ 

116 { 

117 "fieldName": "smartAlbum", 

118 "comparator": "EQUALS", 

119 "fieldValue": {"type": "STRING", "value": "FAVORITE"}, 

120 }, 

121 ], 

122 }, 

123 "Panoramas": { 

124 "obj_type": "CPLAssetInSmartAlbumByAssetDate:Panorama", 

125 "list_type": "CPLAssetAndMasterInSmartAlbumByAssetDate", 

126 "direction": "ASCENDING", 

127 "query_filter": [ 

128 { 

129 "fieldName": "smartAlbum", 

130 "comparator": "EQUALS", 

131 "fieldValue": {"type": "STRING", "value": "PANORAMA"}, 

132 }, 

133 ], 

134 }, 

135 "Screenshots": { 

136 "obj_type": "CPLAssetInSmartAlbumByAssetDate:Screenshot", 

137 "list_type": "CPLAssetAndMasterInSmartAlbumByAssetDate", 

138 "direction": "ASCENDING", 

139 "query_filter": [ 

140 { 

141 "fieldName": "smartAlbum", 

142 "comparator": "EQUALS", 

143 "fieldValue": {"type": "STRING", "value": "SCREENSHOT"}, 

144 }, 

145 ], 

146 }, 

147 "Live": { 

148 "obj_type": "CPLAssetInSmartAlbumByAssetDate:Live", 

149 "list_type": "CPLAssetAndMasterInSmartAlbumByAssetDate", 

150 "direction": "ASCENDING", 

151 "query_filter": [ 

152 { 

153 "fieldName": "smartAlbum", 

154 "comparator": "EQUALS", 

155 "fieldValue": {"type": "STRING", "value": "LIVE"}, 

156 }, 

157 ], 

158 }, 

159 "Recently Deleted": { 

160 "obj_type": "CPLAssetDeletedByExpungedDate", 

161 "list_type": "CPLAssetAndMasterDeletedByExpungedDate", 

162 "direction": "ASCENDING", 

163 "query_filter": None, 

164 }, 

165 "Hidden": { 

166 "obj_type": "CPLAssetHiddenByAssetDate", 

167 "list_type": "CPLAssetAndMasterHiddenByAssetDate", 

168 "direction": "ASCENDING", 

169 "query_filter": None, 

170 }, 

171 } 

172 

173 def __init__(self, service, zone_id, require_finished_index=True): 

174 """Open a library, checking Apple's indexing state for its zone. 

175 

176 Raises ``ICloudPyServiceNotActivatedException`` while Apple is still 

177 indexing the library, unless ``require_finished_index`` is False. 

178 Then it opens anyway and ``indexing_state`` says how far Apple got: 

179 listings may be incomplete until it reads ``FINISHED``, so a photo 

180 missing from one is not evidence it was deleted. ``indexing_state`` is 

181 read once, here, and not refreshed. 

182 """ 

183 self.service = service 

184 self.zone_id = zone_id 

185 

186 self._albums = None 

187 

188 url = f"{self.service._service_endpoint}/records/query?{urlencode(self.service.params)}" 

189 json_data = json.dumps( 

190 { 

191 "query": {"recordType": "CheckIndexingState"}, 

192 "zoneID": self.zone_id, 

193 }, 

194 ) 

195 

196 request = _zone_post( 

197 self.service.session, 

198 url, 

199 json_data, 

200 _zone_name(self.zone_id), 

201 ) 

202 response = request.json() 

203 self.indexing_state = response["records"][0]["fields"]["state"]["value"] 

204 if require_finished_index and self.indexing_state != "FINISHED": 

205 raise ICloudPyServiceNotActivatedException( 

206 ("iCloud Photo Library not finished indexing. Please try again in a few minutes"), 

207 None, 

208 ) 

209 

210 @property 

211 def albums(self): 

212 if not self._albums: 

213 # Fetch before caching anything: a failure must leave no partial 

214 # state, so the next access retries instead of silently returning 

215 # only the smart folders populated before the error. 

216 folders = self._fetch_folders() 

217 albums = { 

218 name: PhotoAlbum(self.service, name, zone_id=self.zone_id, **props) 

219 for (name, props) in self.SMART_FOLDERS.items() 

220 } 

221 

222 for folder in folders: 

223 if folder["recordName"] in ( 

224 "----Root-Folder----", 

225 "----Project-Root-Folder----", 

226 ) or (folder["fields"].get("isDeleted") and folder["fields"]["isDeleted"]["value"]): 

227 continue 

228 

229 folder_id = folder["recordName"] 

230 folder_obj_type = f"CPLContainerRelationNotDeletedByAssetDate:{folder_id}" 

231 folder_name = base64.b64decode( 

232 folder["fields"]["albumNameEnc"]["value"], 

233 ).decode("utf-8") 

234 query_filter = [ 

235 { 

236 "fieldName": "parentId", 

237 "comparator": "EQUALS", 

238 "fieldValue": {"type": "STRING", "value": folder_id}, 

239 }, 

240 ] 

241 

242 album = PhotoAlbum( 

243 self.service, 

244 folder_name, 

245 "CPLContainerRelationLiveByAssetDate", 

246 folder_obj_type, 

247 "ASCENDING", 

248 query_filter, 

249 folder_id=folder_id, 

250 zone_id=self.zone_id, 

251 ) 

252 albums[folder_name] = album 

253 

254 self._albums = albums 

255 

256 return self._albums 

257 

258 def _fetch_folders(self): 

259 url = f"{self.service._service_endpoint}/records/query?{urlencode(self.service.params)}" 

260 json_data = json.dumps( 

261 { 

262 "query": {"recordType": "CPLAlbumByPositionLive"}, 

263 "zoneID": self.zone_id, 

264 }, 

265 ) 

266 

267 request = _zone_post( 

268 self.service.session, 

269 url, 

270 json_data, 

271 _zone_name(self.zone_id), 

272 ) 

273 response = request.json() 

274 

275 return response["records"] 

276 

277 def zone_readable(self): 

278 """Probe whether the zone answers album queries. 

279 

280 Returns False only for a definitive rejection (the zone is unusable) 

281 and True otherwise; transient errors propagate to the caller. 

282 """ 

283 try: 

284 self._fetch_folders() 

285 except ICloudPyLibraryUnavailableException as err: 

286 LOGGER.warning("photo library is unreadable and will be skipped: %s", err) 

287 return False 

288 return True 

289 

290 @property 

291 def all(self): 

292 return self.albums["All Photos"] 

293 

294 

295class PhotosService(PhotoLibrary): 

296 """The 'Photos' iCloud service. 

297 

298 This also acts as a way to access the user's primary library. 

299 """ 

300 

301 def __init__(self, service_root, session, params, require_finished_index=True): 

302 self.session = session 

303 self.params = dict(params) 

304 self._service_root = service_root 

305 self._service_endpoint = f"{self._service_root}/database/1/com.apple.photos.cloud/production/private" 

306 

307 self._libraries = None 

308 

309 self.params.update({"remapEnums": True, "getCurrentSyncToken": True}) 

310 

311 self._photo_assets = {} 

312 self._require_finished_index = require_finished_index 

313 

314 super().__init__( 

315 service=self, 

316 zone_id={"zoneName": "PrimarySync"}, 

317 require_finished_index=require_finished_index, 

318 ) 

319 

320 @property 

321 def libraries(self): 

322 if not self._libraries: 

323 # A failed zones/list must raise the real error, not be logged and 

324 # then crash iterating a variable that was never bound: no 

325 # libraries and "some libraries" are different answers, and only 

326 # the caller can decide what to do about the first. 

327 url = f"{self._service_endpoint}/zones/list" 

328 request = self.session.post( 

329 url, 

330 data="{}", 

331 headers={"Content-type": "text/plain"}, 

332 ) 

333 zones = request.json()["zones"] 

334 

335 libraries = {} 

336 for zone in zones: 

337 if zone.get("deleted"): 

338 continue 

339 zone_name = zone["zoneID"]["zoneName"] 

340 if zone_name.startswith("CMM-"): 

341 # Cloud Moments containers, not photo libraries: they answer 

342 # album queries with 400 "Index has invalid data" (the same 

343 # failure class rclone filters as fix-icloud-photos-cmm-zones). 

344 LOGGER.debug("ignoring non-photo zone %s", zone_name) 

345 continue 

346 try: 

347 library = PhotoLibrary( 

348 self, 

349 zone_id=zone["zoneID"], 

350 require_finished_index=self._require_finished_index, 

351 ) 

352 except ICloudPyLibraryUnavailableException as err: 

353 LOGGER.warning("skipping unreadable photo library: %s", err) 

354 continue 

355 try: 

356 usable = library.zone_readable() 

357 except Exception as err: # transient probe failure: keep the zone 

358 LOGGER.debug( 

359 "probe of %s failed transiently (%s); keeping it", 

360 zone_name, 

361 err, 

362 ) 

363 usable = True 

364 if not usable: 

365 continue 

366 libraries[zone_name] = library 

367 

368 self._libraries = libraries 

369 

370 return self._libraries 

371 

372 

373class PhotoAlbum: 

374 """A photo album.""" 

375 

376 def __init__( 

377 self, 

378 service, 

379 name, 

380 list_type, 

381 obj_type, 

382 direction, 

383 query_filter=None, 

384 page_size=100, 

385 folder_id=None, 

386 zone_id=None, 

387 ): 

388 self.name = name 

389 self.service = service 

390 self.list_type = list_type 

391 self.obj_type = obj_type 

392 self.direction = direction 

393 self.query_filter = query_filter 

394 self.page_size = page_size 

395 self.folder_id = folder_id 

396 

397 if zone_id: 

398 self._zone_id = zone_id 

399 else: 

400 self._zone_id = {"zoneName": "PrimarySync"} 

401 

402 self._len = None 

403 

404 self._subalbums = {} 

405 

406 @property 

407 def title(self): 

408 """Gets the album name.""" 

409 return self.name 

410 

411 def __iter__(self): 

412 return self.photos 

413 

414 def iter_chunks(self, chunk_size=1000): 

415 """Yield lists of PhotoAsset objects in fixed-size batches. 

416 

417 Equivalent to building a list from ``__iter__`` and slicing, 

418 but the per-chunk list is yielded eagerly so callers can 

419 process + release each chunk before the next is materialised. 

420 Lets bulk-download callers bound peak memory by the chunk size 

421 rather than ``len(self)`` -- relevant for 100K+ libraries where 

422 ``list(album)`` would otherwise hold every PhotoAsset (and any 

423 per-asset state callers attach) in memory at once. 

424 

425 The underlying ``photos`` property already paginates HTTP 

426 responses (``page_size * 2`` records per request); this method 

427 is a pure-Python wrapper that batches the yielded 

428 ``PhotoAsset`` instances without changing the HTTP fetch 

429 pattern. 

430 

431 Args: 

432 chunk_size: Max number of PhotoAsset objects per yielded 

433 list. Values <= 0 are coerced to the default (1000). 

434 

435 Yields: 

436 List of up to ``chunk_size`` ``PhotoAsset`` instances. The 

437 final chunk may be smaller. No empty list is yielded for 

438 an empty album. 

439 """ 

440 if chunk_size <= 0: 

441 chunk_size = 1000 

442 buffer = [] 

443 for photo in self: 

444 buffer.append(photo) 

445 if len(buffer) >= chunk_size: 

446 yield buffer 

447 buffer = [] 

448 if buffer: 

449 yield buffer 

450 

451 def __len__(self): 

452 if self._len is None: 

453 url = f"{self.service._service_endpoint}/internal/records/query/batch?{urlencode(self.service.params)}" 

454 data = json.dumps( 

455 { 

456 "batch": [ 

457 { 

458 "resultsLimit": 1, 

459 "query": { 

460 "filterBy": { 

461 "fieldName": "indexCountID", 

462 "fieldValue": { 

463 "type": "STRING_LIST", 

464 "value": [self.obj_type], 

465 }, 

466 "comparator": "IN", 

467 }, 

468 "recordType": "HyperionIndexCountLookup", 

469 }, 

470 "zoneWide": True, 

471 "zoneID": {"zoneName": self._zone_id["zoneName"]}, 

472 }, 

473 ], 

474 }, 

475 ) 

476 request = _zone_post( 

477 self.service.session, 

478 url, 

479 data, 

480 _zone_name(self._zone_id), 

481 ) 

482 response = request.json() 

483 

484 self._len = response["batch"][0]["records"][0]["fields"]["itemCount"]["value"] 

485 

486 return self._len 

487 

488 def _fetch_subalbums(self): 

489 url = (f"{self.service._service_endpoint}/records/query?") + urlencode( 

490 self.service.params, 

491 ) 

492 # pylint: disable=consider-using-f-string 

493 query = """{{ 

494 "query": {{ 

495 "recordType":"CPLAlbumByPositionLive", 

496 "filterBy": [ 

497 {{ 

498 "fieldName": "parentId", 

499 "comparator": "EQUALS", 

500 "fieldValue": {{ 

501 "value": "{}", 

502 "type": "STRING" 

503 }} 

504 }} 

505 ] 

506 }}, 

507 "zoneID": {{ 

508 "zoneName":"{}" 

509 }} 

510 }}""".format( 

511 self.folder_id, 

512 self._zone_id["zoneName"], 

513 ) 

514 json_data = query 

515 request = _zone_post( 

516 self.service.session, 

517 url, 

518 json_data, 

519 _zone_name(self._zone_id), 

520 ) 

521 response = request.json() 

522 

523 return response["records"] 

524 

525 @property 

526 def subalbums(self): 

527 """Returns the subalbums""" 

528 if not self._subalbums and self.folder_id: 

529 for folder in self._fetch_subalbums(): 

530 if folder["fields"].get("isDeleted") and folder["fields"]["isDeleted"]["value"]: 

531 continue 

532 

533 folder_id = folder["recordName"] 

534 folder_obj_type = f"CPLContainerRelationNotDeletedByAssetDate:{folder_id}" 

535 folder_name = base64.b64decode( 

536 folder["fields"]["albumNameEnc"]["value"], 

537 ).decode("utf-8") 

538 query_filter = [ 

539 { 

540 "fieldName": "parentId", 

541 "comparator": "EQUALS", 

542 "fieldValue": {"type": "STRING", "value": folder_id}, 

543 }, 

544 ] 

545 

546 album = PhotoAlbum( 

547 self.service, 

548 name=folder_name, 

549 list_type="CPLContainerRelationLiveByAssetDate", 

550 obj_type=folder_obj_type, 

551 direction="ASCENDING", 

552 query_filter=query_filter, 

553 folder_id=folder_id, 

554 zone_id=self._zone_id, 

555 ) 

556 self._subalbums[folder_name] = album 

557 return self._subalbums 

558 

559 @property 

560 def photos(self): 

561 """Returns the album photos.""" 

562 if self.direction == "DESCENDING": 

563 offset = len(self) - 1 

564 else: 

565 offset = 0 

566 

567 while True: 

568 url = (f"{self.service._service_endpoint}/records/query?") + urlencode( 

569 self.service.params, 

570 ) 

571 data = json.dumps( 

572 self._list_query_gen( 

573 offset, 

574 self.list_type, 

575 self.direction, 

576 self.query_filter, 

577 ), 

578 ) 

579 request = _zone_post( 

580 self.service.session, 

581 url, 

582 data, 

583 _zone_name(self._zone_id), 

584 ) 

585 response = request.json() 

586 

587 asset_records = {} 

588 master_records = [] 

589 for rec in response["records"]: 

590 if rec["recordType"] == "CPLAsset": 

591 master_id = rec["fields"]["masterRef"]["value"]["recordName"] 

592 asset_records[master_id] = rec 

593 elif rec["recordType"] == "CPLMaster": 

594 master_records.append(rec) 

595 

596 master_records_len = len(master_records) 

597 if master_records_len: 

598 if self.direction == "DESCENDING": 

599 offset = offset - master_records_len 

600 else: 

601 offset = offset + master_records_len 

602 

603 for master_record in master_records: 

604 record_name = master_record["recordName"] 

605 yield PhotoAsset( 

606 self.service, 

607 master_record, 

608 asset_records[record_name], 

609 zone_id=self._zone_id, 

610 ) 

611 else: 

612 break 

613 

614 def _list_query_gen(self, offset, list_type, direction, query_filter=None): 

615 query = { 

616 "query": { 

617 "filterBy": [ 

618 { 

619 "fieldName": "startRank", 

620 "fieldValue": {"type": "INT64", "value": offset}, 

621 "comparator": "EQUALS", 

622 }, 

623 { 

624 "fieldName": "direction", 

625 "fieldValue": {"type": "STRING", "value": direction}, 

626 "comparator": "EQUALS", 

627 }, 

628 ], 

629 "recordType": list_type, 

630 }, 

631 "resultsLimit": self.page_size * 2, 

632 "desiredKeys": [ 

633 "resJPEGFullWidth", 

634 "resJPEGFullHeight", 

635 "resJPEGFullFileType", 

636 "resJPEGFullFingerprint", 

637 "resJPEGFullRes", 

638 "resJPEGLargeWidth", 

639 "resJPEGLargeHeight", 

640 "resJPEGLargeFileType", 

641 "resJPEGLargeFingerprint", 

642 "resJPEGLargeRes", 

643 "resJPEGMedWidth", 

644 "resJPEGMedHeight", 

645 "resJPEGMedFileType", 

646 "resJPEGMedFingerprint", 

647 "resJPEGMedRes", 

648 "resJPEGThumbWidth", 

649 "resJPEGThumbHeight", 

650 "resJPEGThumbFileType", 

651 "resJPEGThumbFingerprint", 

652 "resJPEGThumbRes", 

653 "resVidFullWidth", 

654 "resVidFullHeight", 

655 "resVidFullFileType", 

656 "resVidFullFingerprint", 

657 "resVidFullRes", 

658 "resVidMedWidth", 

659 "resVidMedHeight", 

660 "resVidMedFileType", 

661 "resVidMedFingerprint", 

662 "resVidMedRes", 

663 "resVidSmallWidth", 

664 "resVidSmallHeight", 

665 "resVidSmallFileType", 

666 "resVidSmallFingerprint", 

667 "resVidSmallRes", 

668 "resSidecarWidth", 

669 "resSidecarHeight", 

670 "resSidecarFileType", 

671 "resSidecarFingerprint", 

672 "resSidecarRes", 

673 "itemType", 

674 "dataClassType", 

675 "filenameEnc", 

676 "originalOrientation", 

677 "resOriginalWidth", 

678 "resOriginalHeight", 

679 "resOriginalFileType", 

680 "resOriginalFingerprint", 

681 "resOriginalRes", 

682 "resOriginalAltWidth", 

683 "resOriginalAltHeight", 

684 "resOriginalAltFileType", 

685 "resOriginalAltFingerprint", 

686 "resOriginalAltRes", 

687 "resOriginalVidComplWidth", 

688 "resOriginalVidComplHeight", 

689 "resOriginalVidComplFileType", 

690 "resOriginalVidComplFingerprint", 

691 "resOriginalVidComplRes", 

692 "isDeleted", 

693 "isExpunged", 

694 "dateExpunged", 

695 "remappedRef", 

696 "recordName", 

697 "recordType", 

698 "recordChangeTag", 

699 "masterRef", 

700 "adjustmentRenderType", 

701 "assetDate", 

702 "addedDate", 

703 "isFavorite", 

704 "isHidden", 

705 "orientation", 

706 "duration", 

707 "assetSubtype", 

708 "assetSubtypeV2", 

709 "assetHDRType", 

710 "burstFlags", 

711 "burstFlagsExt", 

712 "burstId", 

713 "captionEnc", 

714 "extendedDescEnc", 

715 "locationEnc", 

716 "locationV2Enc", 

717 "locationLatitude", 

718 "locationLongitude", 

719 "adjustmentType", 

720 "timeZoneOffset", 

721 "vidComplDurValue", 

722 "vidComplDurScale", 

723 "vidComplDispValue", 

724 "vidComplDispScale", 

725 "vidComplVisibilityState", 

726 "customRenderedValue", 

727 "containerId", 

728 "itemId", 

729 "position", 

730 "isKeyAsset", 

731 "importedByBundleIdentifierEnc", 

732 "importedByDisplayNameEnc", 

733 "importedBy", 

734 ], 

735 "zoneID": self._zone_id, 

736 } 

737 

738 if query_filter: 

739 query["query"]["filterBy"].extend(query_filter) 

740 

741 return query 

742 

743 def __unicode__(self): 

744 return self.title 

745 

746 def __str__(self): 

747 return self.__unicode__() 

748 

749 def __repr__(self): 

750 return f"<{type(self).__name__}: '{self}'>" 

751 

752 

753class PhotoAsset: 

754 """A photo.""" 

755 

756 def __init__(self, service, master_record, asset_record, zone_id=None): 

757 self._service = service 

758 self._master_record = master_record 

759 self._asset_record = asset_record 

760 self._zone_id = zone_id 

761 

762 self._versions = None 

763 

764 # Apple Uniform Type Identifiers (UTIs) for known iCloud photo/video assets. 

765 # Mirrors the table in icloud_photos_downloader's pyicloud_ipd.services.photos. 

766 # Anything not listed here falls back to the filename-extension heuristic in 

767 # `item_type` below. 

768 ITEM_TYPES = { 

769 "public.heic": "image", 

770 "public.heif": "image", 

771 "public.jpeg": "image", 

772 "public.png": "image", 

773 "public.tiff": "image", 

774 "com.adobe.raw-image": "image", 

775 "com.canon.cr2-raw-image": "image", 

776 "com.canon.cr3-raw-image": "image", 

777 "com.canon.crw-raw-image": "image", 

778 "com.fuji.raw-image": "image", 

779 "com.nikon.nrw-raw-image": "image", 

780 "com.nikon.raw-image": "image", 

781 "com.olympus.or-raw-image": "image", 

782 "com.olympus.raw-image": "image", 

783 "com.panasonic.rw2-raw-image": "image", 

784 "com.pentax.raw-image": "image", 

785 "com.sony.arw-raw-image": "image", 

786 "com.apple.quicktime-movie": "movie", 

787 "public.mpeg-4": "movie", 

788 } 

789 

790 PHOTO_VERSION_LOOKUP = { 

791 "full": "resJPEGFull", 

792 "large": "resJPEGLarge", 

793 "medium": "resJPEGMed", 

794 "thumb": "resJPEGThumb", 

795 "sidecar": "resSidecar", 

796 "original": "resOriginal", 

797 "original_alt": "resOriginalAlt", 

798 # Live Photo video components — present alongside the still image for 

799 # Live Photos. The CloudKit master_record carries `resOriginalVidCompl*` 

800 # (the original .mov), and may also expose `resVidMed*` / `resVidSmall*` 

801 # for smaller variants. If the asset is a regular still photo, these 

802 # keys are silently skipped by `versions` since the underlying fields 

803 # are absent. 

804 "live_video_original": "resOriginalVidCompl", 

805 "live_video_medium": "resVidMed", 

806 "live_video_thumb": "resVidSmall", 

807 } 

808 

809 VIDEO_VERSION_LOOKUP = { 

810 "full": "resVidFull", 

811 "medium": "resVidMed", 

812 "thumb": "resVidSmall", 

813 "original": "resOriginal", 

814 "original_compl": "resOriginalVidCompl", 

815 } 

816 

817 @property 

818 def id(self): 

819 """Gets the photo id.""" 

820 return self._master_record["recordName"] 

821 

822 @property 

823 def filename(self): 

824 """Gets the photo file name.""" 

825 try: 

826 return base64.b64decode( 

827 self._master_record["fields"]["filenameEnc"]["value"], 

828 ).decode("utf-8") 

829 except KeyError: 

830 # Some photos/videos (e.g., GoPro videos) may not have a filename 

831 return None 

832 

833 @property 

834 def size(self): 

835 """Gets the photo size.""" 

836 return self._master_record["fields"]["resOriginalRes"]["value"]["size"] 

837 

838 @property 

839 def created(self): 

840 """Gets the photo created date.""" 

841 return self.asset_date 

842 

843 @property 

844 def asset_date(self): 

845 """Gets the photo asset date.""" 

846 try: 

847 return datetime.fromtimestamp( 

848 self._asset_record["fields"]["assetDate"]["value"] / 1000.0, 

849 tz=UTC, 

850 ) 

851 except KeyError: 

852 return datetime.fromtimestamp(0) 

853 

854 @property 

855 def added_date(self): 

856 """Gets the photo added date.""" 

857 return datetime.fromtimestamp( 

858 self._asset_record["fields"]["addedDate"]["value"] / 1000.0, 

859 tz=UTC, 

860 ) 

861 

862 @property 

863 def dimensions(self): 

864 """Gets the photo dimensions.""" 

865 return ( 

866 self._master_record["fields"]["resOriginalWidth"]["value"], 

867 self._master_record["fields"]["resOriginalHeight"]["value"], 

868 ) 

869 

870 @property 

871 def item_type(self): 

872 """Returns 'image' or 'movie' for this asset. 

873 

874 Reads the CloudKit ``itemType`` field (Apple UTI string) and maps it 

875 via ``ITEM_TYPES``. Falls back to a filename-extension heuristic when 

876 the UTI is missing or unrecognised — that path catches GoPro footage 

877 and a handful of camera-RAW formats that Apple has not assigned a 

878 canonical UTI to. 

879 

880 Returns ``None`` only when both the UTI is missing AND no filename is 

881 available (rare — usually a CloudKit record with no master payload). 

882 """ 

883 fields = self._master_record["fields"] 

884 uti = fields.get("itemType", {}).get("value") 

885 if uti in self.ITEM_TYPES: 

886 return self.ITEM_TYPES[uti] 

887 

888 # Extension-based fallback. Mirrors pyicloud_ipd's heuristic. 

889 filename = self.filename 

890 if filename: 

891 lower = filename.lower() 

892 if lower.endswith((".heic", ".heif", ".png", ".jpg", ".jpeg", ".tif", ".tiff")): 

893 return "image" 

894 if lower.endswith((".mov", ".mp4", ".m4v", ".avi", ".3gp")): 

895 return "movie" 

896 return None 

897 

898 @property 

899 def versions(self): 

900 """Gets the photo versions. 

901 

902 For ``item_type == "movie"`` returns the video versions 

903 (``VIDEO_VERSION_LOOKUP``). For everything else returns the image 

904 versions (``PHOTO_VERSION_LOOKUP``) — which includes Live Photo video 

905 keys (``live_video_original`` / ``live_video_medium`` / 

906 ``live_video_thumb``) when the underlying CloudKit fields are present. 

907 

908 Backward compatibility: callers that previously received only photo 

909 versions for still images and only video versions for movies still see 

910 those keys. Live Photo callers gain new ``live_video_*`` keys that 

911 were previously inaccessible — earlier icloudpy versions misclassified 

912 Live Photos as movies (via the ``resVidSmallRes`` presence heuristic) 

913 and dropped the still image entirely. 

914 

915 Apple splits the resource fields across the asset's two CloudKit 

916 records: the ``CPLAsset`` record carries the edited rendition 

917 (``resJPEGFull*``), while the ``CPLMaster`` record carries the 

918 original and alternate renditions (``resOriginal*``). Each version is 

919 therefore read from the asset record first, falling back to the master 

920 record per version. That makes an edited photo's ``full`` version 

921 available (Apple's rendered edit, including portraits) instead of only 

922 the untouched original. 

923 """ 

924 if not self._versions: 

925 self._versions = {} 

926 if self.item_type == "movie": 

927 typed_version_lookup = self.VIDEO_VERSION_LOOKUP 

928 else: 

929 typed_version_lookup = self.PHOTO_VERSION_LOOKUP 

930 

931 asset_fields = (self._asset_record or {}).get("fields", {}) 

932 master_fields = self._master_record["fields"] 

933 

934 for key, prefix in typed_version_lookup.items(): 

935 fields = asset_fields if f"{prefix}Res" in asset_fields else master_fields 

936 if f"{prefix}Res" in fields: 

937 version = {"filename": self.filename} 

938 

939 width_entry = fields.get(f"{prefix}Width") 

940 if width_entry: 

941 version["width"] = width_entry["value"] 

942 else: 

943 version["width"] = None 

944 

945 height_entry = fields.get(f"{prefix}Height") 

946 if height_entry: 

947 version["height"] = height_entry["value"] 

948 else: 

949 version["height"] = None 

950 

951 size_entry = fields.get(f"{prefix}Res") 

952 if size_entry: 

953 version["size"] = size_entry["value"]["size"] 

954 version["url"] = size_entry["value"]["downloadURL"] 

955 else: 

956 version["size"] = None 

957 version["url"] = None 

958 

959 type_entry = fields.get(f"{prefix}FileType") 

960 if type_entry: 

961 version["type"] = type_entry["value"] 

962 else: 

963 version["type"] = None 

964 

965 self._versions[key] = version 

966 

967 return self._versions 

968 

969 def download(self, version="original", **kwargs): 

970 """Returns the photo file.""" 

971 if version not in self.versions: 

972 return None 

973 

974 return self._service.session.get( 

975 self.versions[version]["url"], 

976 stream=True, 

977 **kwargs, 

978 ) 

979 

980 @property 

981 def zone_id(self): 

982 """The CloudKit zone of the library this photo belongs to. 

983 

984 ``service`` is always the ``PhotosService``, whose own zone is 

985 ``PrimarySync``, so a photo from any other library (a Shared Library, 

986 say) must not borrow it. Falls back to the service's zone only for a 

987 ``PhotoAsset`` built without one. 

988 """ 

989 return self._zone_id or self._service.zone_id 

990 

991 def delete(self): 

992 """Deletes the photo.""" 

993 json_data = json.dumps( 

994 { 

995 "atomic": True, 

996 "desiredKeys": ["isDeleted"], 

997 "operations": [ 

998 { 

999 "operationType": "update", 

1000 "record": { 

1001 "fields": {"isDeleted": {"value": 1}}, 

1002 "recordChangeTag": self._asset_record["recordChangeTag"], 

1003 "recordName": self._asset_record["recordName"], 

1004 "recordType": self._asset_record["recordType"], 

1005 }, 

1006 }, 

1007 ], 

1008 "zoneID": self.zone_id, 

1009 }, 

1010 ) 

1011 

1012 endpoint = self._service._service_endpoint 

1013 params = urlencode(self._service.params) 

1014 url = f"{endpoint}/records/modify?{params}" 

1015 

1016 return self._service.session.post( 

1017 url, 

1018 data=json_data, 

1019 headers={"Content-type": "text/plain"}, 

1020 ) 

1021 

1022 def __repr__(self): 

1023 return f"<{type(self).__name__}: id={self.id}>"