Merge lp:~ed.so/duplicity/gdocs.pydrive into lp:~duplicity-team/duplicity/0.7-series

[edso]

make pydrive new gdocs default backend
keep gdata backend as gdata+gdocs://

[lp:~ed.so/duplicity/gdocs.pydrive]

1098. By ede on 2015-05-31

manpage - some reordering, update "A NOTE ON SSH BACKENDS" to the new prefix+ changes

=== modified file 'bin/duplicity.1'
--- bin/duplicity.1	2015-05-30 11:53:02 +0000
+++ bin/duplicity.1	2015-05-31 14:31:15 +0000
@@ -1037,13 +1037,16 @@
 ftp[s]://user[:password]@other.host[:port]/some_dir
 .PP
 .B NOTE:
-use lftp+, ncftp+ prefixes to enforce a specific backend, e.g. ncftp+ftp://...
+use lftp+, ncftp+ prefixes to enforce a specific backend, default is lftp+ftp://...
 .RE
 .PP
 .B "Google Docs"
 .PP
 .RS
 gdocs://user[:password]@other.host/some_dir
+.PP
+.B NOTE:
+use pydrive+, gdata+ prefixes to enforce a specific backend, default is pydrive+gdocs://...
 .RE
 .PP
 .B "Google Cloud Storage"
@@ -1614,6 +1617,43 @@
 .B from_address_prefix
 will distinguish between different backups.
 
+.SH A NOTE ON MULTI BACKEND
+
+The multi backend allows duplicity to combine the storage available in
+more than one backend store (e.g., you can store across a google drive
+account and a onedrive account to get effectively the combined storage
+available in both).  The URL path specifies a JSON formated config
+file containing a list of the backends it will use. Multibackend then
+round-robins across the given backends.  Each element of the list must
+have a "url" element, and may also contain an optional "description"
+and an optional "env" list of environment variables used to configure
+that backend.
+.PP
+For example:
+.nf
+.RS
+[
+ {
+  "description": "a comment about the backend"
+  "url": "abackend://[e-mail]/backup",
+  "env": [
+    {
+     "name" : "MYENV",
+     "value" : "xyz"
+    },
+    {
+     "name" : "FOO",
+     "value" : "bar"
+    }
+   ]
+ },
+ {
+  "url": "file:///path/to/dir"
+ }
+]
+.RE
+.fi
+
 .SH A NOTE ON PAR2 WRAPPER BACKEND
 Par2 Wrapper Backend can be used in combination with all other backends to
 create recovery files. Just add
@@ -1632,6 +1672,62 @@
 to adjust the size (and redundancy) of recovery files in
 .I percent.
 
+.SH A NOTE ON PYDRIVE BACKEND
+The pydrive backend requires Python PyDrive package to be installed on the system. See
+.B REQUIREMENTS
+above.
+
+There are two ways to use PyDrive: with a regular account or with a
+"service account". With a service account, a separate account is
+created, that is only accessible with Google APIs and not a web login.
+With a regular account, you can store backups in your normal Google
+Drive.
+
+To use a service account, go to the Google developers
+console at https://console.developers.google.com. Create a project,
+and make sure Drive API is enabled for the project. Under "APIs and
+auth", click Create New Client ID, then select Service Account with P12
+key.
+
+Download the .p12 key file of the account and convert it to the .pem format:
+.br
+openssl pkcs12 -in XXX.p12  -nodes -nocerts > pydriveprivatekey.pem
+
+The content of .pem file should be passed to
+.BR GOOGLE_DRIVE_ACCOUNT_KEY
+environment variable for authentification.
+
+The email address of the account will be used as part of URL. See
+.B URL FORMAT
+above.
+
+The alternative is to use a regular account. To do this, start as above,
+but when creating a new Client ID, select "Installed application" of
+type "Other". Create a file with the following content, and pass its
+filename in the
+.BR GOOGLE_DRIVE_SETTINGS
+environment variable:
+.PP
+.nf
+.RS
+client_config_backend: settings
+client_config:
+    client_id: <Client ID from developers' console>
+    client_secret: <Client secret from developers' console>
+save_credentials: True
+save_credentials_backend: file
+save_credentials_file: <filename to cache credentials>
+get_refresh_token: True
+.RE
+.fi
+
+In this scenario, the username and host parts of the URL play no role;
+only the path matters. During the first run, you will be prompted to
+visit an URL in your browser to grant access to your drive. Once
+granted, you will receive a verification code to paste back into
+Duplicity. The credentials are then cached in the file references above
+for future use.
+
 .SH A NOTE ON SSH BACKENDS
 The
 .I ssh backends
