Further nudge users towards python-oracledb.

ReadTheDocs.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -13,7 +13,17 @@ Thank you for using cx_Oracle.
 
 See https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html for how to report security issues
 
-Please answer these questions so we can help you.
+The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a new
+repository at https://github.com/oracle/python-oracledb.  The installation
+instructions are at:
+https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html
+
+Update to python-oracledb, if possible, and submit your bug report to the
+python-oracledb repository.
+
+No further releases under the cx_Oracle namespace are planned.
+
+Otherwise, please answer these questions so we can help you.
 
 Use Markdown syntax, see https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 

.github/ISSUE_TEMPLATE/documentation-and-example-improvements.md

@@ -9,16 +9,13 @@ assignees: ''
 
 <!--
 
-Thank you for using cx_Oracle.
+The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a new
+repository at https://github.com/oracle/python-oracledb. The installation
+instructions are at:
+https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html
 
-Please answer these questions so we can help you.
+Please submit your documentation and example improvements to the python-oracledb repository.
 
-Use Markdown syntax, see https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
+No further releases under the cx_Oracle namespace are planned.
 
 -->
-
-1. What is the link to the documentation section that needs improving?
-
-2. Describe the confusion
-
-3. Suggest changes that would help

.github/ISSUE_TEMPLATE/enhancement-requests.md

@@ -9,16 +9,13 @@ assignees: ''
 
 <!--
 
-Thank you for using cx_Oracle.
+The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a new
+repository at https://github.com/oracle/python-oracledb.  The installation
+instructions are at:
+https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html
 
-Review existing enhancement requests: https://github.com/oracle/python-cx_Oracle/labels/enhancement
+Please submit your enhancement requests to the python-oracledb repository.
 
-Please answer these questions so we can help you.
-
-Use Markdown syntax, see https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
+No further releases under the cx_Oracle namespace are planned.
 
 -->
-
-1. Describe your new request in detail
-
-2. Give supporting information about tools and operating systems.  Give relevant product version numbers

.github/ISSUE_TEMPLATE/general-questions-and-runtime-problems.md

@@ -11,7 +11,14 @@ assignees: ''
 
 Thank you for using cx_Oracle.
 
-Review the user manual: https://cx-oracle.readthedocs.io/en/latest/index.html
+The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a new
+repository at https://github.com/oracle/python-oracledb.  The installation
+instructions are at:
+https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html
+
+Update to python-oracledb, if possible.
+
+Otherwise, review the cx_Oracle user manual: https://cx-oracle.readthedocs.io/en/latest/index.html
 
 Please answer these questions so we can help you.
 

.github/ISSUE_TEMPLATE/installation-questions.md

@@ -11,9 +11,16 @@ assignees: ''
 
 Thank you for using cx_Oracle.
 
+The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a new
+repository at https://github.com/oracle/python-oracledb. The installation
+instructions are at:
+https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html
+
 Do these before creating a new issue:
 
-    Review and follow the Installation Instructions: https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html
+    Update to python-oracledb, if possible.
+
+    Otherwise, review and follow the Installation Instructions: https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html
 
     Review the troubleshooting tips: https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html#troubleshooting
 

.github/SECURITY.md

@@ -1,13 +0,0 @@
-# Reporting Security Vulnerabilities
-
-Oracle values the independent security research community and believes that responsible disclosure of security vulnerabilities helps us ensure the security and privacy of all our users.
-
-Please do NOT raise a GitHub Issue to report a security vulnerability. If you believe you have found a security vulnerability, please submit a report to secalert_us@oracle.com preferably with a proof of concept. We provide additional information on [how to report security vulnerabilities to Oracle](https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html) which includes public encryption keys for secure email.
-
-We ask that you do not use other channels or contact project contributors directly.
-
-Non-vulnerability related security issues such as great new ideas for security features are welcome on GitHub Issues.
-
-## Security-Related Information
-
-We will provide security related information such as a threat model, considerations for secure use, or any known security issues in our documentation. Please note that labs and sample code are intended to demonstrate a concept and may not be sufficiently hardened for production use.

.github/SUPPORT.md

@@ -1,7 +1,9 @@
 # Python cx_Oracle Support
 
-cx_Oracle is an Open Source project, so do some searching and reading
-before asking questions.
+**The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a
+new repository at https://github.com/oracle/python-oracledb.  Please update to
+this new driver.  If you still have problems, open an issue on the new
+repository.**
 
 ## cx_Oracle Installation issues
 

.github/pull_request_template.md

@@ -1,21 +1,8 @@
 Thanks for contributing!
 
-Before submitting PRs for cx_Oracle you must have your signed *Oracle
-Contributor Agreement* accepted.  See
-https://www.oracle.com/technetwork/community/oca-486395.html
+The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a new
+repository at https://github.com/oracle/python-oracledb.
 
-If the problem solved is small, you may find it easier to open an Issue
-describing the problem and its cause so we can create the fix.
+Please submit your contributions to the python-oracledb repository.
 
