From 552fcfb48e6aab2e1cd71aea8c26b992f51186f6 Mon Sep 17 00:00:00 2001 From: Anthony Tuininga Date: Mon, 5 Mar 2018 16:34:53 -0700 Subject: [PATCH] Bump license year; simplify README and avoid duplication. --- LICENSE.txt | 2 +- README.md | 172 +++++---------------------------------- doc/src/installation.rst | 53 ++++++++---- doc/src/releasenotes.rst | 3 + doc/src/whatsnew.rst | 2 + 5 files changed, 63 insertions(+), 169 deletions(-) diff --git a/LICENSE.txt b/LICENSE.txt index 3b5669f..eb62ea9 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ LICENSE AGREEMENT FOR CX_ORACLE -Copyright 2016, 2017, Oracle and/or its affiliates. All rights reserved. +Copyright 2016, 2018, Oracle and/or its affiliates. All rights reserved. Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved. diff --git a/README.md b/README.md index 0835010..46d5171 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ -# Python cx_Oracle interface to Oracle Database +# cx_Oracle version 6.2 -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. - -cx_Oracle is licensed under a BSD license which you can find [here][3]. +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 6 has been tested with Python version 2.7, and with versions 3.4 and higher. You can use cx_Oracle with Oracle 11.2, 12.1 and 12.2 @@ -13,181 +14,46 @@ interoperability allows connection to both older and newer databases, for example Oracle 12.2 client libraries can connect to Oracle Database 11.2. -## Getting Started - -Install Python from [python.org][4]. - -Install cx_Oracle using [Quick Start cx_Oracle Installation][6]. - -Download cx_Oracle [samples][12] or create a script like the one -below. - -Locate your Oracle Database username and password, and the database -connection string. The connection string is commonly of the format -`hostname/servicename`, using the hostname where the database is -running, and the service name of the Oracle Database instance. - -Substitute your username, password and connection string in the code. -For downloaded examples, put these in [`SampleEnv.py`][13] and -[`SampleEnv.sql`][10], and then follow [`sample/README`][16] to create -the cx_Oracle sample schema. SQL scripts to create Oracle Database's -common sample schemas can be found at -[github.com/oracle/db-sample-schemas][17]. - -Run the Python script, for example: - -``` -python myscript.py -``` - -### Sample cx_Oracle Script - -```python -# myscript.py - -from __future__ import print_function - -import cx_Oracle - -# Connect as user "hr" with password "welcome" to the "oraclepdb" service running on this computer. -connection = cx_Oracle.connect("hr", "welcome", "localhost/orclpdb") - -cursor = connection.cursor() -cursor.execute(""" - SELECT first_name, last_name - FROM employees - WHERE department_id = :did AND employee_id > :eid""", - did = 50, - eid = 190) -for fname, lname in cursor: -print("Values:", fname, lname) -``` - ## Installation See [cx_Oracle Installation][15]. -## Examples - -See the [samples][12] directory and the [test suite][11]. You can also -look at the scripts in [cx_OracleTools][7] and the modules in -[cx_PyOracleLib][8]. - ## Documentation -See the [cx_Oracle Documentation][2]. +See the [cx_Oracle Documentation][2] and [Release Notes][14]. -## Changes +## Samples -See [What's New][18] and the [Release Notes][14]. - -## Tests - -See the [test suite][11]. +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]. ## Help Issues and questions can be raised with the cx_Oracle community on [GitHub][9] or on the [mailing list][5]. -## Features +## Tests -- Easily installed from PyPI. +See [/test][11]. -- Support for Python 2 and 3. +## Contributing -- Support for Oracle Client 11.2, 12.1 and 12.2. Oracle's standard - cross-version interoperability, allows easy upgrades and - connectivity to different Oracle Database versions. +See [CONTRIBUTING](https://github.com/oracle/python-cx_Oracle/blob/master/CONTRIBUTING.md) -- Connect to Oracle Database 9.2, 10, 11 or 12 (depending on the - Oracle Client version used). +## License -- SQL and PL/SQL Execution. The underlying Oracle Client libraries - have significant optimizations including compressed fetch, - pre-fetching, client and server result set caching, and statement - caching with auto-tuning. - -- Full use of Oracle Network Service infrastructure, including - encrypted network traffic and security features. - -- Extensive Oracle data type support, including large object support (CLOB - and BLOB). - -- Direct binding to SQL objects. One great use case is binding Python - objects to Oracle Spatial SDO objects. - -- Array operations for efficient INSERT and UPDATEs. - -- Array row counts and batch error handling for array operations. - -- Fetching of large result sets. - -- REF CURSOR support. - -- Support for scrollable cursors. Go back and forth through your query - results. - -- Fetch PL/SQL Implicit Results. Easily return query results from - PL/SQL. - -- Row Prefetching. Efficient use of the network. - -- Client Result Caching. Improve performance of frequently executed - look-up statements. - -- Support for Advanced Queuing. Use database notifications to build - micro-service applications. - -- Continuous Query Notification. Get notified when data changes. - -- Support for Edition Based Redefinition. Easily switch applications - to use updated PL/SQL logic. - -- Support for setting application context during the creation of a - connection, making application metadata more accessible to the - database, including in LOGON triggers. - -- End-to-end monitoring and tracing. - -- Transaction Management. - -- Session Pooling. - -- Database Resident Connection Pooling (DRCP). - -- Privileged Connections. - -- External Authentication. - -- Database startup and shutdown. - -- Sharded Databases - -- Oracle Database High Availability Features, such as FAN notifications and Transaction Guard support. - -**DB API specification 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. +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/master/LICENSE.txt -[4]: https://www.python.org/downloads/ [5]: http://lists.sourceforge.net/lists/listinfo/cx-oracle-users -[6]: http://cx-oracle.readthedocs.io/en/latest/installation.html#quick-start-cx-oracle-installation +[6]: https://github.com/oracle/python-cx_Oracle/tree/master/samples/tutorial [7]: http://cx-oracletools.sourceforge.net [8]: http://cx-pyoraclelib.sourceforge.net [9]: https://github.com/oracle/python-cx_Oracle/issues -[10]: https://github.com/oracle/python-cx_Oracle/blob/master/samples/sql/SampleEnv.sql [11]: https://github.com/oracle/python-cx_Oracle/tree/master/test [12]: https://github.com/oracle/python-cx_Oracle/tree/master/samples -[13]: https://github.com/oracle/python-cx_Oracle/tree/master/samples/SampleEnv.py [14]: http://cx-oracle.readthedocs.io/en/latest/releasenotes.html [15]: http://cx-oracle.readthedocs.io/en/latest/installation.html -[16]: https://github.com/oracle/python-cx_Oracle/tree/master/samples/README.md -[17]: https://github.com/oracle/db-sample-schemas -[18]: http://cx-oracle.readthedocs.io/en/latest/whatsnew.html diff --git a/doc/src/installation.rst b/doc/src/installation.rst index 0fe4e63..1f94cc3 100644 --- a/doc/src/installation.rst +++ b/doc/src/installation.rst @@ -69,25 +69,48 @@ Quick Start cx_Oracle Installation 10.2 or greater. Version 11.2 client libraries can connect to Oracle Database 9.2 or greater. -- After installation, your Python applications will be able to connect - to your database. The database can be on the same machine as - Python, or on a remote machine. cx_Oracle does not install or - create a database. + The database abstraction layer in cx_Oracle is `ODPI-C + `__, which means that the `ODPI-C + installation instructions + `__ can be useful + to review. - You will need to know user credentials and the connection string for - the database. +- Create a script like the one below:: - You can learn how to use cx_Oracle from the API documentation and - `samples - `__. + # myscript.py -If you run into trouble, check out the section on `Troubleshooting`_. + from __future__ import print_function -The database abstraction layer in cx_Oracle is `ODPI-C -`__, which means that the `ODPI-C -installation instructions -`__ can be useful -to review. + import cx_Oracle + + # Connect as user "hr" with password "welcome" to the "oraclepdb" service running on this computer. + connection = cx_Oracle.connect("hr", "welcome", "localhost/orclpdb") + + cursor = connection.cursor() + cursor.execute(""" + SELECT first_name, last_name + FROM employees + WHERE department_id = :did AND employee_id > :eid""", + did = 50, + eid = 190) + for fname, lname in cursor: + print("Values:", fname, lname) + + Locate your Oracle Database username and password, and the database + connection string. The connection string is commonly of the format + ``hostname/servicename``, using the hostname where the database is + running, and the service name of the Oracle Database instance. + + Substitute your username, password and connection string in the + code. Run the Python script, for example:: + + python myscript.py + +You can learn how to use cx_Oracle from the :ref:`API documentation ` +and `samples +`__. + +If you run into installation trouble, check out the section on `Troubleshooting`_. Oracle Client and Oracle Database Interoperability diff --git a/doc/src/releasenotes.rst b/doc/src/releasenotes.rst index e4811b7..efc8f2b 100644 --- a/doc/src/releasenotes.rst +++ b/doc/src/releasenotes.rst @@ -202,6 +202,9 @@ Version 6.0.1 (August 2017) Version 6.0 (August 2017) ------------------------- +See :ref:`What's New ` for a summary of the changes between +cx_Oracle 5.3 and cx_Oracle 6.0. + #) Update to `ODPI-C 2.0 `__. diff --git a/doc/src/whatsnew.rst b/doc/src/whatsnew.rst index 72759d4..b03dbfa 100644 --- a/doc/src/whatsnew.rst +++ b/doc/src/whatsnew.rst @@ -4,6 +4,8 @@ What's New ********** +.. _whatsnew60: + cx_Oracle 6.0 =============