@@ -1646,10 +1742,10 @@
 .IR sftp " or"
 .I scp/ssh
 access.
-To make it even more confusing the user can choose between two ssh backends via
-.BR --ssh-backend " option."
+To make it even more confusing the user can choose between several ssh backends via a scheme prefix:
+paramiko+ (default), pexpect+, lftp+... . 
 .br
-Both support
+paramiko & pexpect support
 .BR --use-scp ,
 .BR --ssh-askpass " and"
 .BR --ssh-options "."
@@ -1659,7 +1755,7 @@
 .BR --scp-command " and"
 .BR --sftp-command .
 .PP
-.BR "SSH paramiko backend " "(selected by default)"
+.BR "SSH paramiko backend " "(default)"
 is a complete reimplementation of ssh protocols natively in python. Advantages
 are speed and maintainability. Minor disadvantage is that extra packages are
 needed as listed in
@@ -1686,6 +1782,10 @@
 .I --use-scp
 option is used to revert to old behavior.
 .PP
+.B SSH lftp backend
+is simply there because lftp can interact with the ssh cmd line binaries.
+It is meant as a last resort in case the above options fail for some reason.
+.PP
 .B Why use sftp instead of scp?
 The change to sftp was made in order to allow the remote system to chroot the backup,
 thus providing better security and because it does not suffer from shell quoting issues like scp.
@@ -1750,99 +1850,6 @@
 .B SWIFT_AUTHVERSION
 is unspecified, it will default to version 1.
 
-.SH A NOTE ON PYDRIVE BACKEND
-The pydrive backend requires Python PyDrive package to be installed on the system. See
-.B REQUIREMENTS
-above.
-
-There are two ways to use PyDrive: with a regular account or with a
-"service account". With a service account, a separate account is
-created, that is only accessible with Google APIs and not a web login.
-With a regular account, you can store backups in your normal Google
-Drive.
-
-To use a service account, go to the Google developers
-console at https://console.developers.google.com. Create a project,
-and make sure Drive API is enabled for the project. Under "APIs and
-auth", click Create New Client ID, then select Service Account with P12
-key.
-
-Download the .p12 key file of the account and convert it to the .pem format:
-.br
-openssl pkcs12 -in XXX.p12  -nodes -nocerts > pydriveprivatekey.pem
-
-The content of .pem file should be passed to
-.BR GOOGLE_DRIVE_ACCOUNT_KEY
-environment variable for authentification.
-
-The email address of the account will be used as part of URL. See
-.B URL FORMAT
-above.
-
-The alternative is to use a regular account. To do this, start as above,
-but when creating a new Client ID, select "Installed application" of
-type "Other". Create a file with the following content, and pass its
-filename in the
-.BR GOOGLE_DRIVE_SETTINGS
-environment variable:
-.PP
-.nf
-.RS
-client_config_backend: settings
-client_config:
-    client_id: <Client ID from developers' console>
-    client_secret: <Client secret from developers' console>
-save_credentials: True
-save_credentials_backend: file
-save_credentials_file: <filename to cache credentials>
-get_refresh_token: True
-.RE
-.fi
-
-In this scenario, the username and host parts of the URL play no role;
-only the path matters. During the first run, you will be prompted to
-visit an URL in your browser to grant access to your drive. Once
-granted, you will receive a verification code to paste back into
-Duplicity. The credentials are then cached in the file references above
-for future use.
-
-.SH A NOTE ON MULTI BACKEND
-
-The multi backend allows duplicity to combine the storage available in
-more than one backend store (e.g., you can store across a google drive
-account and a onedrive account to get effectively the combined storage
-available in both).  The URL path specifies a JSON formated config
-file containing a list of the backends it will use. Multibackend then
-round-robins across the given backends.  Each element of the list must
-have a "url" element, and may also contain an optional "description"
-and an optional "env" list of environment variables used to configure
-that backend.
-.PP
-For example:
-.nf
-.RS
-[
- {
-  "description": "a comment about the backend"
-  "url": "abackend://[e-mail]/backup",
-  "env": [
-    {
-     "name" : "MYENV",
-     "value" : "xyz"
-    },
-    {
-     "name" : "FOO",
-     "value" : "bar"
-    }
-   ]
- },
- {
-  "url": "file:///path/to/dir"
- }
-]
-.RE
-.fi
-
 .SH A NOTE ON SYMMETRIC ENCRYPTION AND SIGNING
 Signing and symmetrically encrypt at the same time with the gpg binary on the
 command line, as used within duplicity, is a specifically challenging issue.