-The bottom of your commit message must have the following line using your name
-and e-mail address as it appears in the OCA Signatories list.
-
-```
-Signed-off-by: Your Name <you@example.org>
-```
-
-This can be automatically added to pull requests by committing with:
-
-```
-git commit --signoff
-````
+No further releases under the cx_Oracle namespace are planned.

.readthedocs.yaml

@@ -1,9 +1,16 @@
+# required
 version: 2
 
-sphinx:
-  configuration: doc/src/conf.py
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
 
+# Build documentation in the doc/src directory with Sphinx
+sphinx:
+   configuration: doc/src/conf.py
+
+# declare Python requirements required to build docs
 python:
-  version: 3.8
-  install:
-    - requirements: doc/requirements.txt
+   install:
+   - requirements: doc/requirements.txt

CONTRIBUTING.md

@@ -1,44 +1,8 @@
 # Contributing
 
-We welcome your contributions! There are multiple ways to contribute.
+The cx_Oracle driver was renamed to python-oracledb in May 2022.  It has a new
+repository at https://github.com/oracle/python-oracledb
 
-## Issues
+Please submit your contributions to the python-oracledb repository.
 
-For bugs or enhancement requests, please file a GitHub issue unless it's security related. When filing a bug remember that the better written the bug is, the more likely it is to be fixed. If you think you've found a security vulnerability, do not raise a GitHub issue and follow the instructions on our [Security Policy](./.github/SECURITY.md).
-
-## Contributing Code
-
-We welcome your code contributions. To get started, you will need to sign the [Oracle Contributor Agreement](https://oca.opensource.oracle.com) (OCA).
-
-For pull requests to be accepted, the bottom of your commit message must have
-the following line using the name and e-mail address you used for the OCA.
-
-```text
-Signed-off-by: Your Name <you@example.org>
-```
-
-This can be automatically added to pull requests by committing with:
-
-```text
-git commit --signoff
-```
-
-Only pull requests from committers that can be verified as having
-signed the OCA can be accepted.
-
-### Pull request process
-
-1. Fork this repository
-1. Create a branch in your fork to implement the changes. We recommend using
-the issue number as part of your branch name, e.g. `1234-fixes`
-1. Ensure that any documentation is updated with the changes that are required
-by your fix.
-1. Ensure that any samples are updated if the base image has been changed.
-1. Submit the pull request. *Do not leave the pull request blank*. Explain exactly
-what your changes are meant to do and provide simple steps on how to validate
-your changes. Ensure that you reference the issue you created as well.
-1. We will review your PR before it is merged.
-
-## Code of Conduct
-
-Follow the [Golden Rule](https://en.wikipedia.org/wiki/Golden_Rule). If you'd like more specific guidelines see the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct/)
+No further releases under the cx_Oracle namespace are planned.

README.md

@@ -1,59 +1,33 @@
-# cx_Oracle version 8.3
+# Python cx_Oracle
 
-cx_Oracle is a Python extension module that enables access to Oracle
-Database.  It conforms to the [Python database API 2.0
-specification][1] with a considerable number of additions and a couple
-of exclusions.  See the
-[homepage](https://oracle.github.io/python-cx_Oracle/index.html) for a
-feature list.
+**cx_Oracle was obsoleted by
+[python-oracledb](https://oracle.github.io/python-oracledb/) in 2022.**
 
-cx_Oracle 8.3 has been tested with Python versions 3.6 through 3.10. You can
-use cx_Oracle with Oracle 11.2, 12c, 18c, 19c and 21c client libraries.
-Oracle's standard client-server version interoperability allows connection to
-both older and newer databases. For example Oracle 19c client libraries can
-connect to Oracle Database 11.2.   Older versions of cx_Oracle may work with
-older versions of Python.
+Python-oracledb uses the same Python DB API as cx_Oracle, and has many new
+features.
 
-## Installation
+Install with:
 
-See [cx_Oracle Installation][15].
+```
+python -m pip install oracledb
+```
 
-## Documentation
+Usage is like:
 
-See the [cx_Oracle Documentation][2] and [Release Notes][14].
+```
+import getpass
+import oracledb
 
-## Samples
+un = 'scott'
+cs = 'localhost/orclpdb1'
+pw = getpass.getpass(f'Enter password for {un}@{cs}: ')
 
