Using Python with Caché
The Caché Python Binding
The Caché Python binding provides a simple, direct way to manipulate Caché objects from within a Python application. It allows Python programs to establish a connection to a database on Caché, create and open objects in the database, manipulate object properties, save objects, run methods on objects, and run queries. All Caché datatypes are supported.
The Python binding offers complete support for object database persistence, including concurrency and transaction control. In addition, there is a sophisticated data caching scheme to minimize network traffic when the Caché server and the Python applications are located on separate machines.
This document assumes a prior understanding of Python and the standard Python modules. Caché does not include a Python interpreter or development environment.
Python Binding Architecture
The Caché Python binding gives Python applications a way to interoperate with objects contained within a Caché server. The Python binding consists of the following components:
The Caché Object Server
a high performance server process that manages communication between Python clients and a Caché database server. It communicates using standard networking protocols (TCP/IP), and can run on any platform supported by Caché. The Caché Object Server is used by all Caché language bindings, including Python, Perl, C++, Java, JDBC, and ODBC.
The basic mechanism works as follows:
You define one or more classes within Caché. These classes can represent persistent objects stored within the Caché database or transient objects that run within a Caché server.
At runtime, your Python application connects to a Caché server. It can then access instances of objects within the Caché server. Caché automatically manages all communications as well as client-side data caching. The runtime architecture consists of the following:
A Caché database server (or servers).
A Python application. At runtime, the Python application connects to Caché using either an object connection interface or a standard ODBC interface. All communications between the Python application and the Caché server use the TCP/IP protocol.
Here are examples of a few basic functions that make up the core of the Python binding:
conn = intersys.pythonbind.connection()
database = intersys.pythonbind.database(conn)
is your logical connection to the namespace specified in url
person = database.openid("Sample.Person",str(id),-1,-1)
person = database.create_new("Sample.Person", None)
person.set("Name","Doe, Joe A")
name = person.get("Name")
answer = person.run_obj_method("Addition",[17,20])
id = person.run_obj_method("%Id",)
sqlstring ="SELECT ID, Name, DOB, SSN \
FROM SAMPLE.PERSON \
WHERE Name %STARTSWITH ?"
query = intersys.pythonbind.query(database)
cols = query.fetch([None])
if len(cols) == 0: break
Installation and Configuration
Python Client Requirements
Caché provides client-side Python support through the intersys.pythonbind
module, which implements the connection and caching mechanisms required to communicate with a Caché server.
This module requires the following environment:
Python version 2.7 or Python 3.0+. For Windows, Intersystems supports only the ActiveState distribution, ActivePython© (www.activestate.com
A C++ compiler to generate the Python C extension. On Windows, you need Visual Studio .NET 2008 or higher (required by the ActiveState distribution). On UNIX®, you need GCC.
The bitness of both your Python distribution and your compiler must match the bitness of Caché: 64-bit systems require the 64-bit versions of Python and compiler, and 32-bit systems require the 32-bit versions of Python and compiler.
On RedHat Linux, the python-devel
package must be installed in order to compile the python sample.
Set up your environment variables to support C compilation and linking, as described in the following sections.
Make sure your path and environment is setup to run the Microsoft C/C++ compiler. Follow the Microsoft instructions. For example from the command line, run:
for 64-bit systems. These files set up the path and environment variables for using the Microsoft C/C++ compiler. Please read your Microsoft documentation to determine the location of these .bat
files, since the location varies depending on the version of Visual Studio you are using.
The following prompt is displayed:
enter directory where you installed Cache'
At the prompt, supply the location of <cachesys>
. For example:
The resulting lib and include paths will be displayed:
Do not run test programs from <cachesys>\dev\python
or the test program will not be able to find the pythonbind module. The python path is relative and you will pick up files from the intersys subdirectory instead.
Caché Server Configuration
Very little configuration is required to use a Python client with a Caché server. The Python sample programs provided with Caché should work with no change following a default Caché installation. This section describes the server settings that are relevant to Python and how to change them.
Every Python client that wishes to connect to a Caché server needs the following information:
A URL that provides the server IP address, port number, and Caché namespace.
By default, the Python sample programs use the following connection information:
Check the following points if you have any problems:
Make sure that the Caché server is installed and running.
Make sure that you know the IP address of the machine on which the Caché server is running. The Python sample programs use "localhost"
. If you want a sample program to default to a different system you will need to change the connection string in the code.
Make sure that you know the TCP/IP port number on which the Caché server is listening. The Python sample programs use "1972"
. If you want a sample program to default to a different port, you will need change the number in the sample code.
Make sure that you have a valid username and password to use to establish a connection. (You can manage usernames and passwords using the Caché Management Portal). The Python sample programs use the administrator username "_SYSTEM
" and the default password "SYS"
. Typically, you will change the default password after installing the server. If you want a sample program to default to a different username and password, you will need to change the sample code.
Make sure that your connection URL includes a valid Caché namespace. This should be the namespace containing the classes and data your program uses. The Python samples connect to the SAMPLES
namespace, which is pre-installed with Caché.
The standard Caché installation contains a set of sample programs that demonstrate the use of the Caché Python binding. These samples are located in:
The following sample programs are provided:
All of these applications use classes from the Sample
package in the SAMPLES
namespace (accessible in Caché Studio).
The sample programs are controlled by various switches that can be entered as arguments to the program on the command line. A default value is supplied if you don't enter an argument.
For example, CPTest2.py
accepts the following optional arguments:
argument would be specified as follows:
python CPTest2.py -user _MYUSERNAME
python CPTest7.py -query A
This query will list all Sample.Person
records containing names that start with the letter A.