Documentation

Added testsetup for sphinx' doctest

Author: 9EOR9

doc/source/usage.rst

@@ -12,7 +12,7 @@ implement |DBAPI|.
 
 Below is a simple example of a typical use of MariaDB Connector/Python
 
-.. testcode::
+.. testsetup::
 
     import mariadb
 
@@ -28,18 +28,42 @@ Below is a simple example of a typical use of MariaDB Connector/Python
     connection= mariadb.connect(**conn_params)
 
     cursor= connection.cursor()
+    cursor.execute("CREATE OR REPLACE TABLE `countries` ("
+                   "`id` int(10) unsigned NOT NULL AUTO_INCREMENT,"
+                   "`name` varchar(50) NOT NULL,"
+                   "`country_code` char(3) NOT NULL,"
+                   "`capital` varchar(50) DEFAULT NULL,"
+                   "PRIMARY KEY (`id`),"
+                   "KEY `name` (`name`),"
+                   "KEY `capital` (`capital`)"
+                   ") ENGINE=InnoDB DEFAULT CHARSET=latin1")
+
+    cursor.close()
+    connection.close()
+
+.. testcode::
+
+    import mariadb
+
+    # connection parameters
+    conn_params= {
+        "user" : "example_user",
+        "password" : "GHbe_Su3B8",
+        "host" : "localhost",
+        "database" : "test"
+    }
+
+    # Establish a connection
+    connection= mariadb.connect(**conn_params)
 
-    # Create a database table
-    cursor.execute("DROP TABLE IF EXISTS mytest")
-    cursor.execute("CREATE TABLE mytest(id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,"
-                   "first_name VARCHAR(100), last_name VARCHAR(100))")
+    cursor= connection.cursor()
 
-    # Populate table with some data
-    cursor.execute("INSERT INTO mytest(first_name, last_name) VALUES (?,?)",
-                   ("Robert", "Redford"))
+    # Populate countries table  with some data
+    cursor.execute("INSERT INTO countries(name, country_code, capital) VALUES (?,?,?)",
+                   ("Germany", "GER", "Berlin"))
 
     # retrieve data
-    cursor.execute("SELECT id, first_name, last_name FROM mytest")
+    cursor.execute("SELECT name, country_code, capital FROM countries")
 
     # print content
     row= cursor.fetchone()
@@ -53,7 +77,7 @@ Below is a simple example of a typical use of MariaDB Connector/Python
 
 .. testoutput::
 
-    1 Robert Redford
+    Germany GER Berlin
 
 
 Before MariaDB Connector/Python can be used, the MariaDB Connector/Python module must be 
@@ -100,41 +124,23 @@ Since |MCP| uses binary protocol, escaping strings or binary data like in other
 
     cursor= connection.cursor()
 
-    cursor.execute("DROP TABLE IF EXISTS books")
-    cursor.execute("CREATE TABLE books(id int not null auto_increment primary key,\
-                    book_name VARCHAR(100), author_name VARCHAR(50), price DECIMAL(10,2))")
-
-    
-    # insert multiple
-    books= [("Dream of the Red Chamber", "Cao Xueqin", 13.90),  
-            ("The Little Prince", "Antoine de Saint-Exupéry", 9.40)]
-    sql= "INSERT INTO books (book_name, author_name, price) VALUES (?, ?, ?)"
-    cursor.executemany(sql, books);
+    sql= "INSERT INTO countries (name, country_code, capital) VALUES (?,?,?)"
+    data= ("Germany", "GER", "Berlin")
+    cursor.execute(sql, data)
 
-    # Since autocommit is off by default, we need to commit last transaction
     connection.commit()
 
-    sql= "INSERT INTO books (book_name, author_name, price) VALUES (?, ?, ?)"
-    data= ("The Lord of the Rings", "J.R.R. Tolkien", 18.99)
+    # delete last entry
+    sql= "DELETE FROM countries WHERE country_code=?"
+    data= ("GER",)
     cursor.execute(sql, data)
 
-    # update
-    sql= "UPDATE books SET price=? WHERE book_name=?"
-    data= (14.90, "Dream of the Red Chamber")
-    cursor.execute(sql, data)
-  
-    # delete
-    sql= "DELETE FROM books WHERE id=?"
-    data= (2,)   # Don't forget a comma at the end!
-    cursor.execute(sql, data)
-
-    # by default autocommit is off, so we need to commit
-    # our transactions
     connection.commit()
 
-    # free resources
     cursor.close()
     connection.close()
+
+
 
 
 Often there is a requirement to update, delete or insert multiple records. This could be done be using :func:`~execute` in
@@ -156,27 +162,45 @@ a loop, but much more effective is using the :func:`executemany` method, especia
     connection= mariadb.connect(**conn_params)
 
     cursor= connection.cursor()
-
-    # update
-    sql= "UPDATE books SET price=? WHERE book_name=?"
-    data= [(14.90, "Dream of the Red Chamber"),
-           (22.30, "The Master and Margarita"),
-           (17.10, "And Then There Were None")]
+    sql= "INSERT INTO countries (name, country_code, capital) VALUES (?,?,?)"
+
+    data= [("Ireland", "IE", "Dublin"),
+           ("Italy", "IT", "Rome"),
+           ("Malaysia", "MY", "Kuala Lumpur"),
+           ("France", "FR", "Paris"),
+           ("Iceland", "IS", "Reykjavik"),
+           ("Nepal", "NP", "Kathmandu")]
+    
+    # insert data
     cursor.executemany(sql, data)
- 
-    # delete
-    sql= "DELETE FROM books WHERE id=?"
-    data= [(4034,),(12001,),(230,)]
+
+    # Since autocommit is off by default, we need to commit last transaction
+    connection.commit()
+
+    # Instead of 3 letter country-code, we inserted 2 letter country code, so
+    # let's fix this mistake by updating data
+    sql= "UPDATE countries SET country_code=? WHERE name=?"
+    data= [("Ireland", "IRL"),
+           ("Italy", "ITA"),
+           ("Malaysia", "MYS"),
+           ("France", "FRA"),
+           ("Iceland", "ISL"),
+           ("Nepal", "NPL")]
     cursor.executemany(sql, data)
- 
-    #insert
-    sql= "INSERT INTO books (book_name, author_name, price) VALUES (?, ?, ?)"
-    data= [("The Lord of the Rings", "J.R.R. Tolkien", 18.99),
-           ("Le Petit Prince", "Antoine de Saint-Exupéry", 22.40),
-           ("Dream of the Red Chamber", "Cao Xueqin", 16.90),
-           ("The Adventures of Pinocchio", "Carlo Collodi", 17.10)]
+  
+    # Now let's delete all non European countries
+    sql= "DELETE FROM countries WHERE name=?"
+    data= [("Malaysia",), ("Nepal",)]
     cursor.executemany(sql, data)
 
+    # by default autocommit is off, so we need to commit
+    # our transactions
+    connection.commit()
+
+    # free resources
+    cursor.close()
+    connection.close()
+
 When using executemany(), there are a few restrictions:
 - All tuples must have the same types as in first tuple. E.g. the parameter [(1),(1.0)] or [(1),(None)] are invalid.
 - Special values like None or column default value needs to be indicated by an indicator.