-See the [/samples][12] directory and the [tutorial][6].  You can also
-look at the scripts in [cx_OracleTools][7] and the modules in
-[cx_PyOracleLib][8].
+with oracledb.connect(user=un, password=pw, dsn=cs) as connection:
+    with connection.cursor() as cursor:
+        sql = 'select systimestamp from dual'
+        for r in cursor.execute(sql):
+            print(r)
+```
 
-## Help
-
-Issues and questions can be raised with the cx_Oracle community on
-[GitHub][9] or on the [mailing list][5].
-
-## Tests
-
-See [/test][11].
-
-## Contributing
-
-See [CONTRIBUTING](https://github.com/oracle/python-cx_Oracle/blob/main/CONTRIBUTING.md)
-
-## License
-
-cx_Oracle is licensed under a BSD license which you can find [here][3].
-
-[1]: https://www.python.org/dev/peps/pep-0249
-[2]: http://cx-oracle.readthedocs.io
-[3]: https://github.com/oracle/python-cx_Oracle/blob/main/LICENSE.txt
-[5]: http://lists.sourceforge.net/lists/listinfo/cx-oracle-users
-[6]: https://github.com/oracle/python-cx_Oracle/tree/main/samples/tutorial
-[7]: http://cx-oracletools.sourceforge.net
-[8]: http://cx-pyoraclelib.sourceforge.net
-[9]: https://github.com/oracle/python-cx_Oracle/issues
-[11]: https://github.com/oracle/python-cx_Oracle/tree/main/test
-[12]: https://github.com/oracle/python-cx_Oracle/tree/main/samples
-[14]: https://cx-oracle.readthedocs.io/en/latest/release_notes.html
-[15]: https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html
+The source code for python-oracledb is at
+[github.com/oracle/python-oracledb](https://github.com/oracle/python-oracledb).

README.txt

@@ -1,5 +1,7 @@
-Please see the cx_Oracle home page for links to documentation, source, build
-and installation instructions:
+cx_Oracle was obsoleted by python-oracledb in 2022.
 
-https://oracle.github.io/python-cx_Oracle/index.html
+Python-oracledb uses the same Python DB API as cx_Oracle, and has many new
+features.
 
+See https://python-oracledb.readthedocs.io/en/latest/index.html for how to
+install and use this updated driver.

SECURITY.md

@@ -0,0 +1,37 @@
+# Reporting security vulnerabilities
+
+Oracle values the independent security research community and believes that
+responsible disclosure of security vulnerabilities helps us ensure the security
+and privacy of all our users.
+
+Please do NOT raise a GitHub Issue to report a security vulnerability. If you
+believe you have found a security vulnerability, please submit a report to
+[secalert_us@oracle.com][1] preferably with a proof of concept. Please review
+some additional information on [how to report security vulnerabilities to
+Oracle][2].  We encourage people who contact Oracle Security to use email
+encryption using [our encryption key][3].
+
+We ask that you do not use other channels or contact the project maintainers
+directly.
+
+Non-vulnerability related security issues including ideas for new or improved
+security features are welcome on GitHub Issues.
+
+## Security updates, alerts and bulletins
+
+Security updates will be released on a regular cadence. Many of our projects
+will typically release security fixes in conjunction with the Oracle Critical
+Patch Update program. Additional information, including past advisories, is
+available on our [security alerts][4] page.
+
+## Security-related information
+
+We will provide security related information such as a threat model,
+considerations for secure use, or any known security issues in our
+documentation. Please note that labs and sample code are intended to
+demonstrate a concept and may not be sufficiently hardened for production use.
+
+[1]: mailto:secalert_us@oracle.com
+[2]: https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html
+[3]: https://www.oracle.com/security-alerts/encryptionkey.html
+[4]: https://www.oracle.com/security-alerts/

doc/requirements.txt

@@ -1,2 +1,2 @@
-sphinx==4.1.2
-sphinx_rtd_theme==0.5.1
+sphinx>=4.2.0
+sphinx-rtd-theme>=0.5.2

doc/src/api_manual/aq.rst

@@ -4,6 +4,13 @@
 Advanced Queuing (AQ)
 *********************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 See :ref:`aqusermanual` for more information about using AQ in cx_Oracle.
 
 .. note::

doc/src/api_manual/connection.rst

@@ -4,6 +4,13 @@
 Connection Object
 *****************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 .. note::
 
     Any outstanding changes will be rolled back when the connection object

doc/src/api_manual/cursor.rst

@@ -5,6 +5,13 @@ Cursor Object
 *************
 
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 .. method:: Cursor.__enter__()
 
     The entry point for the cursor as a context manager. It returns itself.
@@ -290,7 +297,7 @@ Cursor Object
     See :ref:`fetching` for an example.
 
 
-.. method:: Cursor.fetchmany(num_rows=cursor.arraysize)
+.. method:: Cursor.fetchmany(numRows=cursor.arraysize)
 
     Fetch the next set of rows of a query result, returning a list of tuples.
     An empty list is returned if no more rows are available. Note that the

doc/src/api_manual/deprecations.rst

@@ -4,6 +4,13 @@
 Deprecations
 ************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 The following tables contains all of the deprecations in the cx_Oracle API,
 when they were first deprecated and a comment on what should be used instead,
 if applicable. The most recent deprecations are listed first.

doc/src/api_manual/lob.rst

@@ -4,6 +4,13 @@
 LOB Objects
 ***********
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 See :ref:`lobdata` for more information about using LOBs.
 
 .. note::

doc/src/api_manual/module.rst

@@ -6,6 +6,13 @@
 Module Interface
 ****************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 .. data:: __future__
 
     Special object which contains attributes which control the behavior of
@@ -40,7 +47,7 @@ Module Interface
         mode=cx_Oracle.DEFAULT_AUTH, handle=0, pool=None, threaded=False, \
         events=False, cclass=None, purity=cx_Oracle.ATTR_PURITY_DEFAULT, \
         newpassword=None, encoding=None, nencoding=None, edition=None, \
-        appcontext=[], tag=None, matchanytag=None, shardingkey=[], \
+        appcontext=[], tag=None, matchanytag=False, shardingkey=[], \
         supershardingkey=[], stmtcachesize=20)
     Connection(user=None, password=None, dsn=None, \
         mode=cx_Oracle.DEFAULT_AUTH, handle=0, pool=None, threaded=False, \

doc/src/api_manual/object_type.rst

@@ -4,6 +4,13 @@
 Object Type Objects
 *******************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 .. note::
 
     This object is an extension to the DB API. It is returned by the

doc/src/api_manual/session_pool.rst

@@ -4,6 +4,13 @@
 SessionPool Object
 ******************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 .. note::
 
     This object is an extension to the DB API.
@@ -160,7 +167,7 @@ SessionPool Object
     unusable, it is discarded and a different connection is selected to be
     returned by :meth:`SessionPool.acquire()`.  Setting ``ping_interval`` to a
     negative value disables pinging.  Setting it to 0 forces a ping for every
-    ``aquire()`` and is not recommended.
+    ``acquire()`` and is not recommended.
 
     Prior to cx_Oracle 8.2, the ping interval was fixed at 60 seconds.
 

doc/src/api_manual/soda.rst

@@ -4,6 +4,13 @@
 SODA
 ****
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 `Oracle Database Simple Oracle Document Access (SODA)
 <https://docs.oracle.com/en/database/oracle/simple-oracle-document-access>`__
 allows documents to be inserted, queried, and retrieved from Oracle Database

