This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!
Project Description

Installing a Oracle driver on a machine is sometime a pain, or even impossible. Furthermore you may want to distribute self contained scripts that access Oracle without having to ask for additional software installation. Finally, you may want to automate scripts that should run with SQL*Plus.

sqlplus_commando is a pure Python Oracle driver that calls sqlplus on the command line. It was designed so that you may use it by dropping its module in your source tree or even copy its classes in your own source code.

Installation

To install sqlplus_commando, you may use one of the following methods:

  • Extract classes SqlplusCommando, OracleResultParser and OracleErrorParser from tarball (in file sqlplus_commando/sqlplus_commando.py) and put it in your own source code.
  • Drop its module (file sqlplus_commando/sqlplus_commando.py in the tarball) in your source directory.
  • Install it using PIP, typing pip install sqlplus_commando.
  • Install from tarball typing python setup.py install.

The Apache license grants you a right to use this driver in any of your project (even commercial) provided that you mention that you are using sqlplus_commando in your copyright notice.

Usage

You can use this driver in your code just like so:

from sqlplus_commando import SqlplusCommando

sqlplus = SqlplusCommando(hostname='localhost', database='test',
                          username='test', password='test')
result = sqlplus.run_query("SELECT 42 AS response, 'This is a test' AS question FROM DUAL;")
print result

When query returns nothing (after an INSERT for instance), method run_query() will return an empty tuple (). If query returns a result set, this will be a tuple of dictionaries. For instance, previous sample code could print:

({'RESPONSE': 42, 'QUESTION': 'This is a test'},)

Instead of running a query you may run a script as follows:

result = sqlplus.run_script('my_script.sql')

Parameters

You can have values such as %(foo)s in your query that will be replaced with corresponding value of the parameters dictionary. For instance:

from sqlplus_commando import SqlplusCommando

sqlplus = SqlplusCommando(hostname='localhost', database='test',
                          username='test', password='test')
parameters = {'name': 'Reglisse'}
result = sqlplus.run_query(query="SELECT * FROM animals WHERE name=%(name)s",
                           parameters=parameters)
print result

You may not provide parameters running a script. To do so, call run_query() with parameters passing query open('my_script.sql').read().

Result set types

sqlplus_commando performs auto casting before returning result sets. As it calls sqlplus on command line, every value in the result set is a string. For convenience, it casts integers, floats, dates and NULL into native Python types.

There are situations where this might not be accurate. For instance, if a column is of SQL type VARCHAR(10) and contain phone numbers, all its values will be casted to Python integers. It should not because phone numbers can start with 0 that would be lost while casted into an integer.

To avoid this, you may pass cast=False when calling run_query() or run_script(), like so:

from sqlplus_commando import SqlplusCommando

sqlplus = SqlplusCommando(hostname='localhost', database='test',
                          username='test', password='test')
result = sqlplus.run_query("SELECT phone FROM users WHERE name='bob')", cast=False)
print result

You may also disable casting when instantiating the driver, passing cast=False to the constructor. This casting configuration will apply on all calls to run_query() or run_script() except if you pass a different value while calling these methods.

Error management

While running a query or a script with sqlplus, you must add following SQL commands so that the return value is différent from 0 if an error occurs:

WHENEVER SQLERROR EXIT SQL.SQLCODE;
WHENEVER OSERROR EXIT 9;

These lines are added before queries or scripts to run to avoid having to parse the result for error messages. Nevertheless, there are some cases when these lines won’t help for error detection. For instance, following query:

BAD SQL QUERY;

This won’t result in an error in sqlplus and we must parse the result for the error string SP2-0734: unknown command. This is done by default, but you may avoid this passing parameter check_unknown_command=False while calling functions run_query or run_script.

Furthermore, a compilation error will result in a warning, thus it is often necessary to check for warnings in sqlplus output. This is done by default and will result in an exception, except if you pass check_warning=False calling run_query or run_script.

Note

This module is not intended to replace an genuine Oracle driver that you SHOULD use if you can install it on the target machine.

Enjoy!

Release History

Release History

0.4.2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.3.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.6

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sqlplus_commando-0.4.2.tar.gz (8.9 kB) Copy SHA256 Checksum SHA256 Source Aug 17, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting