lelit · Jul 28, 2016 · Jul 28, 2016 · Mar 1, 2017 · Mar 1, 2017 · Mar 1, 2017
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
@@ -521,6 +521,34 @@ Connection Objects
                  f.write('%s\n' % line)
 
 
+   .. method:: backup(filename, *, pages=0, progress=None)
+
+      This method makes a backup of a SQLite database into the mandatory argument
+      *filename*, even while it's being accessed by other clients, or concurrently by
+      the same connection.
+
+      By default, or when *pages* is either ``0`` or a negative integer, the entire
+      database is copied in a single step; otherwise the method performs a loop
+      copying up to the specified *pages* at a time.
+
+      If *progress* is specified, it must either ``None`` or a callable object that
+      will be executed at each iteration with two integer arguments, respectively the
+      *remaining* number of pages still to be copied and the *total* number of pages.
+
+      Example::
+
+         # Copy an existing database into another file
+         import sqlite3
+
+         def progress(remaining, total):
+             print(f"Copied {total-remaining} of {total} pages...")
+
+         con = sqlite3.connect('existing_db.db')
+         con.backup('copy_of_existing_db.db', 1, progress)
+
+      .. versionadded:: 3.7
+
+
 .. _sqlite3-cursor-objects:
 
 Cursor Objects

diff --git a/Lib/sqlite3/test/backup.py b/Lib/sqlite3/test/backup.py
@@ -0,0 +1,104 @@
+import sqlite3 as sqlite
+from tempfile import NamedTemporaryFile
+import unittest
+
+class BackupTests(unittest.TestCase):
+    def setUp(self):
+        cx = self.cx = sqlite.connect(":memory:")
+        cx.execute('CREATE TABLE foo (key INTEGER)')
+        cx.executemany('INSERT INTO foo (key) VALUES (?)', [(3,), (4,)])
+        cx.commit()
+
+    def tearDown(self):
+        self.cx.close()
+
+    def testBackup(self, bckfn):
+        cx = sqlite.connect(bckfn)
+        result = cx.execute("SELECT key FROM foo ORDER BY key").fetchall()
+        self.assertEqual(result[0][0], 3)
+        self.assertEqual(result[1][0], 4)
+
+    def CheckSimple(self):
+        with NamedTemporaryFile(suffix='.sqlite') as bckfn:
+            self.cx.backup(bckfn.name)
+            self.testBackup(bckfn.name)
+
+    def CheckProgress(self):
+        journal = []
+
+        def progress(remaining, total):
+            journal.append(remaining)
+
+        with NamedTemporaryFile(suffix='.sqlite') as bckfn:
+            self.cx.backup(bckfn.name, pages=1, progress=progress)
+            self.testBackup(bckfn.name)
+
+        self.assertEqual(len(journal), 2)
+        self.assertEqual(journal[0], 1)
+        self.assertEqual(journal[1], 0)
+
+    def CheckProgressAllPagesAtOnce_0(self):
+        journal = []
+
+        def progress(remaining, total):
+            journal.append(remaining)
+
+        with NamedTemporaryFile(suffix='.sqlite') as bckfn:
+            self.cx.backup(bckfn.name, progress=progress)
+            self.testBackup(bckfn.name)
+
+        self.assertEqual(len(journal), 1)
+        self.assertEqual(journal[0], 0)
+
+    def CheckProgressAllPagesAtOnce_1(self):
+        journal = []
+
+        def progress(remaining, total):
+            journal.append(remaining)
+
+        with NamedTemporaryFile(suffix='.sqlite') as bckfn:
+            self.cx.backup(bckfn.name, pages=-1, progress=progress)
+            self.testBackup(bckfn.name)
+
+        self.assertEqual(len(journal), 1)
+        self.assertEqual(journal[0], 0)
+
+    def CheckNonCallableProgress(self):
+        with NamedTemporaryFile(suffix='.sqlite') as bckfn:
+            with self.assertRaises(TypeError) as cm:
+                self.cx.backup(bckfn.name, pages=1, progress='bar')
+            self.assertEqual(str(cm.exception), 'progress argument must be a callable')
+
+    def CheckModifyingProgress(self):
+        journal = []
+
+        def progress(remaining, total):
+            if not journal:
+                self.cx.execute('INSERT INTO foo (key) VALUES (?)', (remaining+1000,))
+                self.cx.commit()
+            journal.append(remaining)
+
+        with NamedTemporaryFile(suffix='.sqlite') as bckfn:
+            self.cx.backup(bckfn.name, pages=1, progress=progress)
+            self.testBackup(bckfn.name)
+
+            cx = sqlite.connect(bckfn.name)
+            result = cx.execute("SELECT key FROM foo"
+                                " WHERE key >= 1000"
+                                " ORDER BY key").fetchall()
+            self.assertEqual(result[0][0], 1001)
+
+        self.assertEqual(len(journal), 3)
+        self.assertEqual(journal[0], 1)
+        self.assertEqual(journal[1], 1)
+        self.assertEqual(journal[2], 0)
+
+def suite():
+    return unittest.TestSuite(unittest.makeSuite(BackupTests, "Check"))
+
+def test():
+    runner = unittest.TextTestRunner()
+    runner.run(suite())
+
+if __name__ == "__main__":
+    test()
diff --git a/Lib/test/test_sqlite.py b/Lib/test/test_sqlite.py
@@ -7,7 +7,7 @@
 import sqlite3
 from sqlite3.test import (dbapi, types, userfunctions,
                                 factory, transactions, hooks, regression,
-                                dump)
+                                dump, backup)
 
 def load_tests(*args):
     if test.support.verbose:
