1.1   About the Implementation

The Python bindings are built on top of the C++ libraries, and should be as stable or unstable as this library. All of the API is supported, with only minor differences due to the language translation. In addition, some extra functionality is provided in a Python pacakge which is built built on top of the API we provide.

1.2   Supported Platforms

At the time of writing, the Python bindings are complete and supported only on the Linux platform.

1.3   Disclaimer

This software is provided under the GNU Lesser General Public License (LGPL), version 3. It comes with no guarantees whatsoever. In particular, by using this software, you agree to hold the makers of this software free of liability regarding any consequence of its direct or indirect use. You are responsible for making sure that the code behaves as you think it should. See the file oanpy/LICENSE for details.

2.1   Prerequisites

You will need to install:

• Python 2.x, along with its static library and include files;
• Boost: we only link against the Boost.Python and Boost.Thread libraries;
• The GCC compiler (version 4 or greater should do);
• Scons, in order to build the source code into a module.

If you will use the oanserv server, in addition you will need:

• Twisted (e.g. 2.5 or more recent)
• Version 2.6 of Python, or greater (because of the collections.nametuple class which we use).

2.2   Environment Notes and Setup

The code we provide does not include the client from OANDA's API (libfxclient.a and header files). You need to purchase your own license and obtain this library from them, as the API agreement clearly states that we cannot provide it to any thirdparty.

Set the OANDA_API environment variable to indicate the build programs where you have unpacked the header files and C++ library, e.g.:

OANDA_API = $(HOME)/fxclient/
export OANDA_API

2.3   Build Instructions

cd src/
scons      # build
scons -c   # clean up

The output should look something like this:

scons: done cleaning targets.
tangerine:~/p/oanpy/src$ scons
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
g++ -o oanda.os -c -fPIC oanda.cpp
g++ -E -I/usr/include/python2.6 pchboost.h > pchboost.hpp
g++ -o data.os -c -fvisibility=hidden -fvisibility-inlines-hidden -fPIC \
  -I/usr/include/python2.6 -I/home/blais/p/oanpy/include -I. data.cpp
g++ -o extras.os -c -fvisibility=hidden -fvisibility-inlines-hidden -fPIC \
  -I/usr/include/python2.6 -I/home/blais/p/oanpy/include -I. extras.cpp
g++ -o init.os -c -fvisibility=hidden -fvisibility-inlines-hidden -fPIC \
  -I/usr/include/python2.6 -I/home/blais/p/oanpy/include -I. init.cpp
g++ -o events.os -c -fvisibility=hidden -fvisibility-inlines-hidden -fPIC \
  -I/usr/include/python2.6 -I/home/blais/p/oanpy/include -I. events.cpp
g++ -o exception.os -c -fvisibility=hidden -fvisibility-inlines-hidden -fPIC \
   -I/usr/include/python2.6 -I/home/blais/p/oanpy/include -I. exception.cpp
g++ -o orders.os -c -fvisibility=hidden -fvisibility-inlines-hidden -fPIC \
  -I/usr/include/python2.6 -I/home/blais/p/oanpy/include -I. orders.cpp
g++ -o connect.os -c -fvisibility=hidden -fvisibility-inlines-hidden -fPIC \
  -I/usr/include/python2.6 -I/home/blais/p/oanpy/include -I. connect.cpp
ar rc liboanpy.a exception.os connect.os data.os events.os orders.os extras.os \
  init.os ranlib liboanpy.a
g++ -o _oanda.so -shared -fvisibility=hidden -fvisibility-inlines-hidden \
  --strip-all oanda.os -L/home/blais/p/oanpy/include -L. \
  -lnsl -lm -lc -lpthread -ldl -lz -lcrypto -lrt -lexpat \
  -lboost_python -lboost_thread -loanpy -lfxclient
Install file: "_oanda.so" as "/home/blais/p/oanpy/lib/python/oanda/_oanda.so"
scons: done building targets.

The target DSO should sit in lib/python/oanda/_oanda.so. This should be a working Python extension module (though it is not meant to be imported directly, the oanda package takes care of that, and adds code written in pure Python as well), see oanda/__init__.py.

2.4   Installation

Run the usual distutil procedure to have the files installed in your Python distribution:

python setup.py install

To test the installation, try to import the module; if no error occurs, it worked:

tangerine:~$ python
Python 2.6.2 (release26-maint, Apr 19 2009, 01:56:41)
[GCC 4.3.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import oanda
>>>

(Note: the oanda package imports the _oanda.so DSO itself.)

3.1   Account Information

You create a connection by instantiating a “client”: either an FXGame or an FXTrade object. Note that before you call the login() method, you may have to set some of the general connection parameters:

fxclient = FXTrade()
try:
    fxclient.login(username, password)
except OAException, e:
    raise SystemExit("Could not login: %s" % e)

[...]

fxclient.logout()

3.2   Fetching Exchange Rates (Polling)

Get a single rate via the global object RateTable:

tick = fxclient.getRateTable().getRate(Pair('USD/CAD'))

3.3   Subscribing to Rate Updates

The OANDA API requires you to derive from the RateEvent class in order to subcribe and handle market data events. This works the same way with Python, create a new class and override its handle() method:

from oanda import RateEvent

class RatesMonitor(oanda.RateEvent):

    def match(self, event_info):
        # Return false if you don't want to handle this (default is True).

    def handle(self, event_info, event_manager):
        # Handle the market data update.

[...]

# Enable the rate thread (important).
fxclient.setWithRateThread(True)

mon = RatesMonitor()
fxclient.getRateTable().eventManager().add(mon)

3.4   Order Placement

To place orders, create the class corresponding to the type of order you'd like to place, and execute it on the account. You will get a list of “trade” objects back, that correspond to your orders (the name is poorly chosen, but that's from the API so I prefer not to change it):

