HackBase/python-cx_Oracle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve documentation.

Browse Source
This commit is contained in:
Anthony Tuininga 2017-07-27 20:46:21 -06:00
parent 7edc0ddd83
commit 4c4513f476
3 changed files with 80 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
README.md
View File

@ -1,31 +1,17 @@
# 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.
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 [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].
cx_Oracle is licensed under a BSD license which you can find [here][3].
cx_Oracle has been tested with Python version 2.7, and with versions 3.4 and
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 client libraries,
allowing connection to multiple Oracle Database versions. Oracle's standard
client-server version interoperability allows connection to both older and
newer databases, for example Oracle 11.2 client libraries can connect to Oracle
Database 10.2 or later.
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.
newer databases, for example Oracle 12.2 client libraries can connect to Oracle
Database 11.2 or later.
## Help
@ -38,35 +24,33 @@ See the [cx_Oracle Documentation][2] and [Release Notes][14].
## Installation
The simplest way to install cx_Oracle 6 Beta is with pip:
See [cx_Oracle Installation][15] for detailed instructions.
python -m pip install cx_Oracle --pre
- The simplest way to install cx_Oracle 6 RC2 is with pip:
If a binary wheel package is not available on [PyPI][6] for your
platform, the source package will be used.
`python -m pip install cx_Oracle --pre`
If you prefer, the source package can be downloaded manually from [PyPI][6] and
extracted, after which the following commands should be run:
If a binary wheel package is not available on [PyPI][6] for your platform, the
source package will be used.
python setup.py build
python setup.py install
- After cx_Oracle is installed, Oracle client libraries must also be installed
and configured. These can be from Oracle Instant Client, from a local Oracle
Database, or from a full Oracle Client installation.
Note that if you download a source zip file directly from GitHub that
you will also need to download an [ODPI-C][10] source zip file and
extract it inside a directory called "odpi".
After cx_Oracle is installed, Oracle client libraries must also be
installed and configured. If you need the libraries, you can download
and unzip the [Oracle Instant Client][4] 'Basic' package for your
platform and set PATH, LD_LIBRARY_PATH, or similar platform-specific
library path loading environment. See the
[installation notes for ODPI-C][13] for help with installing and configuring an
Oracle client.
If you need the libraries, download and unzip the [Oracle Instant Client][4]
'Basic' package for your platform and set PATH, LD_LIBRARY_PATH, or similar
platform-specific library path loading environment. See
the [installation notes for ODPI-C][13] for help.
Versions 11.2, 12.1 and 12.2 of the Oracle Client libraries on Linux,
Windows and macOS are supported. Users have also reported success
with other platforms.
Note that if you download a source zip file directly from GitHub that
you will also need to download an [ODPI-C][10] source zip file and
extract it inside the directory called "odpi".
## Usage Example
@ -176,6 +160,13 @@ the modules in the [cx_PyOracleLib][8] projects.
- 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.
[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
@ -190,3 +181,4 @@ the modules in the [cx_PyOracleLib][8] projects.
[12]: https://github.com/oracle/python-cx_Oracle/tree/master/samples
[13]: https://oracle.github.io/odpi/doc/installation.html
[14]: http://cx-oracle.readthedocs.io/en/latest/releasenotes.html
[15]: http://cx-oracle.readthedocs.io/en/latest/installation.html

13
doc/README.md Normal file
View File

@ -0,0 +1,13 @@
The generated cx_Oracle documentation is at http://cx-oracle.readthedocs.io/
This directory contains the documentation source. It is written using reST
(re-Structured Text) format source files which are processed using Sphinx and
turned into HTML, PDF or ePub documents. If you wish to build these yourself,
you need to install Sphinx. Sphinx is available on many Linux distributions as a
pre-built package. You can also install Sphinx on all platforms using the Python
package manager "pip". For more information on Sphinx, please visit this page:
http://www.sphinx-doc.org
Once Sphinx is installed, the supplied Makefile can be used to build the
different targets.

39
doc/src/installation.rst
View File

@ -19,6 +19,8 @@ After cx_Oracle has been installed, you must also `Install Oracle Client`_, if
that has not been done already. Oracle Client versions 12.2, 12.1 and 11.2
are supported.
Note installation has changed from cx_Oracle 5. When using Oracle
Instant Client, you should not set ``ORACLE_HOME``.
Install Using Pip
=================
@ -30,9 +32,13 @@ on all platforms is::
This will download and install a pre-compiled binary matching your platform
and architecture automatically, if one is available. Pre-compiled binaries are
available for Windows and Linux. If a pre-compiled binary is not
available, the source will be downloaded, compiled and the resulting binary
installed.
available for Windows and Linux.
If a pre-compiled binary is not available, the source will be
downloaded, compiled and the resulting binary installed. On macOS,
make you are not using the bundled Python - use `Homebrew
<https://brew.sh>`__ or `Python.org
<https://www.python.org/downloads>`__ instead.
Install Using GitHub
@ -46,6 +52,21 @@ In order to install using the source on GitHub, use the following commands::
git submodule update
python setup.py install
Note that if you download a source zip file directly from GitHub then
you will also need to download an `ODPI-C
<https://github.com/oracle/odpi>`__ source zip file and extract it
inside the directory called "odpi".
Install Using Source from PyPI
==============================
The source package can be downloaded manually from
`PyPI <https://pypi.python.org/pypi/cx_Oracle>`__ and extracted, after
which the following commands should be run:
python setup.py build
python setup.py install
Install Using RPM
=================
@ -79,6 +100,14 @@ index.html>`__. Only the "Basic" or "Basic Light" package is required. Oracle
Client libraries are also available in any Oracle Database installation or
full Oracle Client installation.
On Windows, `Microsoft Windows Redistributables
<https://oracle.github.io/odpi/doc/installation.html#windows>`__
matching the version of the Oracle client libraries need to be
installed.
Oracle Database
===============
Oracle Client libraries allow connection to older and newer databases.
In summary, Oracle Client 12.2 can connect to Oracle Database 11.2 or
greater. Oracle Client 12.1 can connect to Oracle Database 10.2 or
@ -146,7 +175,6 @@ If installation fails:
subdirectory called "odpi" containing files. If missing, review the
section on `Install Using GitHub`_.
If importing cx_Oracle fails:
- Do you get the error "``DPI-1047: Oracle Client library cannot be
@ -160,3 +188,6 @@ If importing cx_Oracle fails:
<https://oracle.github.io/odpi/doc/installation.html#windows>`__ have been
installed.
- If you have both Python 2 and 3 installed, make sure you are
using the correct python and pip (or python3 and pip3)
executables.