diff --git a/README.md b/README.md new file mode 100644 index 0000000..1d2842a --- /dev/null +++ b/README.md @@ -0,0 +1,86 @@ +#Open Source Python/Oracle Utility - cx_Oracle + +cx_Oracle is a Python extension module that enables access to Oracle Database +and conforms to the Python database API 2.0 specifications with a considerable +number of additions and a couple of exclusions. The time data type is not +supported by Oracle and is therefore not implemented. The method +cursor.nextset() is not implemented either as the DB API specification assumes +an implementation of cursors that does not fit well with Oracle's +implementation of cursors and implicit results. See the method +cursor.getimplicitresults() for more information. + +See [PEP 249][1] for more information on the Python database API specification. +See the [documentation][2] for a complete description of the module's +capabilities. + +cx_Oracle is licensed under a BSD license which you can find [here][3]. + +Please note that an Oracle client (or server) installation is required in order +to use cx_Oracle. If you do not require the tools that come with a full client +installation, it is recommended to install the [Instant Client][4]. +which is far easier to install. + +For feedback or patches, contact Anthony Tuininga at +anthony.tuininga@gmail.com. For help or to ask questions, please use the +[mailing list][5]. + + +#Installation + +Binaries for some platforms and Oracle versions are available at +[PyPI][6]. If you prefer to build your own you can use this command + + pip install cx_Oracle + +which will download the source package, build and install it. Otherwise, you +can download the source package directly from PyPI, extract it and run these +commands instead + + python setup.py build + python setup.py install + +This module has been built with Oracle client 11.2, 12.1 and 12.2 on Linux and +Windows. Others have reported success with other platforms such as macOS. + +See BUILD.txt for additional information. + + +#Usage Example + + +```python +from __future__ import print_function # needed for Python 2.x + +import cx_Oracle + +# connect via SQL*Net string or by each segment in a separate argument +#connection = cx_Oracle.connect("user/password@TNS") +connection = cx_Oracle.connect("user", "password", "TNS") + +cursor = connection.cursor() +cursor.execute(""" + select Col1, Col2, Col3 + from SomeTable + where Col4 = :arg_1 + and Col5 between :arg_2 and :arg_3""", + arg_1 = "VALUE", + arg_2 = 5, + arg_3 = 15) +for column_1, column_2, column_3 in cursor: + print("Values:", column_1, column_2, column_3) +``` + + +For more examples, please see the test suite in the test directory and the +samples in the samples directory. You can also look at the scripts in the +[cx_OracleTools][7] and the modules in the [cx_PyOracleLib][8] projects. + +[1]: https://www.python.org/dev/peps/pep-0249 +[2]: http://cx-oracle.readthedocs.io +[3]: http://cx-oracle.readthedocs.io/en/latest/license.html +[4]: http://www.oracle.com/technetwork/database/features/instant-client/index.html +[5]: http://lists.sourceforge.net/lists/listinfo/cx-oracle-users +[6]: https://pypi.python.org/pypi/cx_Oracle +[7]: http://cx-oracletools.sourceforge.net +[8]: http://cx-pyoraclelib.sourceforge.net + diff --git a/README.txt b/README.txt index 7e9a73f..46124e2 100644 --- a/README.txt +++ b/README.txt @@ -1,80 +1,5 @@ -Open Source Python/Oracle Utility - cx_Oracle ---------------------------------------------- -cx_Oracle is a Python extension module that enables access to Oracle Database -and conforms to the Python database API 2.0 specifications with a considerable -number of additions and a couple of exclusions. The time data type is not -supported by Oracle and is therefore not implemented. The method -cursor.nextset() is not implemented either as the DB API specification assumes -an implementation of cursors that does not fit well with Oracle's -implementation of cursors and implicit results. See the method -cursor.getimplicitresults() for more information. +Please see the cx_Oracle home page for links to documentation, source, build +and installation instructions: -See http://www.python.org/topics/database/DatabaseAPI-2.0.html for more -information on the Python database API specification. See the documentation at -http://cx-oracle.readthedocs.io for a complete description of the module's -capabilities. - -cx_Oracle is licensed under a BSD license which you can find at -http://cx-oracle.readthedocs.io/en/latest/license.html. - -Please note that an Oracle client (or server) installation is required in order -to use cx_Oracle. If you do not require the tools that come with a full client -installation, it is recommended to install the Instant Client -(http://www.oracle.com/technetwork/database/features/instant-client/index.html) -which is far easier to install. - -For feedback or patches, contact Anthony Tuininga at -anthony.tuininga@gmail.com. For help or to ask questions, please use the -mailing list at http://lists.sourceforge.net/lists/listinfo/cx-oracle-users. - - -Installation ------------- -Binaries for some platforms and Oracle versions are available at -https://pypi.python.org/pypi/cx_Oracle. If you prefer to build your own you -can use this command - - pip install cx_Oracle - -which will download the source package, build and install it. Otherwise, you -can download the source package directly from PyPI, extract it and run these -commands instead - - python setup.py build - python setup.py install - -This module has been built with Oracle client 11.2, 12.1 and 12.2 on Linux and -Windows. Others have reported success with other platforms such as macOS. - -See BUILD.txt for additional information. - - -Usage Example -------------- - -from __future__ import print_function # needed for Python 2.x - -import cx_Oracle - -# connect via SQL*Net string or by each segment in a separate argument -#connection = cx_Oracle.connect("user/password@TNS") -connection = cx_Oracle.connect("user", "password", "TNS") - -cursor = connection.cursor() -cursor.execute(""" - select Col1, Col2, Col3 - from SomeTable - where Col4 = :arg_1 - and Col5 between :arg_2 and :arg_3""", - arg_1 = "VALUE", - arg_2 = 5, - arg_3 = 15) -for column_1, column_2, column_3 in cursor: - print("Values:", column_1, column_2, column_3) - - -For more examples, please see the test suite in the test directory and the -samples in the samples directory. You can also look at the scripts in the -cx_OracleTools (http://cx-oracletools.sourceforge.net) and the modules in the -cx_PyOracleLib (http://cx-pyoraclelib.sourceforge.net) projects. +https://oracle.github.io/python-cx_Oracle/index.html diff --git a/doc/src/index.rst b/doc/src/index.rst index 96dc727..93ad9e1 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -2,7 +2,7 @@ Welcome to cx_Oracle's documentation! ===================================== -**cx_Oracle** is a module that enables access to Oracle databases and conforms +**cx_Oracle** is a module that enables access to Oracle Database and conforms to the Python database API specification. This module is currently built against Oracle 11.2 and 12.1 and works for both Python 2.x and 3.x. diff --git a/setup.py b/setup.py index 4b46e26..b6f60ce 100644 --- a/setup.py +++ b/setup.py @@ -384,8 +384,8 @@ setup( cmdclass = commandClasses, options = dict(bdist_rpm = dict(doc_files = docFiles)), long_description = \ - "Python interface to Oracle conforming to the Python DB API 2.0 " - "specification.\n" + "Python interface to Oracle Database conforming to the Python DB " + "API 2.0 specification.\n" "See http://www.python.org/topics/database/DatabaseAPI-2.0.html.", author = "Anthony Tuininga", author_email = "anthony.tuininga@gmail.com",