NPO-Accounting/oxrlib Files · README.rst

Files @ ae3e4617d31e

Branch filter:

Location: NPO-Accounting/oxrlib/README.rst

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

Brett Smith

historical: Always format rates with the same precision.

When we format a rate as a price, we don't know how much precision
is "enough" to do the conversion, because we don't know what's
being converted to. As a result, we may (=will almost certainly)
end up formatting the rate with different precision on the cost
date vs. the price date, and that causes Beancount/Ledger to fail
to make the connection between them.

Using a constant of 6 is enough to make the current test for
"enough" precision pass, so just do that for now. This might need
further refinement in the future.

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.