NPO-Accounting/oxrlib Files · README.rst

Files @ 71893ace4dc0

Branch filter:

Location: NPO-Accounting/oxrlib/README.rst

71893ace4dc0 1.6 KiB text/x-rst Show Annotation Show as Raw Download as Raw

Brett Smith

tests: Historical tests use more flexible rate matching.

This lets the tests be more flexible about how much precision is used in
rates when appropriate, and makes them ready to parametrize for
Beancount.

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_rate.rates dict.

Running tests
-------------

Run ``./setup.py test`` from your checkout directory.