From 2a34daf58129f0ad3b4df8d17120524a74212451 Mon Sep 17 00:00:00 2001 From: Anthony Tuininga Date: Wed, 24 Jul 2019 16:39:55 -0600 Subject: [PATCH 01/13] Improve documentation; correct spelling mistakes. --- doc/src/connection.rst | 4 ++-- doc/src/cursor.rst | 6 ++--- doc/src/installation.rst | 48 +++++++++++++++++++++++++++++++--------- doc/src/module.rst | 8 +++---- doc/src/releasenotes.rst | 8 +++---- doc/src/session_pool.rst | 2 +- doc/src/soda.rst | 2 +- 7 files changed, 53 insertions(+), 25 deletions(-) diff --git a/doc/src/connection.rst b/doc/src/connection.rst index 627b012e..26683725 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -23,7 +23,7 @@ Connection Object .. method:: Connection.__exit__() The exit point for the connection as a context manager. This will close - the connection and roll back any uncomitted transaction. + the connection and roll back any uncommitted transaction. .. note:: @@ -622,7 +622,7 @@ Connection Object The subscription can be deregistered in the database by calling the function :meth:`~Connection.unsubscribe()`. If this method is not called and the connection that was used to create the subscription is - explictly closed using the function :meth:`~Connection.close()`, the + explicitly closed using the function :meth:`~Connection.close()`, the subscription will not be deregistered in the database. diff --git a/doc/src/cursor.rst b/doc/src/cursor.rst index f345740d..0094aa45 100644 --- a/doc/src/cursor.rst +++ b/doc/src/cursor.rst @@ -260,7 +260,7 @@ Cursor Object cursor's arraysize attribute can affect the performance of this operation. The number of rows to fetch is specified by the parameter. If it is not - given, the cursor's arrysize attribute determines the number of rows to be + given, the cursor's arraysize attribute determines the number of rows to be fetched. If the number of rows available to be fetched is fewer than the amount requested, fewer rows will be returned. @@ -321,7 +321,7 @@ Cursor Object .. method:: Cursor.getbatcherrors() Retrieve the exceptions that took place after a call to - :meth:`~Cursor.executemany()` with batcherors enabled. This will return a + :meth:`~Cursor.executemany()` with batcherrors enabled. This will return a list of Error objects, one error for each iteration that failed. The offset can be determined by looking at the offset attribute of the error object. @@ -519,7 +519,7 @@ Cursor Object .. method:: Cursor.var(dataType, [size, arraysize, inconverter, outconverter, \ typename, encodingErrors]) - Create a variable with the specified charactistics. This method was + Create a variable with the specified characteristics. This method was designed for use with PL/SQL in/out variables where the length or type cannot be determined automatically from the Python object passed in or for use in input and output type handlers defined on cursors or connections. diff --git a/doc/src/installation.rst b/doc/src/installation.rst index 79b8874b..7de2e24c 100644 --- a/doc/src/installation.rst +++ b/doc/src/installation.rst @@ -42,6 +42,10 @@ Quick Start cx_Oracle Installation the source package will be downloaded instead. This will be compiled and the resulting binary installed. + If you are behind a proxy, specify your proxy server:: + + python -m pip install cx_Oracle --proxy=http://proxy.example.com:80 --upgrade + - Add Oracle 19, 18, 12 or 11.2 client libraries to your operating system library search path such as ``PATH`` on Windows or ``LD_LIBRARY_PATH`` on Linux. On macOS move the files to ``~/lib`` @@ -64,10 +68,10 @@ Quick Start cx_Oracle Installation `__ release. - Version 19, 18 and 12.2 client libraries can connect to Oracle Database 11.2 or - greater. Version 12.1 client libraries can connect to Oracle Database - 10.2 or greater. Version 11.2 client libraries can connect to Oracle - Database 9.2 or greater. + Version 19, 18 and 12.2 client libraries can connect to Oracle Database 11.2 + or greater. Version 12.1 client libraries can connect to Oracle Database 10.2 + or greater. Version 11.2 client libraries can connect to Oracle Database 9.2 + or greater. The database abstraction layer in cx_Oracle is `ODPI-C `__, which means that the `ODPI-C @@ -189,6 +193,10 @@ install cx_Oracle from `PyPI python -m pip install cx_Oracle --upgrade +If you are behind a proxy, specify your proxy server:: + + python -m pip install cx_Oracle --proxy=http://proxy.example.com:80 --upgrade + This will download and install a pre-compiled binary `if one is available `__ for your architecture. If a pre-compiled binary is not available, the source @@ -375,6 +383,10 @@ package to install cx_Oracle from `PyPI python -m pip install cx_Oracle --upgrade +If you are behind a proxy, specify your proxy server:: + + python -m pip install cx_Oracle --proxy=http://proxy.example.com:80 --upgrade + This will download and install a pre-compiled binary `if one is available `__ for your architecture. If a pre-compiled binary is not available, the source @@ -433,12 +445,14 @@ To use cx_Oracle with Oracle Instant Client zip files: SET PATH=C:\oracle\instantclient_18_3;%PATH% python %* - Invoke this batch file everytime you want to run python. + Invoke this batch file every time you want to run python. Alternatively use ``SET`` to change your ``PATH`` in each command prompt window before you run python. -4. Oracle Instant Client libraries require a Visual Studio redistributable with a 64-bit or 32-bit architecture to match Instant Client's architecture. Each Instant Client version requires a different redistributable version: +4. Oracle Instant Client libraries require a Visual Studio redistributable with + 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 18 or 12.2 install `VS 2013 `__ - For Instant Client 12.1 install `VS 2010 `__ @@ -505,6 +519,10 @@ package to install cx_Oracle from `PyPI python -m pip install cx_Oracle --upgrade +If you are behind a proxy, specify your proxy server:: + + python -m pip install cx_Oracle --proxy=http://proxy.example.com:80 --upgrade + The source will be downloaded, compiled, and the resulting binary installed. @@ -650,8 +668,18 @@ If installation fails: using a different method. **Google anything that looks like an error.** Try some potential solutions. - - Was there a network connection error? Do you need to see the environment - variables ``http_proxy`` and/or ``https_proxy``? + - Was there a network connection error? Do you need to set the + environment variables ``http_proxy`` and/or ``https_proxy``? Or + try ``pip install --proxy=http://proxy.example.com:80 cx_Oracle + --upgrade``? + + - If upgrading gave no errors but the old version is still + installed, try ``pip install cx_Oracle --upgrade + --force-reinstall`` + + - If you do not have access to modify your system version of + Python, can you use ``pip install cx_Oracle --upgrade --user`` + or venv? - Do you get the error "``No module named pip``"? The pip module is builtin to Python from version 2.7.9 but is sometimes removed by the OS. Use the @@ -659,8 +687,8 @@ If installation fails: instead. - Do you get the error "``fatal error: dpi.h: No such file or directory``" - when building from source code? Ensure that your source installation has a - subdirectory called "odpi" containing files. If missing, review the + when building from source code? Ensure that your source installation has + a subdirectory called "odpi" containing files. If missing, review the section on `Install Using GitHub`_. If using cx_Oracle fails: diff --git a/doc/src/module.rst b/doc/src/module.rst index 13af4edc..d2083153 100644 --- a/doc/src/module.rst +++ b/doc/src/module.rst @@ -69,7 +69,7 @@ Module Interface The pool parameter is expected to be a :ref:`session pool object ` and the use of this parameter is the equivalent of calling :meth:`SessionPool.acquire()`. Parameters not - acecpted by that method are ignored. + accepted by that method are ignored. The threaded parameter is expected to be a boolean expression which indicates whether or not Oracle should wrap accesses to connections with a @@ -78,7 +78,7 @@ Module Interface The events parameter is expected to be a boolean expression which indicates whether or not to initialize Oracle in events mode. This is required for - continuous query notification and high availablity event notifications. + continuous query notification and high availability event notifications. The cclass parameter is expected to be a string and defines the connection class for database resident connection pooling (DRCP). @@ -412,7 +412,7 @@ parameter for the :meth:`Connection.deq()` method. .. data:: DEQ_BROWSE This constant is used to specify that dequeue should read the message - without acquiring any lock on the message (eqivalent to a select + without acquiring any lock on the message (equivalent to a select statement). @@ -1231,7 +1231,7 @@ Exceptions .. exception:: OperationalError Exception raised for errors that are related to the operation of the - database but are not necessarily under the control of the progammer. It is + database but are not necessarily under the control of the programmer. It is a subclass of DatabaseError. diff --git a/doc/src/releasenotes.rst b/doc/src/releasenotes.rst index d9960ec1..30d6f334 100644 --- a/doc/src/releasenotes.rst +++ b/doc/src/releasenotes.rst @@ -349,7 +349,7 @@ Version 6.3.1 (May 2018) - Ensure that a call to unregister a subscription only occurs if the subscription is still registered. - Ensure that before a statement is executed any buffers used for DML - returning statments are reset. + returning statements are reset. #) Ensure that behavior with cx_Oracle.__future__.dml_ret_array_val not set or False is the same as the behavior in cx_Oracle 6.2 @@ -548,7 +548,7 @@ Version 6.0.3 (November 2017) `__. - - Prevent use of unitialized data in certain cases (`issue 77 + - Prevent use of uninitialized data in certain cases (`issue 77 `__). - Attempting to ping a database earlier than 10g results in error "ORA-1010: invalid OCI operation", but that implies a response from the @@ -1252,7 +1252,7 @@ Version 4.3.2 (August 2007) NATIVE_FLOAT to allow specification of a variable of that specific type where desired. Thanks to D.R. Boxhoorn for pointing out the fact that this was not working properly when the arraysize was anything other than 1. -#) When calling connection.begin(), only create a new tranasction handle if +#) When calling connection.begin(), only create a new transaction handle if one is not already associated with the connection. Thanks to Andreas Mock for discovering this and for Amaury Forgeot d'Arc for diagnosing the problem and pointing the way to a solution. @@ -1399,7 +1399,7 @@ Version 4.1.1 (December 2005) can drastically affect performance of queries since this seems to be a common misunderstanding of first time users of cx_Oracle. #) Add a comment indicating that on HP-UX Itanium with Oracle 10g the library - ttsh10 must alos be linked against. Thanks to Bernard Delmee for the + ttsh10 must also be linked against. Thanks to Bernard Delmee for the information. diff --git a/doc/src/session_pool.rst b/doc/src/session_pool.rst index 387aa8bc..37f1cd76 100644 --- a/doc/src/session_pool.rst +++ b/doc/src/session_pool.rst @@ -50,7 +50,7 @@ SessionPool Object .. method:: SessionPool.close(force=False) Close the session pool now, rather than when the last reference to it is - released, which makes it unsable for further work. + released, which makes it unusable for further work. If any connections have been acquired and not released back to the pool this method will fail unless the force parameter is set to True. diff --git a/doc/src/soda.rst b/doc/src/soda.rst index 9c70e55c..03e850c1 100644 --- a/doc/src/soda.rst +++ b/doc/src/soda.rst @@ -228,7 +228,7 @@ SODA Collection Object .. attribute:: SodaCollection.metadata - This read-only attribute returns a dicationary containing the metadata that + This read-only attribute returns a dictionary containing the metadata that was used to create the collection. See this `collection metadata reference `__ From 6a5bf79532ec6e5446e1a832f6af8deb23453fd9 Mon Sep 17 00:00:00 2001 From: Anthony Tuininga Date: Wed, 24 Jul 2019 16:40:21 -0600 Subject: [PATCH 02/13] Add SODA to tutorial; tweak defaults used in samples. --- samples/SampleEnv.py | 4 +- ...cle-Database-Scripting-for-the-Future.html | 152 ++++++++++++++++-- samples/tutorial/db_config.py | 2 +- samples/tutorial/db_config.sql | 2 +- samples/tutorial/soda.py | 28 ++++ samples/tutorial/solutions/soda.py | 49 ++++++ samples/tutorial/sql/SetupSamples.sql | 13 ++ 7 files changed, 230 insertions(+), 20 deletions(-) create mode 100644 samples/tutorial/soda.py create mode 100644 samples/tutorial/solutions/soda.py diff --git a/samples/SampleEnv.py b/samples/SampleEnv.py index cec56c08..ed0ddd18 100644 --- a/samples/SampleEnv.py +++ b/samples/SampleEnv.py @@ -29,7 +29,7 @@ # [//]host_name[:port][/service_name][:server_type][/instance_name] # # Commonly just the host_name and service_name are needed -# e.g. "localhost/orclpdb" or "localhost/XE" +# e.g. "localhost/orclpdb1" or "localhost/XE" # # If using a tnsnames.ora file, the file can be in a default # location such as $ORACLE_HOME/network/admin/tnsnames.ora or @@ -53,7 +53,7 @@ DEFAULT_MAIN_USER = "pythondemo" DEFAULT_EDITION_USER = "pythoneditions" DEFAULT_EDITION_NAME = "python_e1" -DEFAULT_CONNECT_STRING = "localhost/orclpdb" +DEFAULT_CONNECT_STRING = "localhost/orclpdb1" # dictionary containing all parameters; these are acquired as needed by the # methods below (which should be used instead of consulting this dictionary diff --git a/samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html b/samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html index 31ea9b15..557ae6fc 100644 --- a/samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html +++ b/samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html @@ -92,6 +92,12 @@

Contents

  • 10.1 Message passing with Oracle Advanced Queuing
    • +
  • 11. Simple Oracle Document Access (SODA) +
      +
    • 11.1 Inserting JSON Documents
      • +
    • 11.2 Searching SODA Documents
      • +
    +
  • Summary
  • Appendix: Python Primer
    • @@ -100,24 +106,27 @@

    Contents

    Preface

    -

    If you are running this tutorial in your own environment, install the following required software:

    +

    If you are running this tutorial in your own environment, install the required software:

      -
    1. Python (3.6 preferred but 2.7 should work)
      2. -
    2. cx_Oracle (version 7.2 preferred but 6.3 or later should work, except for the section on Advanced Queuing which requires version 7.2 or later) and Oracle Instant Client Package - Basic (version 19.3 preferred but 18.3 or 12.2 should also work) +

    3. Python. Version 3.6 is preferred.

      4. +

    4. cx_Oracle version 7.2 and the Oracle Client libraries.

      5. -
    5. Oracle Instant Client Package - SQL*Plus.
      6. + +

    6. SQL*Plus such as from the Oracle Instant Client SQL*Plus Package.

    +

    The Advanced Queuing section requires Oracle client 12.2 or later. The SODA section requires Oracle client 18.5, or later, and Oracle Database 18 or later.

    +

    To create the schema run:

    -sqlplus sys/yoursyspassword@localhost/orclpdb as sysdba @sql/SetupSamples
+sqlplus sys/yoursyspassword@localhost/orclpdb1 as sysdba @sql/SetupSamples

    Connection Information

    @@ -130,11 +139,11 @@

    Connection Information

    The username is "pythonhol" with - the password "welcome". The connect string is "localhost/orclpdb". + the password "welcome". The connect string is "localhost/orclpdb1". See sql/SampleEnv.sql.

    It is easist to have a local pluggable database with the service - 'orclpdb' configured. If your database is not local, or has a + 'orclpdb1' configured. If your database is not local, or has a different service, you will need to modify the connection information in db_config.py and db_config.sql.

    The following sections may need adjusting, depending on how you @@ -174,16 +183,16 @@

    1.1 Review the connection credentials

     user = "pythonhol"
 pw = "welcome"
-dsn = "localhost/orclpdb"
+dsn = "localhost/orclpdb1"
    db_config.sql 
     def user = "pythonhol"
 def pw = "welcome"
-def connect_string = "localhost/orclpdb"
+def connect_string = "localhost/orclpdb1"
    -

    By default they connect to the 'orclpdb' database service on the same machine as Python. You can modify the values in both files to match the connection information for your environment.

    +

    By default they connect to the 'orclpdb1' database service on the same machine as Python. You can modify the values in both files to match the connection information for your environment.

    @@ -207,7 +216,7 @@

    1.2 Creating a basic connection

    the db_config.py module. In this case, Oracle's Easy Connect connection string syntax is used. It consists of the hostname of your machine, localhost, and the database service name - orclpdb.

    + orclpdb1.

    Open a command terminal and change to the tutorial directory:

    @@ -1128,7 +1137,7 @@

    2.5 More DRCP investigation

    In a terminal window, start SQL*Plus using the lab credentials and connection string, such as:

    -sqlplus pythonhol/welcome@localhost/orclpdb
+sqlplus pythonhol/welcome@localhost/orclpdb1

    Use the SQL*Plus DESCRIBE command to look at the SDO definition:

    @@ -1661,6 +1670,9 @@

    6.1 Basic output type handler

  • 7. LOBs

    +

    Oracle Database "LOB" long objects can be streamed using a LOB + locator, or worked with directly as strings or bytes.

    +