doc/src/api_manual/subscription.rst

@@ -4,6 +4,13 @@
 Subscription Object
 *******************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 .. note::
 
     This object is an extension the DB API.

doc/src/api_manual/variable.rst

@@ -4,6 +4,13 @@
 Variable Objects
 ****************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 .. note::
 
     The DB API definition does not define this object.

doc/src/index.rst

@@ -1,6 +1,13 @@
 Welcome to cx_Oracle's documentation!
 =====================================
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 **cx_Oracle** is a module that enables access to Oracle Database and conforms
 to the Python database API specification. This module is currently tested
 against Oracle Client 21c, 19c, 18c, 12c, and 11.2, and Python 3.6, 3.7, 3.8,

doc/src/release_notes.rst

@@ -5,6 +5,13 @@
 cx_Oracle Release Notes
 =======================
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 For any deprecations, see :ref:`Deprecations <deprecations>`.
 
 Version 8.3 (November 2021)

doc/src/user_guide/aq.rst

@@ -4,6 +4,13 @@
 Oracle Advanced Queuing (AQ)
 ****************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 `Oracle Advanced Queuing
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=ADQUE>`__ is a highly
 configurable and scalable messaging feature of Oracle Database.  It has

doc/src/user_guide/batch_statement.rst

@@ -4,6 +4,13 @@
 Batch Statement Execution and Bulk Loading
 ******************************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Inserting or updating multiple rows can be performed efficiently with
 :meth:`Cursor.executemany()`, making it easy to work with large data sets with
 cx_Oracle.  This method can significantly outperform repeated calls to

doc/src/user_guide/bind.rst

@@ -4,6 +4,13 @@
 Using Bind Variables
 ********************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 SQL and PL/SQL statements that pass data to and from Oracle Database should use
 placeholders in SQL and PL/SQL statements that mark where data is supplied or
 returned.  These placeholders are referred to as bind variables or bind

doc/src/user_guide/connection_handling.rst

@@ -4,6 +4,13 @@
 Connecting to Oracle Database
 *****************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Connections between cx_Oracle and Oracle Database are used for executing
 :ref:`SQL <sqlexecution>`, :ref:`PL/SQL <plsqlexecution>`, and :ref:`SODA
 <sodausermanual>`.
@@ -336,7 +343,7 @@ connection pool:
     pool.close()
 
 Other :meth:`cx_Oracle.SessionPool()` options can be used at pool creation.
-For example the ``getmode`` value can be set so that any ``aquire()`` call will
+For example the ``getmode`` value can be set so that any ``acquire()`` call will
 wait for a connection to become available if all are currently in use, for
 example:
 
@@ -349,8 +356,8 @@ example:
                                  getmode=cx_Oracle.SPOOL_ATTRVAL_WAIT,
                                  encoding="UTF-8")
 
-See `ConnectionPool.py
-<https://github.com/oracle/python-cx_Oracle/tree/main/samples/ConnectionPool.py>`__
+See `connection_pool.py
+<https://github.com/oracle/python-cx_Oracle/tree/main/samples/connection_pool.py>`__
 for an example.
 
 Before :meth:`SessionPool.acquire()` returns, cx_Oracle does a lightweight check
@@ -1348,10 +1355,10 @@ of the function :meth:`cx_Oracle.connect()` constructor:
                                    dsn="dbhost.example.com/orclpdb1",
                                    newpassword=newpwd, encoding="UTF-8")
 