@@ -1957,10 +1964,13 @@
 .B python-urllib3
 - https://github.com/shazow/urllib3
 .TP
-.BR "gdocs backend" " (Google Docs)"
+.BR "gdocs gdata backend" " (legacy Google Docs backend)"
 .B Google Data APIs Python Client Library
 - http://code.google.com/p/gdata-python-client/
 .TP
+.BR "gdocs pydrive backend" "(default)"
+see pydrive backend
+.TP
 .BR "gio backend" " (Gnome VFS API)"
 .B PyGObject
 - http://live.gnome.org/PyGObject
@@ -1976,6 +1986,17 @@
 .B Python library for mega API
 - https://github.com/ckornacker/mega.py, ubuntu ppa - ppa:ckornacker/backup
 .TP
+.BR "multi backend"
+.B Multi -- store to more than one backend
+.br
+(also see
+.BR "A NOTE ON MULTI BACKEND"
+) below.
+.TP
+.BR "ncftp backend" " (ftp, select via ncftp+ftp://)"
+.B NcFTP
+- http://www.ncftp.com/
+.TP
 .BR "OneDrive backend" " (Microsoft OneDrive)"
 .B python-requests
 - http://python-requests.org
@@ -1983,24 +2004,23 @@
 .B python-requests-oauthlib
 - https://github.com/requests/requests-oauthlib
 .TP
-.BR "ncftp backend" " (ftp, select via ncftp+ftp://)"
-.B NcFTP
-- http://www.ncftp.com/
-.TP
 .B "Par2 Wrapper Backend"
 .B par2cmdline
 - http://parchive.sourceforge.net/
 .TP
+.BR "pydrive backend"
+.B PyDrive -- a wrapper library of google-api-python-client
+- https://pypi.python.org/pypi/PyDrive
+.br
+(also see
+.BR "A NOTE ON PYDRIVE BACKEND"
+) below.
+.TP
 .B "rsync backend"
 .B rsync client binary
 - http://rsync.samba.org/
-.PP
-There are two
-.B ssh backends
-for scp/sftp/ssh access (also see
-.BR "A NOTE ON SSH BACKENDS" ).
 .TP
-.BR "ssh paramiko backend" " (enabled by default)"
+.BR "ssh paramiko backend" " (default)"
 .B paramiko
 (SSH2 for python)
 - http://pypi.python.org/pypi/paramiko (downloads); http://github.com/paramiko/paramiko (project page)
@@ -2030,22 +2050,6 @@
 .br
 (also see
 .BR "A NOTE ON SSL CERTIFICATE VERIFICATION" ).
-.TP
-.BR "pydrive backend"
-.B PyDrive -- a wrapper library of google-api-python-client
-- https://pypi.python.org/pypi/PyDrive
-.br
-(also see
-.BR "A NOTE ON PYDRIVE BACKEND"
-) below.
-.TP
-.BR "multi backend"
-.B Multi -- store to more than one backend
-.br
-(also see
-.BR "A NOTE ON MULTI BACKEND"
-) below.
-.br
 
 .SH AUTHOR
 .TP

=== modified file 'duplicity/backends/gdocsbackend.py'
--- duplicity/backends/gdocsbackend.py	2015-01-22 23:38:29 +0000
+++ duplicity/backends/gdocsbackend.py	2015-05-31 14:31:15 +0000
@@ -184,5 +184,6 @@
         # Done!
         return result
 
-duplicity.backend.register_backend('gdocs', GDocsBackend)
-duplicity.backend.uses_netloc.extend(['gdocs'])
+""" gdata is an alternate way to access gdocs, currently 05/2015 lacking OAuth support """
+duplicity.backend.register_backend('gdata+gdocs', GDocsBackend)
+duplicity.backend.uses_netloc.extend(['gdata+gdocs'])

=== modified file 'duplicity/backends/pydrivebackend.py'
--- duplicity/backends/pydrivebackend.py	2015-05-30 11:53:02 +0000
+++ duplicity/backends/pydrivebackend.py	2015-05-31 14:31:15 +0000
@@ -108,4 +108,9 @@
         return {'size': size}
 
 duplicity.backend.register_backend('pydrive', PyDriveBackend)
-duplicity.backend.uses_netloc.extend(['pydrive'])
+""" pydrive is an alternate way to access gdocs """
+duplicity.backend.register_backend('pydrive+gdocs', PyDriveBackend)
+""" register pydrive as the default way to access gdocs """
+duplicity.backend.register_backend('gdocs', PyDriveBackend)
+
+duplicity.backend.uses_netloc.extend(['pydrive','pydrive+gdocs','gdocs'])