This is the internal code reference for gphotos_sync

gphotos_sync.__version__: str

Version number as calculated by setuptools_scm



class gphotos_sync.BaseMedia.BaseMedia(root_path: Path = PosixPath('.'), **k_args)[source]

Base class for media model classes. These provide a standard interface for media items that have been loaded from disk / loaded from DB / retrieved from the Google Photos Library


class gphotos_sync.DatabaseMedia.DatabaseMedia(_id: str = '', _uid: str = '', _url: str = '', _relative_folder: Path = PosixPath('.'), _filename: str = '', _orig_name: str = '', _duplicate_number: int = 0, _size: int = 0, _mime_type: str = '', _description: str = '', _date: datetime = datetime.datetime(1900, 1, 1, 0, 0), _create_date: datetime = datetime.datetime(1900, 1, 1, 0, 0), _downloaded: bool = False, _location: str = '')[source]

A Class for reading and writing BaseMedia objects to and from database tables

The standard BaseMedia attributes are represented here. This dumb class is used for representing any MediaBase derived class that has been read out of the Database.


remote identifier from Google Photos


the ‘product URL’ which takes you to the Web view for this file


root relative path to file


local filename


as above minus any duplicate number suffix


which instance if > 1 file has same orig_name


files size on disk


string representation of file type


modification date


creation date


true if previously downloaded to disk

property location: str | None

image GPS information

property description: str

The description of the file

property orig_name: str

Original filename before duplicate name handling

property filename: str

filename including a suffix to make it unique if duplicates exist

property create_date: datetime

Creation date

property modify_date: datetime

Modify Date

property url: str

Remote url to retrieve this file from the server





class gphotos_sync.GooglePhotosDownload.GooglePhotosDownload(api: RestClient, root_folder: Path, db: LocalData, settings: Settings)[source]

A Class for managing the indexing and download of Google Photos

  • api – object representing the Google REST API

  • root_folder – path to the root of local file synchronization

  • db – local database for indexing

  • settings – further arguments


here we batch up our requests to get base url for downloading media. This avoids the overhead of one REST call per file. A REST call takes longer than downloading an image

download_batch(batch: Mapping[str, DatabaseMedia])[source]

Downloads a batch of media items collected in download_photo_media.

A fresh ‘base_url’ is required since they have limited lifespan and these are obtained by a single call to the service function mediaItems.batchGet.

download_file(media_item: DatabaseMedia, media_json: dict)[source]

farms a single media download off to the thread pool.

Uses a dictionary of Futures -> mediaItem to track downloads that are currently scheduled/running. When a Future is done it calls do_download_complete to remove the Future from the dictionary and complete processing of the media item.

do_download_file(base_url: str, media_item: DatabaseMedia)[source]

Runs in a process pool and does a download of a single media item.

do_download_complete(futures_list: Mapping[Future, DatabaseMedia] | List[Future])[source]

runs in the main thread and completes processing of a media item once (multi threaded) do_download has completed

find_bad_items(batch: Mapping[str, DatabaseMedia])[source]

a batch get failed. Now do all of its contents as individual gets so we can work out which ID(s) cause the failure