-.. _autononmousdb:
+.. _autonomousdb:
 
-Connecting to Oracle Cloud Autononmous Databases
-================================================
+Connecting to Oracle Cloud Autonomous Databases
+===============================================
 
 To enable connection to Oracle Autonomous Database in Oracle Cloud, a wallet
 needs be downloaded from the cloud, and cx_Oracle needs to be configured to use

doc/src/user_guide/cqn.rst

@@ -4,6 +4,13 @@
 Continuous Query Notification (CQN)
 ***********************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 `Continuous Query Notification (CQN)
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
 id=GUID-373BAF72-3E63-42FE-8BEA-8A2AEFBF1C35>`__ allows applications to receive
@@ -19,14 +26,14 @@ what types of SQL should trigger a notification, whether notifications should
 survive database loss, and control over unsubscription.  You can also choose
 whether notification messages will include ROWIDs of affected rows.
 
-By default, object-level (previously known as Database Change Notification)
-occurs and the Python notification method is invoked whenever a database
-transaction is committed that changes an object that a registered query
-references, regardless of whether the actual query result changed.  However if
-the :meth:`subscription <Connection.subscribe>` option ``qos`` is
-:data:`cx_Oracle.SUBSCR_QOS_QUERY` then query-level notification occurs.  In
-this mode, the database notifies the application whenever a transaction changing
-the result of the registered query is committed.
+By default, object-level notification (previously known as Database Change
+Notification) occurs.  With this mode a Python notification method is invoked
+whenever a database transaction is committed that changes an object referenced
+by a registered query.  However if the :meth:`subscription
+<Connection.subscribe>` option ``qos`` is :data:`cx_Oracle.SUBSCR_QOS_QUERY`
+then query-level notification occurs.  In this mode, the database notifies the
+application whenever a committed transaction changes the result of a registered
+query.
 
 CQN is best used to track infrequent data changes.
 
@@ -109,7 +116,7 @@ calling :meth:`Subscription.registerquery()`.  Registering a query behaves
 similarly to :meth:`Cursor.execute()`, but only queries are permitted and the
 ``args`` parameter must be a sequence or dictionary.
 
-An example script to receive query notifications when the 'CUSTOMER' table data
+An example script to receive query notifications when the 'REGIONS' table data
 changes is:
 
 .. code-block:: python
@@ -129,6 +136,7 @@ changes is:
     subscr = connection.subscribe(callback=cqn_callback,
                                   operations=cx_Oracle.OPCODE_INSERT | cx_Oracle.OPCODE_DELETE,
                                   qos=cx_Oracle.SUBSCR_QOS_QUERY | cx_Oracle.SUBSCR_QOS_ROWIDS)
+
     subscr.registerquery("select * from regions")
     input("Hit enter to stop CQN demo\n")
 

doc/src/user_guide/exception_handling.rst

@@ -4,6 +4,13 @@
 Exception Handling
 ******************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 All exceptions raised by cx_Oracle are inherited from :attr:`cx_Oracle.Error`.
 See :ref:`Exceptions <exceptions>` for more details on the various exceptions
 defined by cx_Oracle. See the exception handling section in the

doc/src/user_guide/globalization.rst

@@ -4,6 +4,13 @@
 Character Sets and Globalization
 ********************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Data fetched from, and sent to, Oracle Database will be mapped between the
 database character set and the "Oracle client" character set of the Oracle
 Client libraries used by cx_Oracle.  If data cannot be correctly mapped between

doc/src/user_guide/ha.rst

@@ -4,6 +4,13 @@
 High Availability with cx_Oracle
 ********************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Applications can utilize many features for high availability (HA) during planned and
 unplanned outages in order to:
 

doc/src/user_guide/initialization.rst

@@ -4,6 +4,13 @@
 cx_Oracle 8 Initialization
 **************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 The cx_Oracle module loads Oracle Client libraries which communicate over
 Oracle Net to an existing database.  The Oracle Client libraries need to be
 installed separately.  See :ref:`installation`.  Oracle Net is not a separate
@@ -168,8 +175,8 @@ example, if the Oracle Instant Client Libraries are in
             cx_Oracle.init_oracle_client(lib_dir=lib_dir)
     except Exception as err:
         print("Whoops!")
-        print(err);
-        sys.exit(1);
+        print(err)
+        sys.exit(1)
 
 Note the use of a 'raw' string ``r"..."`` on Windows so that backslashes are
 treated as directory separators.
@@ -220,8 +227,8 @@ you can call :meth:`cx_Oracle.init_oracle_client()`:
         cx_Oracle.init_oracle_client(config_dir="/etc/my-oracle-config")
     except Exception as err:
         print("Whoops!")
