Added parameter "data" to connection.createlob() to allow data to be

written at LOB creation time.

Author: anthony-tuininga

doc/src/api_manual/connection.rst

@@ -91,13 +91,20 @@ Connection Methods
 
     Commits any pending transactions to the database.
 
-.. method:: Connection.createlob(lob_type)
+.. method:: Connection.createlob(lob_type, data=None)
 
     Creates and returns a new temporary :ref:`LOB object <lobobj>` of the
     specified type. The ``lob_type`` parameter should be one of
     :data:`oracledb.DB_TYPE_CLOB`, :data:`oracledb.DB_TYPE_BLOB`, or
     :data:`oracledb.DB_TYPE_NCLOB`.
 
+    If data is supplied, it will be written to the temporary LOB before it is
+    returned.
+
+    .. versionchanged:: 2.0
+
+        The parameter ``data`` was added.
+
     .. note::
 
         This method is an extension to the DB API definition.

doc/src/api_manual/deprecations.rst

@@ -11,7 +11,7 @@ if applicable. The most recent deprecations are listed first.
 .. list-table-with-summary:: Desupported in python-oracledb 2.0
     :header-rows: 1
     :class: wy-table-responsive
-    :summary: The first column, Name, displays the desupported API name. The second column, Comments, includes information about when the API  desupported and what API to use, if applicable.
+    :summary: The first column, Name, displays the desupported feature. The second column, Comments, includes information about the desupport and what replacement to make, if applicable.
     :name: _desupported_2_0
 
     * - Name
@@ -49,10 +49,29 @@ if applicable. The most recent deprecations are listed first.
     * - ``SessionPool.tnsentry``
       - Replace with :attr:`ConnectionPool.dsn`
 
+.. list-table-with-summary:: Deprecated in python-oracledb 2.0
+    :header-rows: 1
+    :class: wy-table-responsive
+    :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecatation and what replacement to use, if applicable.
+    :name: _deprecations_2_0
+
+    * - Name
+      - Comments
+    * - Calling :meth:`Variable.setvalue()` with a string value when the
+        variable type is one of :data:`oracledb.DB_TYPE_BLOB`,
+        :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB`.
+      - Call :meth:`Connection.createlob()` with the value instead and pass the
+        result to :meth:`Variable.setvalue()`.
+    * - Setting an attribute of type :data:`oracledb.DB_TYPE_BLOB`,
+        :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB` on a
+        database object to a string value.
+      - Call :meth:`Connection.createlob()` with the value instead and set the
+        attribute with the result.
+
 .. list-table-with-summary:: Deprecated in python-oracledb 1.4
     :header-rows: 1
     :class: wy-table-responsive
-    :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable.
+    :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecatation and what replacement to use, if applicable.
     :name: _deprecations_1_4
 
     * - Name
@@ -163,9 +182,7 @@ python-oracledb are listed below:
 .. list-table-with-summary:: Deprecated in cx_Oracle 8.2
     :header-rows: 1
     :class: wy-table-responsive
-    :summary: The first column, Name, displays the deprecated API name. The second column,
-     Comments, includes information about when the API was deprecated and what API to use,
-     if applicable.
+    :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecatation and what replacement to use, if applicable.
     :name: _deprecations_8_2
 
     * - Name
@@ -261,7 +278,7 @@ python-oracledb are listed below:
 .. list-table-with-summary:: Deprecated in cx_Oracle 8.0
     :header-rows: 1
     :class: wy-table-responsive
-    :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable.
+    :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecatation and what replacement to use, if applicable.
     :name: _deprecations_8_0
 
     * - Name
@@ -303,7 +320,7 @@ python-oracledb are listed below:
 .. list-table-with-summary:: Deprecated in cx_Oracle 7.2
     :header-rows: 1
     :class: wy-table-responsive
-    :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable.
+    :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecatation and what replacement to use, if applicable.
     :name: _deprecations_7_2
 
     * - Name
@@ -321,7 +338,7 @@ python-oracledb are listed below:
 .. list-table-with-summary:: Deprecated in cx_Oracle 6.4
     :header-rows: 1
     :class: wy-table-responsive
-    :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable.
+    :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecatation and what replacement to use, if applicable.
     :name: _deprecations_6_4
 
     * - Name

doc/src/release_notes.rst

@@ -74,6 +74,8 @@ Common Changes
     associated with columns that are being fetched. SQL domains and annotations
     require Oracle Database 23c. If using python-oracledb Thick mode, Oracle
     Client 23c is also required.
+#)  Added parameter ``data`` to :meth:`Connection.createlob()` to allow data to
+    be written at LOB creation time.
 #)  Added type :data:`~oracledb.DB_TYPE_XMLTYPE` to represent data of type
     ``SYS.XMLTYPE`` in the database. Previously the value of
     :data:`FetchInfo.type_code` for data of this type was

src/oracledb/connection.py

@@ -619,7 +619,9 @@ def commit(self) -> None:
         self._verify_connected()
         self._impl.commit()
 
-    def createlob(self, lob_type: DbType) -> LOB:
+    def createlob(
+        self, lob_type: DbType, data: Union[str, bytes] = None
+    ) -> LOB:
         """
         Create and return a new temporary LOB of the specified type.
         """
@@ -631,6 +633,8 @@ def createlob(self, lob_type: DbType) -> LOB:
             )
             raise TypeError(message)
         impl = self._impl.create_temp_lob_impl(lob_type)
