5 files changed, 439 insertions, 0 deletions
diff --git a/sources/pyside2/doc/tutorials/portingguide/chapter1/chapter1.rst b/sources/pyside2/doc/tutorials/portingguide/chapter1/chapter1.rst
new file mode 100644
index 000000000..20b11065a
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/portingguide/chapter1/chapter1.rst
@@ -0,0 +1,89 @@
+Chapter 1: ``initDb.h`` to ``createDb.py``
+*******************************************
+
+To begin with, port the C++ code that creates an SQLite
+database and tables, and adds data to them. In this case,
+all C++ code related to this lives in ``initdb.h``. The
+code in this header file is divided into following parts:
+
+* ``initDb`` - Creates a db and the necessary tables
+* ``addBooks`` - Adds data to the **books** table.
+* ``addAuthor`` - Adds data to the **authors** table.
+* ``addGenre`` - Adds data to the **genres** table.
+
+To start with, add these following ``import`` statements at
+the beginning of ``createdb.py``:
+
+.. literalinclude:: createdb.py
+   :language: python
+   :linenos:
+   :lines: 40-44
+
+The ``initDb`` function does most of the work needed to
+set up the database, but it depends on the ``addAuthor``,
+``addGenre``, and ``addBook`` helper functions to populate
+the tables. Port these helper functions first. Here is how
+the C++ and Python versions of these functions look like:
+
+C++ version
+------------
+
+.. literalinclude:: initdb.h
+   :language: c++
+   :linenos:
+   :lines: 55-81
+
+Python version
+---------------
+
+.. literalinclude:: createdb.py
+   :language: python
+   :linenos:
+   :lines: 44-65
+
+Now that the helper functions are in place, port ``initDb``.
+Here is how the C++ and Python versions of this function
+looks like:
+
+C++ version
+------------
+
+.. literalinclude:: initdb.h
+   :language: c++
+   :linenos:
+   :lines: 81-159
+
+Python version
+---------------
+
+.. literalinclude:: createdb.py
+   :language: python
+   :linenos:
+   :lines: 65-
+
+.. note:: The Python version uses the ``check`` function to
+   execute the SQL statements instead of the ``if...else``
+   block like in the C++ version. Although both are valid
+   approaches, the earlier one produces code that looks
+   cleaner and shorter.
+
+Your Python code to set up the database is ready now. To
+test it, add the following code to ``main.py`` and run it:
+
+.. literalinclude:: main.py
+   :language: python
+   :linenos:
+   :lines: 40-
+
+Use the following command from the prompt to run:
+
+.. code-block::
+
+    python main.py
+
+Your table will look like this:
+
+.. image:: images/chapter1_books.png
+
+Try modifying the SQL statment in ``main.py`` to get data
+from the ``genres`` or ``authors`` table.
diff --git a/sources/pyside2/doc/tutorials/portingguide/chapter1/createdb.py b/sources/pyside2/doc/tutorials/portingguide/chapter1/createdb.py
new file mode 100644
index 000000000..8fb20cda1
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/portingguide/chapter1/createdb.py
@@ -0,0 +1,131 @@
+#############################################################################
+##
+## Copyright (C) 2019 The Qt Company Ltd.
+## Contact: http://www.qt.io/licensing/
+##
+## This file is part of the Qt for Python examples of the Qt Toolkit.
+##
+## $QT_BEGIN_LICENSE:BSD$
+## You may use this file under the terms of the BSD license as follows:
+##
+## "Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions are
+## met:
+##   * Redistributions of source code must retain the above copyright
+##     notice, this list of conditions and the following disclaimer.
+##   * Redistributions in binary form must reproduce the above copyright
+##     notice, this list of conditions and the following disclaimer in
+##     the documentation and/or other materials provided with the
+##     distribution.
+##   * Neither the name of The Qt Company Ltd nor the names of its
+##     contributors may be used to endorse or promote products derived
+##     from this software without specific prior written permission.
+##
+##
+## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+## "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+## LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+## A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+## OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+## DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+## THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+## (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+## OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+##
+## $QT_END_LICENSE$
+##
+#############################################################################
+
+from PySide2.QtSql import QSqlDatabase, QSqlError, QSqlQuery
+from datetime import date
+
+
+def add_book(q, title, year, authorId, genreId, rating):
+    q.addBindValue(title)
+    q.addBindValue(year)
+    q.addBindValue(authorId)
+    q.addBindValue(genreId)
+    q.addBindValue(rating)
+    q.exec_()
+
+
+def add_genre(q, name):
+    q.addBindValue(name)
+    q.exec_()
+    return q.lastInsertId()
+
+
+def add_author(q, name, birthdate):
+    q.addBindValue(name)
+    q.addBindValue(str(birthdate))
+    q.exec_()
+    return q.lastInsertId()
+
+BOOKS_SQL = """
+    create table books(id integer primary key, title varchar, author integer,
+                       genre integer, year integer, rating integer)
+    """
+AUTHORS_SQL = """
+    create table authors(id integer primary key, name varchar, birthdate text)
+    """
+GENRES_SQL = """
+    create table genres(id integer primary key, name varchar)
+    """
+INSERT_AUTHOR_SQL = """
+    insert into authors(name, birthdate) values(?, ?)
+    """
+INSERT_GENRE_SQL = """
+    insert into genres(name) values(?)
+    """
+INSERT_BOOK_SQL = """
+    insert into books(title, year, author, genre, rating)
+                values(?, ?, ?, ?, ?)
+    """
+
+def init_db():
+    """
+    init_db()
+    Initializes the database.
+    If tables "books" and "authors" are already in the database, do nothing.
+    Return value: None or raises ValueError
+    The error value is the QtSql error instance.
+    """
+    def check(func, *args):
+        if not func(*args):
+            raise ValueError(func.__self__.lastError())
+    db = QSqlDatabase.addDatabase("QSQLITE")
+    db.setDatabaseName(":memory:")
+
+    check(db.open)
+
+    q = QSqlQuery()
+    check(q.exec_, BOOKS_SQL)
+    check(q.exec_, AUTHORS_SQL)
+    check(q.exec_, GENRES_SQL)
+    check(q.prepare, INSERT_AUTHOR_SQL)
+
+    asimovId = add_author(q, "Isaac Asimov", date(1920, 2, 1))
+    greeneId = add_author(q, "Graham Greene", date(1904, 10, 2))
+    pratchettId = add_author(q, "Terry Pratchett", date(1948, 4, 28))
+
+    check(q.prepare,INSERT_GENRE_SQL)
+    sfiction = add_genre(q, "Science Fiction")
+    fiction = add_genre(q, "Fiction")
+    fantasy = add_genre(q, "Fantasy")
+
+    check(q.prepare,INSERT_BOOK_SQL)
+    add_book(q, "Foundation", 1951, asimovId, sfiction, 3)
+    add_book(q, "Foundation and Empire", 1952, asimovId, sfiction, 4)
+    add_book(q, "Second Foundation", 1953, asimovId, sfiction, 3)
+    add_book(q, "Foundation's Edge", 1982, asimovId, sfiction, 3)
+    add_book(q, "Foundation and Earth", 1986, asimovId, sfiction, 4)
+    add_book(q, "Prelude to Foundation", 1988, asimovId, sfiction, 3)
+    add_book(q, "Forward the Foundation", 1993, asimovId, sfiction, 3)
+    add_book(q, "The Power and the Glory", 1940, greeneId, fiction, 4)
+    add_book(q, "The Third Man", 1950, greeneId, fiction, 5)
+    add_book(q, "Our Man in Havana", 1958, greeneId, fiction, 4)
+    add_book(q, "Guards! Guards!", 1989, pratchettId, fantasy, 3)
+    add_book(q, "Night Watch", 2002, pratchettId, fantasy, 3)
+    add_book(q, "Going Postal", 2004, pratchettId, fantasy, 3)
diff --git a/sources/pyside2/doc/tutorials/portingguide/chapter1/images/chapter1_books.png b/sources/pyside2/doc/tutorials/portingguide/chapter1/images/chapter1_books.png
new file mode 100644
index 000000000..164674220
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/portingguide/chapter1/images/chapter1_books.png
diff --git a/sources/pyside2/doc/tutorials/portingguide/chapter1/initdb.h b/sources/pyside2/doc/tutorials/portingguide/chapter1/initdb.h
new file mode 100644
index 000000000..773e3fb74
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/portingguide/chapter1/initdb.h
@@ -0,0 +1,160 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the demonstration applications of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef INITDB_H
+#define INITDB_H
+
+#include <QtSql>
+
+void addBook(QSqlQuery &q, const QString &title, int year, const QVariant &authorId,
+             const QVariant &genreId, int rating)
+{
+    q.addBindValue(title);
+    q.addBindValue(year);
+    q.addBindValue(authorId);
+    q.addBindValue(genreId);
+    q.addBindValue(rating);
+    q.exec();
+}
+
+QVariant addGenre(QSqlQuery &q, const QString &name)
+{
+    q.addBindValue(name);
+    q.exec();
+    return q.lastInsertId();
+}
+
+QVariant addAuthor(QSqlQuery &q, const QString &name, const QDate &birthdate)
+{
+    q.addBindValue(name);
+    q.addBindValue(birthdate);
+    q.exec();
+    return q.lastInsertId();
+}
+
+const auto BOOKS_SQL = QLatin1String(R"(
+    create table books(id integer primary key, title varchar, author integer,
+                       genre integer, year integer, rating integer)
+    )");
+
+const auto AUTHORS_SQL =  QLatin1String(R"(
+    create table authors(id integer primary key, name varchar, birthdate date)
+    )");
+
+const auto GENRES_SQL = QLatin1String(R"(
+    create table genres(id integer primary key, name varchar)
+    )");
+
+const auto INSERT_AUTHOR_SQL = QLatin1String(R"(
+    insert into authors(name, birthdate) values(?, ?)
+    )");
+
+const auto INSERT_BOOK_SQL = QLatin1String(R"(
+    insert into books(title, year, author, genre, rating)
+                      values(?, ?, ?, ?, ?)
+    )");
+
+const auto INSERT_GENRE_SQL = QLatin1String(R"(
+    insert into genres(name) values(?)
+    )");
+
+QSqlError initDb()
+{
+    QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE");
+    db.setDatabaseName(":memory:");
+
+    if (!db.open())
+        return db.lastError();
+
+    QStringList tables = db.tables();
+    if (tables.contains("books", Qt::CaseInsensitive)
+        && tables.contains("authors", Qt::CaseInsensitive))
+        return QSqlError();
+
+    QSqlQuery q;
+    if (!q.exec(BOOKS_SQL))
+        return q.lastError();
+    if (!q.exec(AUTHORS_SQL))
+        return q.lastError();
+    if (!q.exec(GENRES_SQL))
+        return q.lastError();
+
+    if (!q.prepare(INSERT_AUTHOR_SQL))
+        return q.lastError();
+    QVariant asimovId = addAuthor(q, QLatin1String("Isaac Asimov"), QDate(1920, 2, 1));
+    QVariant greeneId = addAuthor(q, QLatin1String("Graham Greene"), QDate(1904, 10, 2));
+    QVariant pratchettId = addAuthor(q, QLatin1String("Terry Pratchett"), QDate(1948, 4, 28));
+
+    if (!q.prepare(INSERT_GENRE_SQL))
+        return q.lastError();
+    QVariant sfiction = addGenre(q, QLatin1String("Science Fiction"));
+    QVariant fiction = addGenre(q, QLatin1String("Fiction"));
+    QVariant fantasy = addGenre(q, QLatin1String("Fantasy"));
+
+    if (!q.prepare(INSERT_BOOK_SQL))
+        return q.lastError();
+    addBook(q, QLatin1String("Foundation"), 1951, asimovId, sfiction, 3);
+    addBook(q, QLatin1String("Foundation and Empire"), 1952, asimovId, sfiction, 4);
+    addBook(q, QLatin1String("Second Foundation"), 1953, asimovId, sfiction, 3);
+    addBook(q, QLatin1String("Foundation's Edge"), 1982, asimovId, sfiction, 3);
+    addBook(q, QLatin1String("Foundation and Earth"), 1986, asimovId, sfiction, 4);
+    addBook(q, QLatin1String("Prelude to Foundation"), 1988, asimovId, sfiction, 3);
+    addBook(q, QLatin1String("Forward the Foundation"), 1993, asimovId, sfiction, 3);
+    addBook(q, QLatin1String("The Power and the Glory"), 1940, greeneId, fiction, 4);
+    addBook(q, QLatin1String("The Third Man"), 1950, greeneId, fiction, 5);
+    addBook(q, QLatin1String("Our Man in Havana"), 1958, greeneId, fiction, 4);
+    addBook(q, QLatin1String("Guards! Guards!"), 1989, pratchettId, fantasy, 3);
+    addBook(q, QLatin1String("Night Watch"), 2002, pratchettId, fantasy, 3);
+    addBook(q, QLatin1String("Going Postal"), 2004, pratchettId, fantasy, 3);
+
+    return QSqlError();
+}
+
+#endif
diff --git a/sources/pyside2/doc/tutorials/portingguide/chapter1/main.py b/sources/pyside2/doc/tutorials/portingguide/chapter1/main.py
new file mode 100644
index 000000000..7e94e4c14
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/portingguide/chapter1/main.py
@@ -0,0 +1,59 @@
+#############################################################################
+##
+## Copyright (C) 2019 The Qt Company Ltd.
+## Contact: http://www.qt.io/licensing/
+##
+## This file is part of the Qt for Python examples of the Qt Toolkit.
+##
+## $QT_BEGIN_LICENSE:BSD$
+## You may use this file under the terms of the BSD license as follows:
+##
+## "Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions are
+## met:
+##   * Redistributions of source code must retain the above copyright
+##     notice, this list of conditions and the following disclaimer.
+##   * Redistributions in binary form must reproduce the above copyright
+##     notice, this list of conditions and the following disclaimer in
+##     the documentation and/or other materials provided with the
+##     distribution.
+##   * Neither the name of The Qt Company Ltd nor the names of its
+##     contributors may be used to endorse or promote products derived
+##     from this software without specific prior written permission.
+##
+##
+## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+## "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+## LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+## A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+## OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+## DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+## THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+## (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+## OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+##
+## $QT_END_LICENSE$
+##
+#############################################################################
+
+import sys
+
+from PySide2.QtSql import QSqlQueryModel
+from PySide2.QtWidgets import QTableView, QApplication
+
+import createdb
+
+if __name__ == "__main__":
+    app = QApplication()
+    createdb.init_db()
+
+    model = QSqlQueryModel()
+    model.setQuery("select * from books")
+
+    table_view = QTableView()
+    table_view.setModel(model)
+    table_view.resize(800, 600)
+    table_view.show()
+    sys.exit(app.exec_())