-        print(err);
-        sys.exit(1);
+        print(err)
+        sys.exit(1)
 
 This is equivalent to setting the environment variable `TNS_ADMIN
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-12C94B15-2CE1-4B98-9D0C-8226A9DDF4CB>`__
@@ -241,7 +248,7 @@ located with, or separately from, the ``tnsnames.ora`` and ``sqlnet.ora``
 files.  It should be securely stored.  The ``sqlnet.ora`` file's
 ``WALLET_LOCATION`` path should be set to the directory containing
 ``cwallet.sso``.  For Oracle Autonomous Database use of wallets, see
-:ref:`autononmousdb`.
+:ref:`autonomousdb`.
 
 Note the :ref:`easyconnect` can set many common configuration options without
 needing ``tnsnames.ora`` or ``sqlnet.ora`` files.
@@ -393,8 +400,8 @@ parameters is:
                                      error_url="https://example.com/MyInstallInstructions.html")
     except Exception as err:
         print("Whoops!")
-        print(err);
-        sys.exit(1);
+        print(err)
+        sys.exit(1)
 
 The convention for ``driver_name`` is to separate the product name from the
 product version by a colon and single blank characters.  The value will be shown

doc/src/user_guide/installation.rst

@@ -4,12 +4,19 @@
 cx_Oracle 8 Installation
 ************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Overview
 ========
 
-To use cx_Oracle 8 with Python and Oracle Database you need:
+To use cx_Oracle 8.3 with Python and Oracle Database you need:
 
-- Python 3.5 and higher. Older versions of cx_Oracle may work with older
+- Python 3.6 and higher. Older versions of cx_Oracle may work with older
   versions of Python.
 
 - Oracle Client libraries. These can be from the free `Oracle Instant Client
@@ -35,18 +42,12 @@ product: it is how the Oracle Client and Oracle Database communicate.
 Quick Start cx_Oracle Installation
 ==================================
 
-The `Quick Start: Developing Python Applications for Oracle Database
-<https://www.oracle.com/database/technologies/appdev/python/quickstartpythononprem.html>`__
-and `Quick Start: Developing Python Applications for Oracle Autonomous Database
-<https://www.oracle.com/database/technologies/appdev/python/quickstartpython.html>`__
-instructions have steps for Windows, Linux, and macOS.
-
-Alternatively you can:
+You can:
 
 - Install `Python <https://www.python.org/downloads>`__ 3, if not already
   available.  On macOS you must always install your own Python.
 
-  Python 3.5 and higher are supported by cx_Oracle 8.  If you use Python 2,
+  Python 3.6 and higher are supported by cx_Oracle 8.3.  If you use Python 2,
   then the older cx_Oracle 7.3 will install.
 
 - Install cx_Oracle from `PyPI
@@ -191,6 +192,13 @@ Installing cx_Oracle on Linux
 This section discusses the generic installation methods on Linux.  To use Python
 and cx_Oracle RPM packages from yum on Oracle Linux, see :ref:`oraclelinux`.
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Install cx_Oracle
 -----------------
 
@@ -424,6 +432,13 @@ Developers <https://yum.oracle.com/oracle-linux-python.html>`__.
 Installing cx_Oracle on Windows
 ===============================
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Install cx_Oracle
 -----------------
 
@@ -491,10 +506,11 @@ To use cx_Oracle with Oracle Instant Client zip files:
    a 64-bit or 32-bit architecture to match Instant Client's architecture.
    Each Instant Client version requires a different redistributable version:
 
-       - For Instant Client 19 install `VS 2017 <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`__.
-       - For Instant Client 18 or 12.2 install `VS 2013 <https://support.microsoft.com/en-us/kb/2977003#bookmark-vs2013>`__
-       - For Instant Client 12.1 install `VS 2010 <https://support.microsoft.com/en-us/kb/2977003#bookmark-vs2010>`__
-       - For Instant Client 11.2 install `VS 2005 64-bit <https://www.microsoft.com/en-us/download/details.aspx?id=18471>`__ or `VS 2005 32-bit <https://www.microsoft.com/en-ca/download/details.aspx?id=3387>`__
+       - For Instant Client 21 install `VS 2019 <https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170>`__ or later.
+       - For Instant Client 19 install `VS 2017 <https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170>`__.
+       - For Instant Client 18 or 12.2 install `VS 2013 <https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2013-vc-120>`__
+       - For Instant Client 12.1 install `VS 2010 <https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2010-vc-100-sp1-no-longer-supported>`__
+       - For Instant Client 11.2 install `VS 2005 64-bit <https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2005-vc-80-sp1-no-longer-supported>`__
 
 Configure Oracle Instant Client
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -571,6 +587,13 @@ Python architecture.
 Installing cx_Oracle on macOS (Intel x86)
 =========================================
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Install Python
 --------------
 

doc/src/user_guide/introduction.rst

@@ -9,6 +9,13 @@ Database.  It conforms to the `Python Database API v2.0 Specification
 <https://www.python.org/dev/peps/pep-0249/>`__ with a considerable number of
 additions and a couple of exclusions.
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Architecture
 ------------
 
@@ -131,12 +138,6 @@ The output is::
 Examples and Tutorials
 ----------------------
 