+        if data:
+            impl.write(data, 1)
         return LOB._from_impl(impl)
 
     def cursor(self, scrollable: bool = False) -> Cursor:
@@ -1518,7 +1522,9 @@ async def commit(self) -> None:
         self._verify_connected()
         await self._impl.commit()
 
-    async def createlob(self, lob_type: DbType) -> LOB:
+    async def createlob(
+        self, lob_type: DbType, data: Union[str, bytes] = None
+    ) -> AsyncLOB:
         """
         Create and return a new temporary LOB of the specified type.
         """
@@ -1530,6 +1536,8 @@ async def createlob(self, lob_type: DbType) -> LOB:
             )
             raise TypeError(message)
         impl = await self._impl.create_temp_lob_impl(lob_type)
+        if data:
+            await impl.write(data, 1)
         return AsyncLOB._from_impl(impl)
 
     def cursor(self, scrollable: bool = False) -> AsyncCursor:

tests/test_1900_lob_var.py

@@ -211,8 +211,7 @@ def __test_pickle(self, lob_type):
         if lob_type == "BLOB":
             value = value.encode("ascii")
         db_type = getattr(oracledb, "DB_TYPE_" + lob_type)
-        lob = self.conn.createlob(db_type)
-        lob.write(value)
+        lob = self.conn.createlob(db_type, value)
         pickled_data = pickle.dumps(lob)
         unpickled_value = pickle.loads(pickled_data)
         self.assertEqual(unpickled_value, value)
@@ -224,8 +223,7 @@ def __test_temporary_lob(self, lob_type):
         if lob_type == "BLOB":
             value = value.encode("ascii")
         db_type = getattr(oracledb, f"DB_TYPE_{lob_type}")
-        lob = self.conn.createlob(db_type)
-        lob.write(value)
+        lob = self.conn.createlob(db_type, value)
         self.cursor.execute(
             f"""
             insert into Test{lob_type}s (IntCol, {lob_type}Col)
@@ -435,8 +433,7 @@ def test_1920_supplemental_characters(self):
             "𢵌 𢵧 𢺳 𣲷 𤓓 𤶸 𤷪 𥄫 𦉘 𦟌 𦧲 𦧺 𧨾 𨅝 𨈇 𨋢 𨳊 𨳍 𨳒 𩶘"
         )
         self.cursor.execute("delete from TestCLOBs")
-        lob = self.conn.createlob(oracledb.DB_TYPE_CLOB)
-        lob.write(supplemental_chars)
+        lob = self.conn.createlob(oracledb.DB_TYPE_CLOB, supplemental_chars)
         self.cursor.execute(
             """
             insert into TestCLOBs

tests/test_5700_lob_var_async.py

@@ -203,8 +203,7 @@ async def __test_temporary_lob(self, lob_type):
         if lob_type == "BLOB":
             value = value.encode("ascii")
         db_type = getattr(oracledb, f"DB_TYPE_{lob_type}")
-        lob = await self.conn.createlob(db_type)
-        await lob.write(value)
+        lob = await self.conn.createlob(db_type, value)
         await self.cursor.execute(
             f"""
             insert into Test{lob_type}s (IntCol, {lob_type}Col)
@@ -399,8 +398,9 @@ async def test_5716_supplemental_characters(self):
             "𢵌 𢵧 𢺳 𣲷 𤓓 𤶸 𤷪 𥄫 𦉘 𦟌 𦧲 𦧺 𧨾 𨅝 𨈇 𨋢 𨳊 𨳍 𨳒 𩶘"
         )
         await self.cursor.execute("delete from TestCLOBs")
-        lob = await self.conn.createlob(oracledb.DB_TYPE_CLOB)
-        await lob.write(supplemental_chars)
+        lob = await self.conn.createlob(
+            oracledb.DB_TYPE_CLOB, supplemental_chars
+        )
         await self.cursor.execute(
             """
             insert into TestCLOBs

utils/templates/connection.py

@@ -617,7 +617,9 @@ def commit(self) -> None:
         self._verify_connected()
         self._impl.commit()
 
-    def createlob(self, lob_type: DbType) -> LOB:
+    def createlob(
+        self, lob_type: DbType, data: Union[str, bytes] = None
+    ) -> LOB:
         """
         Create and return a new temporary LOB of the specified type.
         """
@@ -629,6 +631,8 @@ def createlob(self, lob_type: DbType) -> LOB:
             )
             raise TypeError(message)
         impl = self._impl.create_temp_lob_impl(lob_type)
+        if data:
+            impl.write(data, 1)
         return LOB._from_impl(impl)
 
     def cursor(self, scrollable: bool = False) -> Cursor:
@@ -1325,7 +1329,9 @@ async def commit(self) -> None:
         self._verify_connected()
         await self._impl.commit()
 
-    async def createlob(self, lob_type: DbType) -> LOB:
+    async def createlob(
+        self, lob_type: DbType, data: Union[str, bytes] = None
+    ) -> AsyncLOB:
         """
         Create and return a new temporary LOB of the specified type.
         """
@@ -1337,6 +1343,8 @@ async def createlob(self, lob_type: DbType) -> LOB:
             )
             raise TypeError(message)
         impl = await self._impl.create_temp_lob_impl(lob_type)
+        if data:
+            await impl.write(data, 1)
         return AsyncLOB._from_impl(impl)
 
     def cursor(self, scrollable: bool = False) -> AsyncCursor: