Improvement to samples.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -32,6 +32,7 @@ oracledb 1.0.1 (TBD)
     fetched as floats when oracledb.defaults.fetch_lobs was set to `False`.
 #)  Thin: ensure that errors that occur during fetch are detected consistently.
 #)  Thin: fixed issue when fetching null values in implicit results.
+#)  Improved samples and documentation.
 
 
 oracledb 1.0.0 (May 2022)

samples/app_context.py

@@ -41,18 +41,23 @@
 # this script is currently only supported in python-oracledb thick mode
 oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
 
-# define constants used throughout the script; adjust as desired
+# client context attributes to be set
 APP_CTX_NAMESPACE = "CLIENTCONTEXT"
 APP_CTX_ENTRIES = [
     ( APP_CTX_NAMESPACE, "ATTR1", "VALUE1" ),
     ( APP_CTX_NAMESPACE, "ATTR2", "VALUE2" ),
     ( APP_CTX_NAMESPACE, "ATTR3", "VALUE3" )
 ]
 
-connection = oracledb.connect(sample_env.get_main_connect_string(),
+connection = oracledb.connect(user=sample_env.get_main_user(),
+                              password=sample_env.get_main_password(),
+                              dsn=sample_env.get_connect_string(),
                               appcontext=APP_CTX_ENTRIES)
-cursor = connection.cursor()
-for namespace, name, value in APP_CTX_ENTRIES:
-    cursor.execute("select sys_context(:1, :2) from dual", (namespace, name))
-    value, = cursor.fetchone()
-    print("Value of context key", name, "is", value)
+
+with connection.cursor() as cursor:
+
+    for namespace, name, value in APP_CTX_ENTRIES:
+        cursor.execute("select sys_context(:1, :2) from dual",
+                       (namespace, name))
+        value, = cursor.fetchone()
+        print("Value of context key", name, "is", value)

samples/aq_notification.py

@@ -26,9 +26,8 @@
 # aq_notification.py
 #
 # Demonstrates using advanced queuing notification. Once this script is
-# running, use another session to enqueue a few messages to the
-# "DEMO_BOOK_QUEUE" queue. This is most easily accomplished by running the
-# object_aq.py sample.
+# running, run object_aq.py in another terminal to to enqueue a few messages to
+# the "DEMO_BOOK_QUEUE" queue.
 #------------------------------------------------------------------------------
 
 import time
@@ -51,8 +50,11 @@ def process_messages(message):
     print("Queue name:", message.queue_name)
     print("Consumer name:", message.consumer_name)
 
-connection = oracledb.connect(sample_env.get_main_connect_string(),
+connection = oracledb.connect(user=sample_env.get_main_user(),
+                              password=sample_env.get_main_password(),
+                              dsn=sample_env.get_connect_string(),
                               events=True)
+
 sub = connection.subscribe(namespace=oracledb.SUBSCR_NAMESPACE_AQ,
                            name="DEMO_BOOK_QUEUE", callback=process_messages,
                            timeout=300)

samples/array_dml_rowcounts.py

@@ -38,33 +38,36 @@
 if not sample_env.get_is_thin():
     oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
 
-connection = oracledb.connect(sample_env.get_main_connect_string())
-cursor = connection.cursor()
+connection = oracledb.connect(user=sample_env.get_main_user(),
+                              password=sample_env.get_main_password(),
+                              dsn=sample_env.get_connect_string())
 
-# show the number of rows for each parent ID as a means of verifying the
-# output from the delete statement
-for parent_id, count in cursor.execute("""
-        select ParentId, count(*)
-        from ChildTable
-        group by ParentId
-        order by ParentId"""):
-    print("Parent ID:", parent_id, "has", int(count), "rows.")
-print()
+with connection.cursor() as cursor:
 
-# delete the following parent IDs only
-parent_ids_to_delete = [20, 30, 50]
+    # show the number of rows for each parent ID as a means of verifying the
+    # output from the delete statement
+    for parent_id, count in cursor.execute("""
+            select ParentId, count(*)
+            from ChildTable
+            group by ParentId
+            order by ParentId"""):
+        print("Parent ID:", parent_id, "has", int(count), "rows.")
+    print()
 
-print("Deleting Parent IDs:", parent_ids_to_delete)
-print()
+    # delete the following parent IDs only
+    parent_ids_to_delete = [20, 30, 50]
 
-# enable array DML row counts for each iteration executed in executemany()
-cursor.executemany("""
-        delete from ChildTable
-        where ParentId = :1""",
-        [(i,) for i in parent_ids_to_delete],
-        arraydmlrowcounts = True)
+    print("Deleting Parent IDs:", parent_ids_to_delete)
+    print()
 
-# display the number of rows deleted for each parent ID
-row_counts = cursor.getarraydmlrowcounts()
-for parent_id, count in zip(parent_ids_to_delete, row_counts):
-    print("Parent ID:", parent_id, "deleted", count, "rows.")
+    # enable array DML row counts for each iteration executed in executemany()
+    cursor.executemany("""
+            delete from ChildTable
+            where ParentId = :1""",
+            [(i,) for i in parent_ids_to_delete],
+            arraydmlrowcounts = True)
+
+    # display the number of rows deleted for each parent ID
+    row_counts = cursor.getarraydmlrowcounts()
+    for parent_id, count in zip(parent_ids_to_delete, row_counts):
+        print("Parent ID:", parent_id, "deleted", count, "rows.")

samples/batch_errors.py

@@ -40,69 +40,75 @@
 if not sample_env.get_is_thin():
     oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
 
-connection = oracledb.connect(sample_env.get_main_connect_string())
-cursor = connection.cursor()
+connection = oracledb.connect(user=sample_env.get_main_user(),
+                              password=sample_env.get_main_password(),
+                              dsn=sample_env.get_connect_string())
 
-# define data to insert
-data_to_insert = [
-    (1016, 10, 'Child B of Parent 10'),
-    (1017, 10, 'Child C of Parent 10'),
-    (1018, 20, 'Child D of Parent 20'),
-    (1018, 20, 'Child D of Parent 20'),       # duplicate key
-    (1019, 30, 'Child C of Parent 30'),
-    (1020, 30, 'Child D of Parent 40'),
-    (1021, 60, 'Child A of Parent 60'),       # parent does not exist
-    (1022, 40, 'Child F of Parent 40'),
-]
+with connection.cursor() as cursor:
 
-# retrieve the number of rows in the table
-cursor.execute("""
-        select count(*)
-        from ChildTable""")
-count, = cursor.fetchone()
-print("number of rows in child table:", int(count))
-print("number of rows to insert:", len(data_to_insert))
+    # retrieve the number of rows in the table
+    cursor.execute("""
+            select count(*)
+            from ChildTable""")
+    count, = cursor.fetchone()
+    print("Number of rows in child table:", int(count))
 
-# old method: executemany() with data errors results in stoppage after the
-# first error takes place; the row count is updated to show how many rows
-# actually succeeded
-try:
-    cursor.executemany("insert into ChildTable values (:1, :2, :3)",
-                       data_to_insert)
-except oracledb.DatabaseError as e:
-    error, = e.args
-    print("FAILED with error:", error.message)
-    print("number of rows which succeeded:", cursor.rowcount)
+    # define data to insert
+    data_to_insert = [
+        (1016, 10, 'Child B of Parent 10'),
+        (1017, 10, 'Child C of Parent 10'),
+        (1018, 20, 'Child D of Parent 20'),
+        (1018, 20, 'Child D of Parent 20'),       # duplicate key
+        (1019, 30, 'Child C of Parent 30'),
+        (1020, 30, 'Child D of Parent 40'),
+        (1021, 60, 'Child A of Parent 60'),       # parent does not exist
+        (1022, 40, 'Child F of Parent 40'),
+    ]
+    print("Number of rows to insert:", len(data_to_insert))
+
+    # old method: executemany() with data errors results in stoppage after the
+    # first error takes place; the row count is updated to show how many rows
+    # actually succeeded
+    try:
+        cursor.executemany("insert into ChildTable values (:1, :2, :3)",
+                           data_to_insert)
+    except oracledb.DatabaseError as e:
+        error, = e.args
+        print("Failure with error:", error.message)
+        print("Number of rows successfully inserted:", cursor.rowcount)
 
-# demonstrate that the row count is accurate
-cursor.execute("""
-        select count(*)
-        from ChildTable""")
-count, = cursor.fetchone()
-print("number of rows in child table after failed insert:", int(count))
+    # demonstrate that the row count is accurate
+    cursor.execute("""
+            select count(*)
+            from ChildTable""")
+    count, = cursor.fetchone()
+    print("Number of rows in child table after failed insert:", int(count))
 
-# roll back so we can perform the same work using the new method
-connection.rollback()
+    # roll back so we can perform the same work using the new method
+    connection.rollback()
 
-# new method: executemany() with batch errors enabled (and array DML row counts
-# also enabled) results in no immediate error being raised
-cursor.executemany("insert into ChildTable values (:1, :2, :3)",
-                   data_to_insert, batcherrors=True, arraydmlrowcounts=True)
+    # new method: executemany() with batch errors enabled (and array DML row
+    # counts also enabled) results in no immediate error being raised
+    cursor.executemany("insert into ChildTable values (:1, :2, :3)",
+                       data_to_insert, batcherrors=True,
+                       arraydmlrowcounts=True)
 
-# where errors have taken place, the row count is 0; otherwise it is 1
-row_counts = cursor.getarraydmlrowcounts()
-print("Array DML row counts:", row_counts)
+    # display the errors that have taken place
+    errors = cursor.getbatcherrors()
+    print("Number of rows with bad values:", len(errors))
+    for error in errors:
+        print("Error", error.message.rstrip(), "at row offset", error.offset)
 
-# display the errors that have taken place
-errors = cursor.getbatcherrors()
-print("number of errors which took place:", len(errors))
-for error in errors:
-    print("Error", error.message.rstrip(), "at row offset", error.offset)
+    # arraydmlrowcounts also shows rows with invalid data: they have a row
+    # count of 0; otherwise 1 is shown
+    row_counts = cursor.getarraydmlrowcounts()
+    print("Array DML row counts:", row_counts)
 
-# demonstrate that all of the rows without errors have been successfully
-# inserted
-cursor.execute("""
-        select count(*)
-        from ChildTable""")
-count, = cursor.fetchone()
-print("number of rows in child table after successful insert:", int(count))
+    # demonstrate that all of the rows without errors have been successfully
+    # inserted
+    cursor.execute("""
+            select count(*)
+            from ChildTable""")
+    count, = cursor.fetchone()
+    print("Number of rows in child table after insert with batcherrors "
+          "enabled:", int(count))

samples/bind_insert.py

@@ -25,7 +25,7 @@
 #------------------------------------------------------------------------------
 # bind_insert.py
 #
-# Demonstrates how to insert a row into a table using bind variables.
+# Demonstrates how to insert rows into a table using bind variables.
 #------------------------------------------------------------------------------
 
 import oracledb
@@ -35,7 +35,9 @@
 if not sample_env.get_is_thin():
     oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
 
-connection = oracledb.connect(sample_env.get_main_connect_string())
+connection = oracledb.connect(user=sample_env.get_main_user(),
+                              password=sample_env.get_main_password(),
+                              dsn=sample_env.get_connect_string())
 
 #------------------------------------------------------------------------------
 # "Bind by position"
@@ -51,13 +53,14 @@
     (7, "Seventh")
 ]
 
-cursor = connection.cursor()
+with connection.cursor() as cursor:
 
-# predefine maximum string size to avoid data scans and memory reallocations;
-# the None value indicates that the default processing can take place
-cursor.setinputsizes(None, 20)
+    # predefine the maximum string size to avoid data scans and memory
+    # reallocations.  The value 'None' indicates that the default processing
+    # can take place
+    cursor.setinputsizes(None, 20)
 
-cursor.executemany("insert into mytab(id, data) values (:1, :2)", rows)
+    cursor.executemany("insert into mytab(id, data) values (:1, :2)", rows)
 
 #------------------------------------------------------------------------------
 # "Bind by name"
@@ -66,15 +69,17 @@
 rows = [
     {"d": "Eighth", "i": 8},
     {"d": "Ninth",  "i": 9},
-    {"d": "Tenth",  "i": 10}
+    {"d": "Tenth",  "i": 10},
+    {"i": 11}  # Insert a NULL value
 ]
 
-cursor = connection.cursor()
+with connection.cursor() as cursor:
 
-# Predefine maximum string size to avoid data scans and memory reallocations
-cursor.setinputsizes(d=20)
+    # Predefine maximum string size to avoid data scans and memory
+    # reallocations
+    cursor.setinputsizes(d=20)
 
-cursor.executemany("insert into mytab(id, data) values (:i, :d)", rows)
+    cursor.executemany("insert into mytab(id, data) values (:i, :d)", rows)
 
 #------------------------------------------------------------------------------
 # Inserting a single bind still needs tuples
@@ -85,15 +90,16 @@
     ("Twelth",)
 ]
 
-cursor = connection.cursor()
-cursor.executemany("insert into mytab(id, data) values (11, :1)", rows)
+with connection.cursor() as cursor:
+    cursor.executemany("insert into mytab(id, data) values (12, :1)", rows)
+
+# Don't commit - this lets the demo be run multiple times
+# connection.commit()
 
 #------------------------------------------------------------------------------
 # Now query the results back
 #------------------------------------------------------------------------------
 
-# Don't commit - this lets the demo be run multiple times
-# connection.commit()
-
-for row in cursor.execute('select * from mytab'):
-    print(row)
+with connection.cursor() as cursor:
+    for row in cursor.execute("select * from mytab order by id"):
+        print(row)