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
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-05 06:42 +0000
1"""Photo service."""
3import base64
4import json
5import logging
6from datetime import UTC, datetime
7from urllib.parse import urlencode # pylint: disable=bad-option-value,relative-import
9from icloudpy.exceptions import (
10 ICloudPyAPIResponseException,
11 ICloudPyLibraryUnavailableException,
12 ICloudPyServiceNotActivatedException,
13)
15LOGGER = logging.getLogger(__name__)
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"})
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",)
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
36def _zone_post(session, url, data, zone_name):
37 """POST a zone-scoped query, labelling definitive zone rejections.
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
56class PhotoLibrary:
57 """Represents a library in the user's photos.
59 This provides access to all the albums as well as the photos.
60 """
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 }
173 def __init__(self, service, zone_id, require_finished_index=True):
174 """Open a library, checking Apple's indexing state for its zone.
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
186 self._albums = None
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 )
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 )
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 }
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
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 ]
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
254 self._albums = albums
256 return self._albums
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 )
267 request = _zone_post(
268 self.service.session,
269 url,
270 json_data,
271 _zone_name(self.zone_id),
272 )
273 response = request.json()
275 return response["records"]
277 def zone_readable(self):
278 """Probe whether the zone answers album queries.
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
290 @property
291 def all(self):
292 return self.albums["All Photos"]
295class PhotosService(PhotoLibrary):
296 """The 'Photos' iCloud service.
298 This also acts as a way to access the user's primary library.
299 """
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"
307 self._libraries = None
309 self.params.update({"remapEnums": True, "getCurrentSyncToken": True})
311 self._photo_assets = {}
312 self._require_finished_index = require_finished_index
314 super().__init__(
315 service=self,
316 zone_id={"zoneName": "PrimarySync"},
317 require_finished_index=require_finished_index,
318 )
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"]
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
368 self._libraries = libraries
370 return self._libraries
373class PhotoAlbum:
374 """A photo album."""
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
397 if zone_id:
398 self._zone_id = zone_id
399 else:
400 self._zone_id = {"zoneName": "PrimarySync"}
402 self._len = None
404 self._subalbums = {}
406 @property
407 def title(self):
408 """Gets the album name."""
409 return self.name
411 def __iter__(self):
412 return self.photos
414 def iter_chunks(self, chunk_size=1000):
415 """Yield lists of PhotoAsset objects in fixed-size batches.
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.
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.
431 Args:
432 chunk_size: Max number of PhotoAsset objects per yielded
433 list. Values <= 0 are coerced to the default (1000).
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
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()
484 self._len = response["batch"][0]["records"][0]["fields"]["itemCount"]["value"]
486 return self._len
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()
523 return response["records"]
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
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 ]
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
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
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()
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)
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
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
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 }
738 if query_filter:
739 query["query"]["filterBy"].extend(query_filter)
741 return query
743 def __unicode__(self):
744 return self.title
746 def __str__(self):
747 return self.__unicode__()
749 def __repr__(self):
750 return f"<{type(self).__name__}: '{self}'>"
753class PhotoAsset:
754 """A photo."""
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
762 self._versions = None
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 }
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 }
809 VIDEO_VERSION_LOOKUP = {
810 "full": "resVidFull",
811 "medium": "resVidMed",
812 "thumb": "resVidSmall",
813 "original": "resOriginal",
814 "original_compl": "resOriginalVidCompl",
815 }
817 @property
818 def id(self):
819 """Gets the photo id."""
820 return self._master_record["recordName"]
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
833 @property
834 def size(self):
835 """Gets the photo size."""
836 return self._master_record["fields"]["resOriginalRes"]["value"]["size"]
838 @property
839 def created(self):
840 """Gets the photo created date."""
841 return self.asset_date
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)
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 )
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 )
870 @property
871 def item_type(self):
872 """Returns 'image' or 'movie' for this asset.
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.
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]
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
898 @property
899 def versions(self):
900 """Gets the photo versions.
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.
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.
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
931 asset_fields = (self._asset_record or {}).get("fields", {})
932 master_fields = self._master_record["fields"]
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}
939 width_entry = fields.get(f"{prefix}Width")
940 if width_entry:
941 version["width"] = width_entry["value"]
942 else:
943 version["width"] = None
945 height_entry = fields.get(f"{prefix}Height")
946 if height_entry:
947 version["height"] = height_entry["value"]
948 else:
949 version["height"] = None
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
959 type_entry = fields.get(f"{prefix}FileType")
960 if type_entry:
961 version["type"] = type_entry["value"]
962 else:
963 version["type"] = None
965 self._versions[key] = version
967 return self._versions
969 def download(self, version="original", **kwargs):
970 """Returns the photo file."""
971 if version not in self.versions:
972 return None
974 return self._service.session.get(
975 self.versions[version]["url"],
976 stream=True,
977 **kwargs,
978 )
980 @property
981 def zone_id(self):
982 """The CloudKit zone of the library this photo belongs to.
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
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 )
1012 endpoint = self._service._service_endpoint
1013 params = urlencode(self._service.params)
1014 url = f"{endpoint}/records/modify?{params}"
1016 return self._service.session.post(
1017 url,
1018 data=json_data,
1019 headers={"Content-type": "text/plain"},
1020 )
1022 def __repr__(self):
1023 return f"<{type(self).__name__}: id={self.id}>"