data-xexe/README.md

# xexe

`xexe` is Superhog's tool to ingest currency rates from xe.com into our DWH. `xexe` is a Python CLI application, and this is the repository where it lives.

## How to use the tool

*Note: the app has only been used so far in a Linux environment. Windows support is dubious.*

### Install

- Ensure you have Python 3.10> and `poetry` installed.
- Run `poetry install` to install dependencies.
- Activate the project's virtual environment. You can use `poetry shell`.
- Test that everything is working by running `xexe smoke-test`. You should see a happy pig.

### Set up credentials

To use `xexe`, you will need to have credentials for the `xe.com` API. Specifically, you need an account id and it's matching api key.

To set up your environment, you should create a `.env` file and place it in `~/.xexe/.env`. You will have to run `xexe` as the right user to ensure the `.env` file is found. You can use the `.env-example` file as a reference. We also recommend running `chmod 400` or `chmod 600` on it for safety.

Once you have done this, you can run `xexe xe-healthcheck`. If the connection to the API was successful, you will see some output telling you so.

## Using

Remember to activate the project virtual environment.

You can use `xexe` to get rates and store them locally like this:

```bash
xexe get-rates --start-date "2024-01-01" --end-date "2024-01-10" --output my_rates.csv
```

You can also run without specifying dates. Not specifying `end-date` will get rates up to today. Not specifying `start-date` will get dates up to last week.

```bash
xexe get-rates --output my_rates.csv
```

`xexe` comes with a set of default currencies, but you can also specify the currencies you want to get data for by passing them like this:

```bash
# Currencies must be valid ISO 4217 codes and be comma-separated
xexe get-rates --currencies USD,EUR,GBP --output my_rates.csv
```

The output file will follow this schema:

- `date`
- `from_currency`
- `to_currency`
- `exchange_rate`
- `exported_at`

A few more details:

- Running `get-rates` with an `end-date` beyond the current date will ignore the future dates. The run will behave as if you had specified today as the `end-date`.
- Trying to place an `end-date` before a `start-date` will cause an exception.