deploy: 24632d3

gilesknap · May 18, 2024 · 4b897de · 4b897de
1 parent 0244ff0
commit 4b897de
Show file tree

Hide file tree

Showing 120 changed files with 12,278 additions and 0 deletions.
diff --git a/fix-pr/.buildinfo b/fix-pr/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: e11022316d94a019e95560bdfd050ccc
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/fix-pr/.doctrees/environment.pickle b/fix-pr/.doctrees/environment.pickle
diff --git a/fix-pr/.doctrees/explanations.doctree b/fix-pr/.doctrees/explanations.doctree
diff --git a/fix-pr/.doctrees/explanations/folders.doctree b/fix-pr/.doctrees/explanations/folders.doctree
diff --git a/fix-pr/.doctrees/explanations/googleapiissues.doctree b/fix-pr/.doctrees/explanations/googleapiissues.doctree
diff --git a/fix-pr/.doctrees/explanations/notes.doctree b/fix-pr/.doctrees/explanations/notes.doctree
diff --git a/fix-pr/.doctrees/explanations/tokens.doctree b/fix-pr/.doctrees/explanations/tokens.doctree
diff --git a/fix-pr/.doctrees/how-to.doctree b/fix-pr/.doctrees/how-to.doctree
diff --git a/fix-pr/.doctrees/how-to/comparison.doctree b/fix-pr/.doctrees/how-to/comparison.doctree
diff --git a/fix-pr/.doctrees/how-to/cron.doctree b/fix-pr/.doctrees/how-to/cron.doctree
diff --git a/fix-pr/.doctrees/how-to/windows.doctree b/fix-pr/.doctrees/how-to/windows.doctree
diff --git a/fix-pr/.doctrees/index.doctree b/fix-pr/.doctrees/index.doctree
diff --git a/fix-pr/.doctrees/reference.doctree b/fix-pr/.doctrees/reference.doctree
diff --git a/fix-pr/.doctrees/reference/api.doctree b/fix-pr/.doctrees/reference/api.doctree
diff --git a/fix-pr/.doctrees/reference/contributing.doctree b/fix-pr/.doctrees/reference/contributing.doctree
diff --git a/fix-pr/.doctrees/tutorials.doctree b/fix-pr/.doctrees/tutorials.doctree
diff --git a/fix-pr/.doctrees/tutorials/installation.doctree b/fix-pr/.doctrees/tutorials/installation.doctree
diff --git a/fix-pr/.doctrees/tutorials/login.doctree b/fix-pr/.doctrees/tutorials/login.doctree
diff --git a/fix-pr/.doctrees/tutorials/oauth2.doctree b/fix-pr/.doctrees/tutorials/oauth2.doctree
diff --git a/fix-pr/_images/0.png b/fix-pr/_images/0.png
diff --git a/fix-pr/_images/01-sign-in.png b/fix-pr/_images/01-sign-in.png
diff --git a/fix-pr/_images/02-verify.png b/fix-pr/_images/02-verify.png
diff --git a/fix-pr/_images/03-verify2.png b/fix-pr/_images/03-verify2.png
diff --git a/fix-pr/_images/04-access.png b/fix-pr/_images/04-access.png
diff --git a/fix-pr/_images/1.png b/fix-pr/_images/1.png
diff --git a/fix-pr/_images/10-test_users.png b/fix-pr/_images/10-test_users.png
diff --git a/fix-pr/_images/11-summary.png b/fix-pr/_images/11-summary.png
diff --git a/fix-pr/_images/12-create_creds.png b/fix-pr/_images/12-create_creds.png
diff --git a/fix-pr/_images/14-create_id.png b/fix-pr/_images/14-create_id.png
diff --git a/fix-pr/_images/15-created.png b/fix-pr/_images/15-created.png
diff --git a/fix-pr/_images/2.png b/fix-pr/_images/2.png
diff --git a/fix-pr/_images/3.png b/fix-pr/_images/3.png
diff --git a/fix-pr/_images/4.png b/fix-pr/_images/4.png
diff --git a/fix-pr/_images/5.png b/fix-pr/_images/5.png
diff --git a/fix-pr/_images/6.png b/fix-pr/_images/6.png
diff --git a/fix-pr/_images/7-oauth_concent.png b/fix-pr/_images/7-oauth_concent.png
diff --git a/fix-pr/_images/8-app_registration.png b/fix-pr/_images/8-app_registration.png
diff --git a/fix-pr/_images/9-scopes.png b/fix-pr/_images/9-scopes.png
diff --git a/fix-pr/_modules/gphotos_sync/BaseMedia.html b/fix-pr/_modules/gphotos_sync/BaseMedia.html
diff --git a/fix-pr/_modules/gphotos_sync/DatabaseMedia.html b/fix-pr/_modules/gphotos_sync/DatabaseMedia.html
diff --git a/fix-pr/_modules/gphotos_sync/GooglePhotosDownload.html b/fix-pr/_modules/gphotos_sync/GooglePhotosDownload.html
diff --git a/fix-pr/_modules/index.html b/fix-pr/_modules/index.html
@@ -0,0 +1,163 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" data-content_root="../">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Overview: module code &mdash; gphotos-sync 3.2.3.dev1+g24632d3 documentation</title>
+      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
+      <link rel="stylesheet" type="text/css" href="../_static/graphviz.css?v=fd3f3429" />
+      <link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css?v=e20ccd95" />
+
+
+    <link rel="shortcut icon" href="../_static/logo.png"/>
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+
+        <script src="../_static/jquery.js?v=5d32c60e"></script>
+        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+        <script src="../_static/documentation_options.js?v=a403ad80"></script>
+        <script src="../_static/doctools.js?v=9a2dae69"></script>
+        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script src="../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search"  style="background: rgb(7, 43, 93)" >
+
+
+
+          <a href="../index.html" class="icon icon-home">
+            gphotos-sync
+              <img src="../_static/logo.png" class="logo" alt="Logo"/>
+          </a>
+              <div class="version">
+                main
+              </div>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Initial Setup</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html#execute-in-a-container">Execute in a container</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html#local-installation">Local Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html#running-gphotos-sync">Running gphotos-sync</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/oauth2.html">Creating an OAuth Client ID</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/login.html">User Login OAuth Flow</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">How-to Guides</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../how-to/windows.html">Additional Setup for Windows Machines</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../how-to/windows.html#initial-setup-on-windows-for-docker-desktop">Initial Setup on Windows for Docker desktop</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../how-to/cron.html">Scheduling a Regular Backup</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../how-to/comparison.html">Comparing The Google Photos Library With Local files</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">Explanations</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../explanations/folders.html">Folder Layout</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanations/notes.html">Why is Google Photos Sync Read Only</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanations/tokens.html">Google OAuth Tokens for gphotos-sync</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanations/googleapiissues.html">Known Issues</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">Reference</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../reference/contributing.html">Contributing</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/api.html">API</a></li>
+<li class="toctree-l1"><a class="reference external" href="https://github.com/gilesknap/gphotos-sync/releases">Releases</a></li>
+</ul>
+
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu"  style="background: rgb(7, 43, 93)" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">gphotos-sync</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
+      <li class="breadcrumb-item active">Overview: module code</li>
+      <li class="wy-breadcrumbs-aside">
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+
+  <h1>All modules for which code is available</h1>
+<ul><li><a href="gphotos_sync/BaseMedia.html">gphotos_sync.BaseMedia</a></li>
+<li><a href="gphotos_sync/DatabaseMedia.html">gphotos_sync.DatabaseMedia</a></li>
+<li><a href="gphotos_sync/GooglePhotosDownload.html">gphotos_sync.GooglePhotosDownload</a></li>
+</ul>
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p></p>
+  </div>
+
+
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script>
+
+  <div id="other-versions-div" class="rst-versions" data-toggle="rst-versions" role="note" aria-label="Versions" style="visibility: hidden">
+    <span class="rst-current-version" data-toggle="rst-current-version">
+      <span class="fa fa-book"> Other Versions</span>
+      main
+      <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+      <dl id="other-versions-dl"/>
+    </div>
+  </div>
+  <script>
+    function addVersion(name) {
+      var dd = document.createElement("dd");
+      var a = document.createElement("a");
+      a.href = "../../" + name;
+      a.innerText = name;
+      dd.appendChild(a);
+      document.getElementById('other-versions-dl').appendChild(dd);
+    }
+    // Get versions.txt and add a version for each line
+    fetch("../../versions.txt").then(response => {
+      if (response.ok) {
+        document.getElementById('other-versions-div').style.visibility = "visible";
+        return response.text().then(text => text.split(/\r?\n/).forEach(addVersion))
+      }
+    });
+  </script>
+
+
+</body>
+</html>
diff --git a/fix-pr/_sources/explanations.rst.txt b/fix-pr/_sources/explanations.rst.txt
@@ -0,0 +1,14 @@
+:orphan:
+
+Explanations
+============
+
+Explanation of how the library works and why it works that way.
+
+.. toctree::
+    :caption: Explanations
+
+    explanations/folders
+    explanations/notes
+    explanations/tokens
+    explanations/googleapiissues
diff --git a/fix-pr/_sources/explanations/folders.rst.txt b/fix-pr/_sources/explanations/folders.rst.txt
@@ -0,0 +1,43 @@
+.. _Folders:
+
+Folder Layout
+=============
+
+After doing a full sync you will have 2 directories off of the specified root:
+
+Media Files
+-----------
+
+photos:
+    contains all photos and videos from your Google Photos Library organized 
+    into folders with the structure 'photos/YYYY/MM' where 'YYYY/MM' is 
+    the date the photo/video was taken. The filenames within a folder will 
+    be as per the original upload except that duplicate names will have a 
+    suffix ' (n)' where n is the duplicate number of the file (this matches 
+    the approach used in the official Google tool for Windows).
+
+albums:
+    contains a folder hierarchy representing the set of albums and shared
+    albums in your library. All the files are symlinks to content in the photos
+    folder. The folder names will be 'albums/YYYY/MM Original Album Name'.
+
+Note that these are the default layouts and you can change what is downloaded
+and how it is layed out with command line options. See the help for details::
+
+    gphotos-sync --help
+
+Other Files
+-----------
+
+The following files will also appear in the root folder:-
+
+  - gphotos.sqlite: the database that tracks what files have been indexed,
+    you can open this with sqlite3 to examine what media and metadata you have.
+  - gphotos.log: a log of the most recent run, including debug info       
+  - gphotos.lock: the lock file used to make sure only one gphotos-sync runs
+    at a time   
+  - gphotos.trace: a trace file if logging is set to trace level. This logs 
+    the calls to the Google Photos API. 
+  - gphotos.bad_ids.yaml: A list of bad entries that cause the API to get 
+    an error when downloading. Delete this file to retry downloading these
+    bad items.
diff --git a/fix-pr/_sources/explanations/googleapiissues.rst.txt b/fix-pr/_sources/explanations/googleapiissues.rst.txt
@@ -0,0 +1,71 @@
+Known Issues
+============
+
+
+Known Issues with Google API
+----------------------------
+A few outstanding limitations of the Google API restrict what can be achieved. 
+All these issues have been reported to Google and this project will be updated 
+once they are resolved.
+
+Unfortunately, a number of quite significant issues have remained unfixed for 
+several years. I'm starting a discussion group in this repo for people to
+discuss workarounds, and collect reports of how these things are affecting 
+users. I intend to link this discussion group in the Google issue trackers
+to see if it will encourage some response from Google.
+
+To join the discussion go here 
+https://github.com/gilesknap/gphotos-sync/discussions.
+
+Pending API Issues
+~~~~~~~~~~~~~~~~~~
+
+-   There is no way to discover modified date of library media items. Currently 
+    ``gphotos-sync`` will refresh your local copy with any new photos added since 
+    the last scan but will not update any photos that have been modified in 
+    Google Photos.
+
+    - https://issuetracker.google.com/issues/122737849.
+
+
+-   GOOGLE WON'T FIX. The API strips GPS data from images.
+
+    - https://issuetracker.google.com/issues/80379228.
+
+-   Video download transcodes the videos even if you ask for the original file 
+    (=vd parameter). My experience is that the result is looks similar to the original
+    but the compression is more clearly visible. It is a smaller file with 
+    approximately 60% bitrate (same resolution).
+
+    - https://issuetracker.google.com/issues/80149160
+
+-   Photo download compresses the photos even if you ask for the original file 
+    (=d parameter). This is similar to the above issue, except in my experience 
+    is is nearly impossible to notice a loss in quality. It
+    is a file compressed to approximately 60% of the original size (same resolution).
+
+    - https://issuetracker.google.com/issues/112096115
+
+-   Burst shots are not supported. You will only see the first file of a burst shot.
+
+    - https://issuetracker.google.com/issues/124656564
+
+Fixed API Issues
+~~~~~~~~~~~~~~~~
+-   FIXED BY GOOGLE. Some types of video will not download using the new API.
+
+    - https://issuetracker.google.com/issues/116842164.
+    - https://issuetracker.google.com/issues/141255600
+
+Other Issues
+------------
+- Some mounted filesystems including NFS, CIFS and AFP do not support file locks 
+  and database access will fail on them.
+
+  - To fix, use the parameter --db-path to specify a location for your DB on 
+    the local disk. This will perform better anyway.
+
+GPS workaround
+--------------
+For a workaround to the GPS issue described below see this project  
+https://github.com/DennyWeinberg/manager-for-google-photos
diff --git a/fix-pr/_sources/explanations/notes.rst.txt b/fix-pr/_sources/explanations/notes.rst.txt
@@ -0,0 +1,17 @@
+Why is Google Photos Sync Read Only
+===================================
+
+Google Photos Sync is a backup tool only. It never makes any changes to your
+Google Photos Library in the cloud. There are two primary reasons for this:
+
+- The Photos API provided by Google is far too restricted to make changes 
+  in any meaningful way. For example
+
+  - there is no delete function
+  - you cannot add photos to an album unless it was created by the same
+    application that is trying to add photos
+
+- Even if the API allowed it, this would be a very hard problem, because
+  it is often hard to identify if a local photo or video matches one in the 
+  cloud. Besides this, I would not want the resposibility of potentially 
+  trashing someone's photo collection. 
diff --git a/fix-pr/_sources/explanations/tokens.rst.txt b/fix-pr/_sources/explanations/tokens.rst.txt
@@ -0,0 +1,55 @@
+.. _Tokens:
+
+Google OAuth Tokens for gphotos-sync
+====================================
+
+Introduction
+------------
+
+There are two kinds of authentication required to run gphotos-sync.
+
+  - First the application must authenticate with Google to authorize the use
+    of the Google Photos API. This gives it permission to perform the 
+    second authentication step.
+  - Second, an individual User Account must me authenticated to allow access
+    to that user's Google Photos Library.
+
+The secret information that enables these authentication steps is held in 
+two files:
+
+  - client_secret.json holds the OAuth application ID that allows the 
+    first step. This is stored in an application configuration folder.
+    There is only one of these files per installation of gphotos-sync.
+    See `Client ID` for details of creating this file.
+  - .gphotos.token holds the user token for each user you are backing up 
+    photos for. This resides in the root folder of the library backup.
+    See `Login` for details of creating this file.
+
+Why Do We Need Client ID ?
+--------------------------
+
+The expected use of the client ID is that a vendor provides a single ID
+for their application, Google verifies the application and then anyone 
+can use it.
+
+In this scenario ALL Google API calls would count against the vendor's
+account. They would be charged for use of those APIs and they would
+need to charge their users to make this worthwhile.
+
+If I was to provide my own client ID with gphotos-sync then I would need
+to charge a subscription to cover API costs.
+
+Since this is FOSS I ask every user to create their own client ID
+so they can take advantage of the free tier of Google API use that is 
+available to every user.
+
+Most normal use of gphotos-sync does not exceed the free tier. If it does
+you will not be charged. The code is supposed to throttle back and go slower
+to drop back into the free usage rate. However there is an issue with this 
+feature at present and you will likely see an error:
+
+    ``429 Client Error: Too Many Requests for url``. 
+
+See https://github.com/gilesknap/gphotos-sync/issues/320,
+https://github.com/gilesknap/gphotos-sync/issues/202 for details and 
+workarounds.
diff --git a/fix-pr/_sources/how-to.rst.txt b/fix-pr/_sources/how-to.rst.txt
@@ -0,0 +1,13 @@
+:orphan:
+
+How-to Guides
+=============
+
+Practical step-by-step guides for the more experienced user.
+
+.. toctree::
+    :caption: How-to Guides
+
+    how-to/windows
+    how-to/cron
+    how-to/comparison