order = MarketOrder()
order.base, order.quote = pair.split('/')
order.units = 1
modtrades = acc.execute(order)
for trade in modtrades:
    print
    print '  ', str(trade)

3.5   Trade Confirmations

Monitor trade confirmations works similarly as for rate updates, they're called “Account events”:

from oanda import AccountEvent

class AccountEventsMonitor(oanda.AccountEvent):

    def handle(self, event_info, event_manager):
        # Handle the account event.

[...]

# Enable the rate thread (important).
fxclient.setWithRateThread(True)

user = fxclient.getUser()
for acc in user.getAccounts():
    mon = AccountEventsMonitor(acc)
    acc.eventManager().add(mon)

3.6   Fetching Historical Data

See the RateTable.getHistory() methods. Instead of taking a vector as input, they are modified to return Python list objects with the results.

4.1   Mapping of Names

Because the Python API is a direct mapping on top of the C++ API, we do not provide documentation specific to it other than this document. The main reference should be the include files that you should have obtained once you acquired the license from OANDA itself. This file only documents the differences between the C++ version of the OANDA API and the Python view that we provide..

FXAccountEvent            ->    AccountEvent
FXAccountEventInfo        ->    AccountEventInfo
FXEvent                   ->    Event
FXEventInfo               ->    EventInfo
FXEventManager            ->    EventManager
FXHistoryPoint            ->    HistoryPoint
FXInstrument              ->    Instrument
FXPair                    ->    Pair
FXRateEvent               ->    RateEvent
FXRateEventInfo           ->    RateEventInfo
FXTick                    ->    Tick
FXTransactionType         ->    TransactionType

rate_table.getHistory(Pair('EUR/USD'),
                      INTERVAL.INTERVAL_10_SEC,   # <-- (enum)
                      60)

4.2   Holding References to Objects

During the development of the bindings, I have occasionally exposed some of the transient objects provided by the callbacks, to the Python side. Keeping and using a reference to those objects from Python would cause a core dump (the C++ objects get freed within the OANDA C++ library).

The solution is rather inelegant: create a copy of the objects whenever a callback is invoked. This is what is being done at the moment but it really is the lesser of two evils. In any case, you should try to avoid keeping around objects provided to you by callback methods (or make copies of them instead).

Note: if someone feels like working out a scheme with the Python interpreter's weakptr type, this could be a clean solution for this problem (interesting little project).

4.3   Threads and Dispatching

The C++ client library uses a background thread to dispatch the rate and account event callbacks. Because of limitations around the global Python interperter lock, we need to queue the events and let you choose the preferred method for dispatching them in the main Python thread or otherwise. This requires you to choose a preferred technique.

There are four methods for dispatch the events:

1. Blocking Call: You call the fxevents_process_loop() function, which will block and dispatch the events as they come. This becomes your main loop.
2. Polling: this is a variant on the previous method, where you are simply call a non-blocking version of the dispatcher at regular intervals (fxevents_process_pending()).
3. In another Python thread: you create a separate thread in Python to handle the blocking call in (1).
4. Using select(): you block on a call to select(), juggling the I/O of data on sockets and the dispatching of queued events. The module allows you to set a file descriptor that it writes a single byte to when a new event has arrived. This wakes up the select() call and you can dispatch the events immediately.

There are examples for each of these methods in lib/python/oanda/dispatch.py. The example code for the select()-based dispatch uses xTwisted.

4.4   Integration with a GUI toolkit

I have not yet completed integration with a GUI toolkit. I've been meaning to write a GUI application using PyQt. I think it would work like this:

• Your execution loop in the main UI/Python thread would be the GUI's loop, without modification.
• You would dispatch messages via a separate Python-level thread, which would either
  1. Wake up the GUI loop/thread using a “custom GUI event”, and you would have this event trigger a callback in the main thread to dispatch the events using fxevents_process_pending().
  2. Dispatch the messages directly from the other Python thread, which is possible because of the GIL restriction (no other Python code will be able to run in the same PVM during this time). You would need to be careful with thread-local data and non-Python locking issues.

4.5   About Timestamps

Be careful when initializing objects with timestamps, the expected time resolution is in seconds, and if you use Python's time.time() function, it returns a float. You will need to convert that to an int to use the API functions.

4.6   Precision of Types for Prices

The OANDA API provides prices as C type double, which is unwise, due to rounding error. See the module lib/python/oanda/prices.py which provides functions to convert to Decimal or int Python objects.