Skip to main content
Previous section   Next section

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 intersys.pythonbind module — a Python C extension that provides your Python application with transparent connectivity to the objects stored in the Caché database.

  • 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).

    • The Python interpreter (see Python Client Requirements).

    • 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.

Quick Start

Here are examples of a few basic functions that make up the core of the Python binding:

  • Create a connection and get a database

       conn = intersys.pythonbind.connection()
       conn.connect_now(url,user,password, None)
       database = intersys.pythonbind.database(conn)
    Copy code to clipboard

    database is your logical connection to the namespace specified in url.

  • Open an existing object

       person =  database.openid("Sample.Person",str(id),-1,-1)
    Copy code to clipboard

    person is your logical connection to a Sample.Person object on the Caché server.

  • Create a new object

       person =  database.create_new("Sample.Person", None)
    Copy code to clipboard
  • Set or get a property

       person.set("Name","Doe, Joe A")
       name = person.get("Name")
    Copy code to clipboard
  • Run a method

       answer = person.run_obj_method("Addition",[17,20])
    Copy code to clipboard
  • Save an object

       person.run_obj_method("%Save",[])
    Copy code to clipboard
  • Get the id of a saved object

       id = person.run_obj_method("%Id",[])
    Copy code to clipboard
  • Run a query

       sqlstring ="SELECT ID, Name, DOB, SSN \
                   FROM SAMPLE.PERSON \
                   WHERE Name %STARTSWITH ?"
       query = intersys.pythonbind.query(database)
       query.prepare(sqlstring)
       query.set_par(1,"A")
       query.execute();
       while 1:
          cols = query.fetch([None])
          if len(cols) == 0: break
          print cols
    Copy code to clipboard

Installation and Configuration

The standard Caché installation places all files required for Caché Python binding in <cachesys>/dev/Python. (For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide). You should be able to run any of the Python sample programs after performing the following installation procedures.

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.

  • Your PATH must include the <cachesys>\bin directory. (For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide).

  • Set up your environment variables to support C compilation and linking, as described in the following sections.

UNIX® Installation

  • Make sure <cachesys>/bin is on your PATH and in your LD_LIBRARY_PATH. (For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide).

    For example:

       export PATH=/usr/cachesys/bin:$PATH
       export LD_LIBRARY_PATH=/usr/cachesys/bin:$LD_LIBRARY_PATH
    Copy code to clipboard
    Note:

    Mac OS X uses DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH. For example:

       export DYLD_LIBRARY_PATH=/usr/cachesys/bin:$DYLD_LIBRARY_PATH
    Copy code to clipboard
  • Run setup.py (located in <cachesys>/dev/python):

       python setup.py  install
    Copy code to clipboard

    The following prompt is displayed:

       enter directory where you installed Cache'
    Copy code to clipboard
  • At the prompt, supply the location of <cachesys>. For example:

       /usr/cachesys
    Copy code to clipboard

    The resulting lib and include paths will be displayed:

       libdir=/usr/cachesys/bin
       include dir=/usr/cachesys/dev/cpp/include
    Copy code to clipboard
  • Run test.py (located in dev/python/samples ) to test the installation:

       python test.py
    Copy code to clipboard

    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.

Windows Installation

  • 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:

       vsvars32.bat
    Copy code to clipboard

    for 32-bit systems, or:

       vcvarsall.bat x64
    Copy code to clipboard

    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.

  • Run setup.py, located in <cachesys>/dev/python (for the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide):

       python setup.py install
    Copy code to clipboard

    The following prompt is displayed:

       enter directory where you installed Cache'
    Copy code to clipboard
  • At the prompt, supply the location of <cachesys>. For example:

       C:\Intersystems\Cache
    Copy code to clipboard

    The resulting lib and include paths will be displayed:

       libdir=C:\Intersystems\Cache\dev\cpp\lib
       include dir=C:\Intersystems\Cache\dev\cpp\include
    Copy code to clipboard
  • Run test.py (located in <cachesys>\dev\python\samples) to test the installation:

       python test.py
    Copy code to clipboard

    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.

  • A username and password.

By default, the Python sample programs use the following connection information:

  • URL: "localhost[1972]:Samples"

  • username: "_SYSTEM"

  • password: "SYS"

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 Management Portal). The Python sample programs use the administrator username "_SYSTEM" and the default password "SYS" or "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é.

Sample Programs

The standard Caché installation contains a set of sample programs that demonstrate the use of the Caché Python binding. These samples are located in:

<cachesys>/dev/Python/samples/

(For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide)

The following sample programs are provided:

  • CPTest2.py — Get and set properties of an instance of Sample.Person.

  • CPTest3.py — Get properties of embedded object Sample.Person.Home.

  • CPTest4.py — Update embedded object Sample.Person.Home.

  • CPTest5.py — Process datatype collections.

  • CPTest6.py — Process the result set of a ByName query.

  • CPTest7.py — Process the result set of a dynamic SQL query.

  • CPTest8.py — Process employee subclass and company/employee relationship.

All of these applications use classes from the Sample package in the SAMPLES namespace (accessible in Atelier).

Arguments

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:

  • -user — the username you want to login under (default is "_SYSTEM").

  • -password — the password you want to use (default is "SYS").

  • -host — the host computer to connect to (default is "localhost").

  • -port — the port to use (default is "1972").

A -user argument would be specified as follows:

   python CPTest2.py -user _MYUSERNAME
Copy code to clipboard

The CPTest7.py sample accepts a -query argument that is passed to an SQL query:

   python CPTest7.py -query A
Copy code to clipboard

This query will list all Sample.Person records containing names that start with the letter A.