Bump license year; simplify README and avoid duplication.

Author: anthony-tuininga

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.
 

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
-
-- Easily installed from PyPI.
-
-- Support for Python 2 and 3.
-
-- 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.
-
-- Connect to Oracle Database 9.2, 10, 11 or 12 (depending on the
-  Oracle Client version used).
-
-- 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.
+## Tests
 
-- External Authentication.
+See [/test][11].
 
-- Database startup and shutdown.
+## Contributing
 
-- Sharded Databases
+See [CONTRIBUTING](https://github.com/oracle/python-cx_Oracle/blob/master/CONTRIBUTING.md)
 
-- Oracle Database High Availability Features, such as FAN notifications and Transaction Guard support.
+## License
 
-**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

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
+  <https://github.com/oracle/odpi>`__, which means that the `ODPI-C
+  installation instructions
+  <https://oracle.github.io/odpi/doc/installation.html>`__ 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
-  <https://github.com/oracle/python-cx_Oracle/blob/master/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
-<https://github.com/oracle/odpi>`__, which means that the `ODPI-C
-installation instructions
-<https://oracle.github.io/odpi/doc/installation.html>`__ 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 <module>`
+and `samples
+<https://github.com/oracle/python-cx_Oracle/blob/master/samples>`__.
+
+If you run into installation trouble, check out the section on `Troubleshooting`_.
 
 
 Oracle Client and Oracle Database Interoperability

doc/src/releasenotes.rst

@@ -202,6 +202,9 @@ Version 6.0.1 (August 2017)
 Version 6.0 (August 2017)
 -------------------------
 
+See :ref:`What's New <whatsnew60>` for a summary of the changes between
+cx_Oracle 5.3 and cx_Oracle 6.0.
+
 #)  Update to `ODPI-C 2.0 <https://oracle.github.io/odpi/doc/releasenotes.html
     #version-2-0-august-14-2017>`__.
 

doc/src/whatsnew.rst

@@ -4,6 +4,8 @@
 What's New
 **********
 
+.. _whatsnew60:
+
 cx_Oracle 6.0
 =============