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`.
- Any run that requires more than 1,000 API calls will prompt the user for confirmation. We do this to avoid accidentally running massive exports against the API due to human errors, since we have a monthly cap on the usage of xe.com's API.