@@ -18,7 +18,8 @@ def load_tests(*args):
                                userfunctions.suite(),
                                factory.suite(), transactions.suite(),
                                hooks.suite(), regression.suite(),
-                               dump.suite()])
+                               dump.suite(),
+                               backup.suite()])
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/Misc/NEWS b/Misc/NEWS
@@ -10,6 +10,9 @@ What's New in Python 3.7.0 alpha 1?
 Core and Builtins
 -----------------
 
+- bpo-27645: sqlite3.Connection now exposes a backup() method.
+  Patch by Lele Gaifax.
+
 - bpo-28598: Support __rmod__ for subclasses of str being called before
   str.__mod__.  Patch by Martijn Pieters.
 

diff --git a/Modules/_sqlite/connection.c b/Modules/_sqlite/connection.c
@@ -1477,6 +1477,92 @@ pysqlite_connection_iterdump(pysqlite_Connection* self, PyObject* args)
     return retval;
 }
 
+static PyObject *
+pysqlite_connection_backup(pysqlite_Connection* self, PyObject* args, PyObject* kwds)
+{
+    char* filename;
+    int pages = -1;
+    PyObject* progress = Py_None;
+    PyObject* retval = NULL;
+    int rc;
+    sqlite3 *bckconn;
+    sqlite3_backup *bckhandle;
+    static char *keywords[] = {"filename", "pages", "progress", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "s|$iO:backup", keywords,
+                                     &filename, &pages, &progress)) {
+        goto finally;
+    }
+
+    if (progress != Py_None && !PyCallable_Check(progress)) {
+        PyErr_SetString(PyExc_TypeError, "progress argument must be a callable");
+        goto finally;
+    }
+
+    if (pages == 0) {
+        pages = -1;
+    }
+
+    Py_BEGIN_ALLOW_THREADS
+    rc = sqlite3_open(filename, &bckconn);
+    Py_END_ALLOW_THREADS
+
+    if (rc != SQLITE_OK) {
+        goto finally;
+    }
+
+    Py_BEGIN_ALLOW_THREADS
+    bckhandle = sqlite3_backup_init(bckconn, "main", self->db, "main");
+    Py_END_ALLOW_THREADS
+
+    if (bckhandle) {
+        do {
+            Py_BEGIN_ALLOW_THREADS
+            rc = sqlite3_backup_step(bckhandle, pages);
+            Py_END_ALLOW_THREADS
+
+            if (progress != Py_None) {
+                if (!PyObject_CallFunction(progress, "ii",
+                                           sqlite3_backup_remaining(bckhandle),
+                                           sqlite3_backup_pagecount(bckhandle))) {
+                    /* User's callback raised an error: interrupt the loop and
+                       propagate it. */
+                    rc = -1;
+                }
+            }
+
+            /* Sleep for 250ms if there are still further pages to copy */
+            if (rc == SQLITE_OK || rc == SQLITE_BUSY || rc == SQLITE_LOCKED) {
+                Py_BEGIN_ALLOW_THREADS
+                sqlite3_sleep(250);
+                Py_END_ALLOW_THREADS
+            }
+        } while (rc == SQLITE_OK || rc == SQLITE_BUSY || rc == SQLITE_LOCKED);
+
+        Py_BEGIN_ALLOW_THREADS
+        sqlite3_backup_finish(bckhandle);
+        Py_END_ALLOW_THREADS
+    }
+
+    if (rc != -1) {
+        rc = _pysqlite_seterror(bckconn, NULL);
+    }
+
+    Py_BEGIN_ALLOW_THREADS
+    sqlite3_close(bckconn);
+    Py_END_ALLOW_THREADS
+
+    if (rc == SQLITE_OK) {
+        Py_INCREF(Py_None);
+        retval = Py_None;
+    } else {
+        /* TODO: should the (probably incomplete/invalid) backup be removed here? */
+    }
+
+finally:
+    return retval;
+}
+
 static PyObject *
 pysqlite_connection_create_collation(pysqlite_Connection* self, PyObject* args)
 {
@@ -1649,6 +1735,8 @@ static PyMethodDef connection_methods[] = {
         PyDoc_STR("Abort any pending database operation. Non-standard.")},
     {"iterdump", (PyCFunction)pysqlite_connection_iterdump, METH_NOARGS,
         PyDoc_STR("Returns iterator to the dump of the database in an SQL text format. Non-standard.")},
+    {"backup", (PyCFunction)pysqlite_connection_backup, METH_VARARGS | METH_KEYWORDS,
+        PyDoc_STR("Makes a backup of the database. Non-standard.")},
     {"__enter__", (PyCFunction)pysqlite_connection_enter, METH_NOARGS,
         PyDoc_STR("For context manager. Non-standard.")},
     {"__exit__", (PyCFunction)pysqlite_connection_exit, METH_VARARGS,