-The `Quick Start: Developing Python Applications for Oracle Database
-<https://www.oracle.com/database/technologies/appdev/python/quickstartpythononprem.html>`__
-and `Quick Start: Developing Python Applications for Oracle Autonomous Database
-<https://www.oracle.com/database/technologies/appdev/python/quickstartpython.html>`__
-instructions have steps for Windows, Linux, and macOS.
-
 Runnable examples are in the `GitHub samples directory
 <https://github.com/oracle/python-cx_Oracle/tree/main/samples>`__.  A `Python
 cx_Oracle tutorial

doc/src/user_guide/json_data_type.rst

@@ -4,6 +4,13 @@
 Working with the JSON Data Type
 *******************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Native support for JSON data was introduced in Oracle Database 12c.  You can
 use JSON with relational database features, including transactions, indexing,
 declarative querying, and views.  You can project JSON data relationally,

doc/src/user_guide/lob_data.rst

@@ -4,6 +4,13 @@
 Using CLOB and BLOB Data
 ************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Oracle Database uses :ref:`lobobj` to store large data such as text, images,
 videos and other multimedia formats.  The maximum size of a LOB is limited to
 the size of the tablespace storing it.

doc/src/user_guide/plsql_execution.rst

@@ -4,6 +4,13 @@
 PL/SQL Execution
 ****************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 PL/SQL stored procedures, functions and anonymous blocks can be called from
 cx_Oracle.
 

doc/src/user_guide/soda.rst

@@ -4,6 +4,13 @@
 Simple Oracle Document Access (SODA)
 ************************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Overview
 ========
 

doc/src/user_guide/sql_execution.rst

@@ -4,6 +4,13 @@
 SQL Execution
 *************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Executing SQL statements is the primary way in which a Python application
 communicates with Oracle Database.  Statements are executed using the methods
 :meth:`Cursor.execute()` or :meth:`Cursor.executemany()`.  Statements include

doc/src/user_guide/startup.rst

@@ -4,6 +4,13 @@
 Starting and Stopping Oracle Database
 *************************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 This chapter covers how to start up and shutdown Oracle Database using
 cx_Oracle.
 

doc/src/user_guide/tracing_sql.rst

@@ -4,6 +4,13 @@
 Tracing SQL and PL/SQL Statements
 *********************************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Subclass Connections
 ====================
 

doc/src/user_guide/tuning.rst

@@ -4,6 +4,13 @@
 Tuning cx_Oracle
 ****************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Some general tuning tips are:
 
 * Tune your application architecture.

doc/src/user_guide/txn_management.rst

@@ -4,6 +4,13 @@
 Transaction Management
 **********************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 A database transaction is a grouping of SQL statements that make a logical data
 change to the database.
 

doc/src/user_guide/xml_data_type.rst

@@ -4,6 +4,13 @@
 Working with XMLTYPE
 ********************
 
+.. note::
+
+    **cx_Oracle has a major new release under a new name and homepage**
+    `python-oracledb <https://oracle.github.io/python-oracledb/>`__.
+
+    **New projects should install python-oracledb instead of cx_Oracle.**
+
 Oracle XMLType columns are fetched as strings by default.  This is currently
 limited to the maximum length of a ``VARCHAR2`` column.  To return longer XML
 values, they must be queried as LOB values instead.

samples/README.md

