pyicloud

The iCloud Photo Library is accessed via the api.photos property.

Browsing Photos:

• api.photos.all: Access the 'All Photos' album. This album is sorted by added_date (most recent first).
• api.photos.albums['AlbumName']: Access specific albums. These are sorted by asset_date (EXIF date).
• Iterating over an album yields PhotoAsset objects.

Downloading Photos:

• Use photo.download() to download the original version. This returns a requests.Response object with stream=True. Use download.raw.read() or a buffered strategy like shutil.copyfile to save the file.
• Versions: Each photo has a .versions property (e.g., ['medium', 'original', 'thumb']). To download a specific version, pass the version key to the download method: photo.download('thumb').

Photo Metadata:

• photo.filename: The filename of the asset.
• photo.versions[version_key]['filename']: The filename associated with a specific version.

iCloud Drive is accessed via the api.drive property. It uses a dictionary-like interface to navigate directories and files.

Navigation:

• Use api.drive.dir() to list contents of the root.
• Access folders and files using bracket notation: api.drive['Folder']['Subfolder']['file.ext'].
• Use .dir() on a folder object to list its contents.

File Metadata:

• .name: The filename.
• .date_modified: The modification timestamp (in UTC).
• .size: File size in bytes.
• .type: Returns 'file' for files.

File Operations:

• Download: Use .open(stream=True) to get a response object. It is recommended to use shutil.copyfileobj with response.raw to save the file to disk efficiently.
• Upload: Use .upload(file_like_object) on a folder object. Always open local files in binary mode ('rb') to avoid decoding errors.
• Management: Use .mkdir('name'), .rename('new_name'), and .delete() on folder or file objects.

To debug network traffic using tools like mitmproxy, fiddler, or charles, you can monkeypatch requests.Session.merge_environment_settings to disable SSL verification. This allows the library to work even when intercepting proxies are used. Additionally, you can enable full HTTP debugging by patching http.client.print to use the logging framework and setting http.client.HTTPConnection.debuglevel = 1.

import http.client
import logging
import requests
import warnings
from urllib3.exceptions import InsecureRequestWarning
from pyicloud import PyiCloudService

# 1. Disable SSL verification for requests
old_merge_environment_settings = requests.Session.merge_environment_settings

def merge_environment_settings(self, url, proxies, stream, verify, cert):
    settings = old_merge_environment_settings(self, url, proxies, stream, verify, cert)
    settings["verify"] = False
    return settings

requests.Session.merge_environment_settings = merge_environment_settings

# 2. Enable HTTP client debug logging
httpclient_logger = logging.getLogger("http.client")
def httpclient_logging_patch(level=logging.DEBUG):
    def httpclient_log(*args):
        httpclient_logger.log(level, " ".join(args))
    http.client.print = httpclient_log
    http.client.HTTPConnection.debuglevel = 1

logging.basicConfig(level=logging.DEBUG)
httpclient_logging_patch()

# 3. Use the API
with warnings.catch_warnings():
    warnings.simplefilter("ignore", InsecureRequestWarning)
    api = PyiCloudService(username, password)
    # Perform requests...