Updated the Jupyter notebook samples to cover recently added features.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -37,6 +37,9 @@ Common Changes
 #)  Fixed bug that caused ``ORA-03137: malformed TTC packet from client
     rejected`` exception to be raised when attempting to call
     :meth:`Cursor.parse()` on a scrollable cursor.
+#)  Updated the `Jupyter notebook samples <https://github.com/oracle/
+    python-oracledb/tree/main/samples/notebooks>`__ to cover recent
+    python-oracledb features.
 
 
 oracledb `3.4.0 <https://github.com/oracle/python-oracledb/compare/v3.3.0...v3.4.0>`__ (October 2025)

samples/notebooks/1-Connection.ipynb

@@ -57,9 +57,9 @@
     "Install with a command like one of the following:\n",
     "\n",
     "```\n",
-    "$ python3 -m pip install oracledb --upgrade\n",
-    "$ python3 -m pip install oracledb --upgrade --user\n",
-    "$ python3 -m pip install oracledb --upgrade --user --proxy=http://proxy.example.com:80\n",
+    "$ python -m pip install oracledb --upgrade\n",
+    "$ python -m pip install oracledb --upgrade --user\n",
+    "$ python -m pip install oracledb --upgrade --user --proxy=http://proxy.example.com:80\n",
     "```"
    ]
   },
@@ -105,7 +105,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Instead of hard coding the password, you could prompt for a value, pass it as an environment variable, or use Oracle \"external authentication\"."
+    "Instead of hard coding the password in your applications, you could prompt for a value, pass it as an environment variable, or use Oracle \"external authentication\"."
    ]
   },
   {
@@ -133,13 +133,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Oracle Client 19c improved [Easy Connect Plus](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-8C85D289-6AF3-41BC-848B-BF39D32648BA) syntax with additional optional settings, for example:\n",
+    "Oracle's [Easy Connect](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-8C85D289-6AF3-41BC-848B-BF39D32648BA) syntax allows many optional settings, for example:\n",
     "\n",
     "```\n",
     "cs = \"tcps://my.cloud.com:1522/orclpdb1?connect_timeout=4&expire_time=10\"\n",
     "```\n",
     "\n",
-    "<!-- See the [technical brief](https://download.oracle.com/ocomdocs/global/Oracle-Net-19c-Easy-Connect-Plus.pdf). -->"
+    "See the Oracle Database Easy Connect [technical brief](https://download.oracle.com/ocomdocs/global/Oracle-Net-Easy-Connect-Plus.pdf) for other options."
    ]
   },
   {
@@ -148,7 +148,7 @@
    "source": [
     "### Oracle Network and Oracle Client Configuration Files\n",
     "\n",
-    "Oracle Database's `tnsnames.ora` file can be used.  This file maps a connect descriptor to an alias.  \n",
+    "Instead of the Easy Connect syntax, a TNS Alias from a `tnsnames.ora` file can be used.  This file maps connect descriptors to TNS aliases. \n",
     "\n",
     "Documentation reference link: [Optional configuration files](https://python-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#optional-oracle-net-configuration-files)"
    ]
@@ -159,7 +159,7 @@
    "source": [
     "\n",
     "# tnsnames.ora in /opt/oracle/configdir\n",
-    "    \n",
+    "\n",
     "highperfdb = (description= \n",
     "               (retry_count=5)(retry_delay=3)\n",
     "               (address=(protocol=tcps)(port=1522)(host=xxxxxx.oraclecloud.com))\n",
@@ -173,7 +173,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Your Python code could use the alias as the connection `dsn` value:\n",
+    "Your Python code could use the TNS Alias as the connection `dsn` value:\n",
     "```\n",
     "connection = oracledb.connect(user=un, password=pw, dsn=\"highperfdb\", config_dir=\"/opt/oracle/configdir\")\n",
     "```"
@@ -192,7 +192,7 @@
    "source": [
     "### Standalone Connections\n",
     "\n",
-    "Standalone connections are simple to create."
+    "Standalone connections are simple to create. They are suitable for single-user applications that do not run very long."
    ]
   },
   {
@@ -208,7 +208,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Stand-alone Connections\n",
+    "# Stand-alone Connection\n",
     "\n",
     "connection = oracledb.connect(user=un, password=pw, dsn=cs)\n",
     "\n",
@@ -227,10 +227,12 @@
    "metadata": {},
    "source": [
     "#### Pools are highly recommended if you have:\n",
-    "- a lot of connections that will be used for short periods of time\n",
-    "- or a small number of connections that are idle for long periods of time\n",
+    "- A lot of connections that will be used for short periods of time\n",
+    "- Or a small number of connections that are idle for long periods of time\n",
     "\n",
     "#### Pool advantages\n",
+    "Try to architect your applications to use connection pools to take advantage of:\n",
+    "\n",
     "- Reduced cost of setting up and tearing down connections\n",
     "- Dead connection detection and automatic re-establishment"
    ]
@@ -278,17 +280,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Close connections when not needed.  This is important for pooled connections.\n",
+    "Close connections when not needed.  This is important for pooled connections. With a connection pool, closing the connection releases it back to the pool for later reuse.\n",
+    "\n",
+    "To avoid resource closing order issues, you should use `with` or let resources be closed at end of scope:\n",
     "\n",
     "```\n",
-    "connection.close()\n",
+    "with pool.acquire() as connection:\n",
+    "    do_something(connection)\n",
     "```\n",
     "\n",
-    "To avoid resource closing order issues, you may want to use `with` or let resources be closed at end of scope:\n",
+    "Or you can explicitly close connections:\n",
     "\n",
     "```\n",
-    "with pool.acquire() as connection:\n",
-    "    do_something(connection)\n",
+    "connection.close()\n",
     "```"
    ]
   },
@@ -333,8 +337,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Memory example with 5000 application users and a DRCP pool of size 100\n",
-    "![DRCP memory comparison](images/drcp-comparison.png)"
+    "#### Database memory usage example with 5000 application users and a DRCP pool of size 100\n",
+    "![DRCP memory comparison](images/drcp-comparison.png)\n",
+    "The numbers are examples."
    ]
   },
   {
@@ -375,7 +380,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.9.24"
   }
  },
  "nbformat": 4,

samples/notebooks/2-Queries.ipynb

@@ -15,12 +15,10 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "import oracledb"
+    "Setup for this notebook:"
    ]
   },
   {
@@ -29,6 +27,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import oracledb\n",
+    "\n",
     "un       = \"pythondemo\"\n",
     "pw       = \"welcome\"\n",
     "\n",
@@ -104,7 +104,25 @@
     "        for r in rows:\n",
     "            print(r)\n",
     "        if len(rows) < cursor.arraysize:\n",
-    "            break\n"
+    "            break"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A common idiom to use an iterator and process each row individually.  Internally python-oracledb will fetch from the database in batches controlled by tuning parameters shown in the next section:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with connection.cursor() as cursor:\n",
+    "    for row in cursor.execute(\"select * from SampleQueryTab\"):\n",
+    "        print(row)"
    ]
   },
   {
@@ -519,7 +537,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.9.24"
   }
  },
  "nbformat": 4,