oxrlib

======

Introduction

------------

oxrlib provides a Python library and CLI tool to query the `Open Exchange Rates API <https://openexchangerates.org/>`_.  It emphasizes support for rich data types throughout, and supports caching API results to the filesystem.

It currently only supports OXR's "historical" API.

Getting started with the CLI tool

---------------------------------

oxrlib includes an `oxrquery` tool to access the OXR API directly from the command line.  By default, it reads your OXR credentials and other common configuration from `~/.config/oxrlib.ini`.  Copy `oxrlib_example.ini` from the source to `~/.config/oxrlib.ini`, then edit that file following the instructions in the comments.

Run `oxrquery --help` for instructions to use the tool.

Getting started with the library

--------------------------------

Here's an example of using the Python library, complete with caching results:

  from oxrlib import cache, loaders, rate

  filename_format = '{date}_{base}_rates.json'

  cache_writer = cache.CacheWriter(DIR_PATH, historical=filename_format)

  loader = loaders.LoaderChain()

  loader.add_loader(loaders.FileCache(DIR_PATH, historical=filename_format))

  loader.add_loader(loaders.OXRAPIRequest(APP_ID_STRING))

  with loader.historical(DATE, BASE_CODE_STRING) as json_response:

      hist_rate = rate.Rate.from_json_file(json_response)

  if loader.should_cache():

      cache_writer.save_rate(hist_rate)

  # Rates are available from the hist_rates.rates dict.

[OXR]

# This section includes settings to query the Open Exchange Rates API directly.

# An App ID provided by OXR.

app_id = abcd1234...

[Cache]

# This optional section includes settings to read and write a cache of API

# results on the filesystem.  If you omit these settings, results won't be

# cached.

# The directory to save cache files under.  This directory must already exist.

directory = /home/YOU/.cache/oxrlib

# Save data from the historical API using this filename pattern.

# The pattern must include `{date}` and `{base}`, where API parameters are

# filled in.

historical = {date}_{base}_rates.json

[Historical]

# This optional section can specify default parameters for historical API calls.

# Set the base currency.

# Note that setting a base other than USD requires a paid OXR account.

base = USD