@@ -1,4 +1,16 @@
-# cx_Oracle Examples
+# Samples
+
+## News
+
+**cx_Oracle has a major new release under a new name and homepage
+[python-oracledb](https://oracle.github.io/python-oracledb/).**
+
+**New projects should install python-oracledb instead of cx_Oracle: python -m pip install oracledb**
+
+**The new source code and samples can be found at
+[github.com/oracle/python-oracledb](https://github.com/oracle/python-oracledb).**
+
+## cx_Oracle Examples
 
 This directory contains samples for [cx_Oracle][6].  Documentation is
 [here][7].  A separate tutorial is [here][8].

samples/sample_env.py

@@ -41,6 +41,19 @@
 # user for on premises databases is SYSTEM.
 #------------------------------------------------------------------------------
 
+print("""
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!!  cx_Oracle was renamed to python-oracledb.                      !!!
+!!!  Use python-oracledb instead of cx_Oracle for development.      !!!
+!!!  Install with:                                                  !!!
+!!!    python -m pip install oracledb                               !!!
+!!!  and use the new samples in:                                    !!!
+!!!    https://github.com/oracle/python-oracledb/tree/main/samples  !!!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+""")
+
 import getpass
 import os
 import sys

samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html

@@ -11,7 +11,18 @@
 
   <h1>Python and Oracle Database Tutorial: Scripting for the Future</h1>
 
-  <img src="resources/community-py-200.png" alt="Python cx_Oracle logo" />
+  <div class="announcement">
+
+  <p><strong>cx_Oracle has a major new release under a new name and
+  homepage <a href="https://oracle.github.io/python-oracledb/"
+  >python-oracledb</a>.</strong></p>
+  
+  <p><strong>We recommend you use the  <a
+  href="https://oracle.github.io/python-oracledb/samples/tutorial/Python-and-Oracle-Database-The-New-Wave-of-Scripting.html"
+  >new python-oracledb tutorial</a> instead of this cx_Oracle tutorial.</strong></p>
+  
+  </div> <!-- announcement -->
+
 
   <h2>Contents</h2>
 

samples/tutorial/resources/base.css

@@ -60,3 +60,10 @@ hr {
 pre {
     background: #E0E0E0;
 }
+
+.announcement {
+  margin-top: 30px;
+  padding: 30px;
+  padding-bottom: 15px;
+  background-color: #F0CC71;
+}

test/test_3000_subscription.py

@@ -7,39 +7,60 @@
 """
 
 import threading
+import unittest
 
 import cx_Oracle as oracledb
 import test_env
 
-class SubscriptionData(object):
+class SubscriptionData:
 
     def __init__(self, num_messages_expected):
         self.condition = threading.Condition()
         self.num_messages_expected = num_messages_expected
         self.num_messages_received = 0
+
+    def _process_message(self, message):
+        pass
+
+    def callback_handler(self, message):
+        if message.type != oracledb.EVENT_DEREG:
+            self._process_message(message)
+            self.num_messages_received += 1
+        if message.type == oracledb.EVENT_DEREG or \
+                self.num_messages_received == self.num_messages_expected:
+            with self.condition:
+                self.condition.notify()
+
+    def wait_for_messages(self):
+        if self.num_messages_received < self.num_messages_expected:
+            with self.condition:
+                self.condition.wait(10)
+
+
+class AQSubscriptionData(SubscriptionData):
+    pass
+
+
+class DMLSubscriptionData(SubscriptionData):
+
+    def __init__(self, num_messages_expected):
+        super().__init__(num_messages_expected)
         self.table_operations = []
         self.row_operations = []
         self.rowids = []
 
-    def CallbackHandler(self, message):
-        if message.type != oracledb.EVENT_DEREG:
-            table, = message.tables
-            self.table_operations.append(table.operation)
-            for row in table.rows:
-                self.row_operations.append(row.operation)
-                self.rowids.append(row.rowid)
-            self.num_messages_received += 1
-        if message.type == oracledb.EVENT_DEREG or \
-                self.num_messages_received == self.num_messages_expected:
-            self.condition.acquire()
-            self.condition.notify()
-            self.condition.release()
+    def _process_message(self, message):
+        table, = message.tables
+        self.table_operations.append(table.operation)
+        for row in table.rows:
+            self.row_operations.append(row.operation)
+            self.rowids.append(row.rowid)
 
 
 class TestCase(test_env.BaseTestCase):
 
-    def test_3000_subscription(self):
-        "3000 - test Subscription for insert, update, delete and truncate"
+    def test_3000_dml_subscription(self):
+        "3000 - test subscription for insert, update, delete and truncate"
 
         # skip if running on the Oracle Cloud, which does not support
         # subscriptions currently
@@ -67,9 +88,9 @@ class TestCase(test_env.BaseTestCase):
         rowids = []
 
         # set up subscription
-        data = SubscriptionData(5)
+        data = DMLSubscriptionData(5)
         connection = test_env.get_connection(threaded=True, events=True)
-        sub = connection.subscribe(callback=data.CallbackHandler,
+        sub = connection.subscribe(callback=data.callback_handler,
                                    timeout=10, qos=oracledb.SUBSCR_QOS_ROWIDS)
         sub.registerquery("select * from TestTempTable")
         connection.autocommit = True
@@ -105,8 +126,7 @@ class TestCase(test_env.BaseTestCase):
         cursor.execute("truncate table TestTempTable")
 
         # wait for all messages to be sent
-        data.condition.acquire()
-        data.condition.wait(10)
+        data.wait_for_messages()
 
         # verify the correct messages were sent
         self.assertEqual(data.table_operations, table_operations)
@@ -134,5 +154,30 @@ class TestCase(test_env.BaseTestCase):
         self.assertRaises(oracledb.ProgrammingError, connection.subscribe,
                           client_initiated=True, clientInitiated=True)
 
+    @unittest.skip("multiple subscriptions cannot be created simultaneously")
+    def test_3002_aq_subscription(self):
+        "3002 - test subscription for AQ"
+
+        # create queue and clear it of all messages
+        queue = self.connection.queue("TEST_RAW_QUEUE")
+        queue.deqoptions.wait = oracledb.DEQ_NO_WAIT
+        while queue.deqone():
+            pass
+        self.connection.commit()
+
+        # set up subscription
+        data = AQSubscriptionData(1)
+        connection = test_env.get_connection(events=True)
+        sub = connection.subscribe(namespace=oracledb.SUBSCR_NAMESPACE_AQ,
+                                   name=queue.name, timeout=10,
+                                   callback=data.callback_handler)
+
+        # enqueue a message
+        queue.enqone(self.connection.msgproperties(payload="Some data"))
+        self.connection.commit()
+
+        # wait for all messages to be sent
+        data.wait_for_messages()
+
 if __name__ == "__main__":
     test_env.run_test_cases()