This application that can track and manage your fuel expenses. It will allow you to enter fuel expenses based on:

• Date
• Cost
• Liters added
• Mileage since last fill up

You will be able to register different vehicles in the database and associate the expenses with each vehicle. The information will be stored in a SQLite database (~/.config/bluebill.net/fuel_tracker/data.db).

1. Install Rye
2. Installation and Configuration
3. Activate

To get this project up and running from the repository, it uses Rye as the build/dependency manager. There are instructions for installing Rye on many different systems. This set of instructions are for Linux and windows. See the installation guide for other operating systems.

You have to download Rye to your system. Follow the installation guide for your operating system.

Why Rye? That is a good question. Python is a great language but it is tough to create a reproducible environment. You have to have the correct version of Python installed or available. You have to have the correct tools configured. If you are on Linux/BSD you have to make sure that your work doesn't mess up your system Python installation. It is fairly trivial if you are experienced, but annoying enough to have to do it over-and-over again. If you are new, it can be extremely difficult.

Rye takes care of handling the different versions of Python and managing the tools you need for a reproducible environment, particularly if you are doing cross-platform work.

For Linux, you can use the following:

curl -sSf https://rye-up.com/get | bash

There are also good guides to configuring Rye for your shell. Here is what I had to do to get it working in ZSH on my system.

Edit .zshrc:

vi ~/.zshrc

Add the following:

source "$HOME/.rye/env"

Restart the terminal and type rye. To add shell completion, you can:

mkdir $ZSH_CUSTOM/plugins/rye
rye self completion -s zsh > $ZSH_CUSTOM/plugins/rye/_rye

For windows, download the installer listed in the installation guide link.

Update rye:

rye self update

Once you have rye properly installed, you can run rye sync, to build (or update) the virtual environment.

Create/Update Virtual Environment

rye sync

NOTE: This needs to be run from within the repository. If you add new dependencies or modify the pyproject.toml you should run rye sync.

You can add the following alias to your .zshrc or .bashrc, or you can run the activate script directly:

# Python Virtual Environment Alias
alias activate="source .venv/bin/activate"

NOTE: On Windows, there is an activate.ps1, a PowerShell script that you can execute.

To add a vehicle to the database, issue the following command:

$ ft vehicle add

Where:

• ft - This is the name of the program to execute ft = fuel tracker.
• vehicle - This command tells fuel tracker we want to work with vehicles.
• add - This sub-command tells fuel tracker we want to add a new vehicle to the database.

With the bare command (above) you will be prompted for the missing information:

• name - A name that can be used to identify the vehicle. This can be the model of the vehicle or something more memorable or easier to type. It should be unique.

• make - The make of the vehicle. For example it could be VW, Ford or Toyota.

• model - This is the type of vehicle. For example it could be Passat, F-150 or Hilux

• year - The year of the vehicle. It should be 4 digits - 2021 for example.

• tank - The fuel capacity in liters

• initial-odo - The initial odometer reading in kilometers

Optionally, you can provide a list of switches with the correct information. Don't worry, if you don't provide the switches, fuel tracker will prompt you for the missing information. The switches are as follows:

$ ft vehicle add --name=passat --make=VW --model=Passat --year=2015 --tank=70 --initial-odo=0

NOTE: Currently not implemented. On Linux and Windows you can use DB Browser for SQLite.

Add new fuel records to the database for the vehicle. You must specify the vehicle to attach the fuel record to by database id or by name. You can optionally specify the switches or be prompted for the minimum data.

If you forget, what you have in the database, you can type:

$ ft fuel add

without a vehicle name or id and it will show you a list of valid entries. It will show you a list of valid commands, simply copy and paste the correct one.

Add a fuel record by using the vehicle name:

$ ft fuel add passat

or by vehicle id:

$ ft fuel add 4

You can also use switches at the CLI if you like. If not, you will be prompted for the information.

Switches:

  --date [%Y-%m-%d|%d/%m/%y|%m/%d/%y|%d/%m/%Y|%m/%d/%Y]
                                  The date fuel was added to the vehicle.
                                  Support 5 major date formats in the
                                  following order: Y-m-d, d/m/Y, d/m/y, m/d/Y,
                                  m/d/y (first match is taken)
  --fuel FLOAT                    The amount of fuel added to the vehicle.
  --mileage FLOAT                 The mileage since the last fill up.
  --cost FLOAT                    The full cost of the fuel.
  --partial BOOLEAN               Was this a partial fill up. Optional - you
                                  will not be prompted and have to set the
                                  switch.
  --comment TEXT                  A comment about this fuel record. Optional -
                                  you will not be prompted and have to set the
                                  switch.
  --help                          Show this message and exit.

NOTE: The date format can be one of the following:

1. %Y-%m-%d - year-month-day 2021-08-12
2. %d/%m/%y - day/month/year 12/08/21
3. %m/%d/%y - month/day/year 08/12/21
4. %d/%m/%Y - day/month/year 12/08/2021
5. %m/%d/%Y - month/day/year 08/12/2021

NOTE: The first format to produce a correct date is used. The date is matched against the list in the order specified above. For example, 02/03/2021 can match 2 or 3 but will match 2 first. Beware. It is best to use the ISO 8601 representation.

NOTE: If you use any of the date formats that have a /in them you will have to escape them on the CLI using quotation marks.

Example of prompts:

$ ft fuel add passat
>Date: 2021-08-29
>Fuel: 45.893
>Mileage: 645.8
>Cost: 54.35

4 - passat
Date    = 2021-08-29 00:00:00
Fuel    = 45.893
Mileage = 645.8
Cost    = 54.35
Partial = None
Comment = None
Is the Fuel Record Correct? [Y/n]:

NOTE: It will not prompt for partial or comment. These switches must be specified as they are optional fields.

Add a fuel record to the vehicle (switches):

$ ft fuel add passat --date=2021-01-01 --fuel=48 --mileage=750 --cost=56.65 --partial --comment="Some reason"

NOTE: Currently not implemented. On Linux and Windows you can use DB Browser for SQLite.

You can bulk add new vehicles and fuel records to the database with a carefully crafted spreadsheet. Fuel Tracker supports both Excel and Open Office formatted spreadsheets (*.xlsx and *.ods). The spreadsheet will need the following columns defined:

• name - A name used to identify the vehicle. This name will be used by you when communicating with Fuel Tracker. Alternatively, you will also be able to specify a unique number representing the vehicle in the database.

• make - The make of the vehicle (i.e. Ford, Toyota, Volkswagen).

• model - The model of the vehicle (F-150, Passat, Camry).

• year - The year of the vehicle.

• tank_capacity - The tank capacity in liters.

• initial_odometer - The initial odometer reading when added to the system in kilometers.

• fill_date - The date you put fuel in your vehicle (yyyy-mm-dd).

• mileage - The number of kilometers since the last fill date. Normally you would capture this on your trip meter.

• fuel - The amount of fuel added in liters.

• cost - The cost of the fuel.

• partial - Was this a partial fill up? That is, did you only put a small amount of fuel into the tank? 1 if you did, 0 or leave it empty if you didn't.

• comment - An optional description of the fuel record. You can record unusual things or the reason for a partial fill up.

NOTE: The column order doesn't matter. You will have to duplicate the vehicle information for every fuel record - that is a requirement.

You can point directly to the spreadsheet:

$ ft bulk add ./data/vw-passat-2015.ods

You can specify multiple different spreadsheets:

$ ft bulk add ./data/vw-passat-2015.ods ./data/dodge-intrepid-1997.ods

You can specify a wild card to include all of the spreadsheets:

$ ft bulk add ./data/*.ods

NOTE: The spreadsheet format matches the format of the Bulk Export Option. So you can bulk export all of your records and then import those directly into a new database. It is a great way to backup your data in a format outside the database.

You can bulk delete vehicles and all the records associated with them. You specify the vehicle by name or by database id:

$ ft bulk delete passat 2

Export the vehicle(s) and its fuel records to various formats. The available export formats are:

• CSV - Export to CSV
• Excel - Export to Excel
• ODS - Export to Open Office
• stdout - Export to the terminal

The vehicle and fuel records will be combined into one table and exported to the file. If an output format isn't selected, it will be displayed in the terminal.

Display the records for the vehicles:

$ ft bulk export passat 2

Export the vehicles and fuel records to Excel:

$ ft bulk export passat interpid --excel=file.xlsx

NOTE: When multiple vehicles are exported to a spreadsheet format new tabs, one for each vehicle will be created inside the spreadsheet. One file is created that contains all of the data separated by different sheets within the file.

Export the vehicles to the Open Office format (ODS):

$ ft bulk export passat interpid --ods=file.ods

Export the vehicles to CSV:

$ ft bulk export passat interpid --csv=file.csv

NOTE: Exporting multiple vehicles to CSV will result in one CSV being created for each vehicle.

Export multiple vehicles to multiple different formats:

$ ft bulk export passat interpid --excel=file.xlsx --ods=file.ods --csv=file.csv

NOTE: This is a good way of backing up the database in a different format.

Display the fuel records for the vehicle (by name or id). This option will also show a yearly summary.

If you forget the vehicle name or id, type the command and a list of possible values will be suggested. Copy/paste the command:

$ ft report show

Options:

--tail INTEGER   Display the last `n` records. Defaults to 10. Use -1 to
               select all records.
--hide-partial   Hide the partial column.
--hide-comments  Hide the comments column.
--extra-summary  Include extra columns in the summary report
--help           Show this message and exit.

Display the summary for a specific vehicle:

$ ft report show passat

id:            4
Name:          passat
Make:          Volkswagen
Model:         Passat
Year:          2015
Tank Capacity: 70.0
Odometer:      0.0

+---+-----------+------------+------+---------+--------+-------+-------+---------+----------+-----------+
|   | fuel (id) | fill date  | days | mileage |  fuel  | cost  |  $/l  | l/100km | mpg (us) | mpg (imp) |
+---+-----------+------------+------+---------+--------+-------+-------+---------+----------+-----------+
| 0 |    832    | 2021-01-31 |  48  |  778.0  | 26.278 | 29.41 | 1.119 |  3.378  |  69.639  |  83.633   |
| 1 |    833    | 2021-03-14 |  42  |  384.9  | 24.019 | 30.0  | 1.249 |  6.24   |  37.693  |  45.267   |
| 2 |    829    | 2021-06-05 |  83  |  273.5  | 47.281 | 60.0  | 1.269 | 17.287  |  13.606  |   16.34   |
| 3 |    828    | 2021-07-15 |  40  |  738.0  | 46.154 | 60.0  |  1.3  |  6.254  |  37.611  |  45.169   |
| 4 |    827    | 2021-08-17 |  33  |  861.5  | 45.872 | 60.0  | 1.308 |  5.325  |  44.175  |  53.051   |
| 5 |    838    | 2021-11-04 |  79  |  790.6  | 41.125 | 60.0  | 1.459 |  5.202  |  45.218  |  54.305   |
| 6 |    837    | 2021-11-22 |  18  |  759.8  | 41.152 | 60.0  | 1.458 |  5.416  |  43.428  |  52.155   |
| 7 |    834    | 2021-12-05 |  13  |  731.7  | 41.152 | 60.0  | 1.458 |  5.624  |  41.822  |  50.226   |
| 8 |    836    | 2021-12-12 |  7   |  551.3  | 41.152 | 60.0  | 1.458 |  7.465  |  31.511  |  37.843   |
| 9 |    835    | 2021-12-27 |  15  |  833.1  | 41.152 | 60.0  | 1.458 |  4.94   |  47.618  |  57.187   |
+---+-----------+------------+------+---------+--------+-------+-------+---------+----------+-----------+

Summary by Year:
+---+------+----------+-----------------+--------------+--------------+-----------+---------------+----------------+-----------------+
|   | year | Fill-Ups | Mileage (Total) | Fuel (Total) | Cost (Total) | $/l (Avg) | l/100km (Avg) | mpg (us) (Avg) | mpg (imp) (Avg) |
+---+------+----------+-----------------+--------------+--------------+-----------+---------------+----------------+-----------------+
| 0 | 2015 |    33    |     30787.0     |   1703.345   |    1818.9    |   1.068   |     5.533     |     42.514     |     51.057      |
| 1 | 2016 |    28    |     26317.3     |   1476.104   |   1378.62    |   0.934   |     5.609     |     41.936     |     50.363      |
| 2 | 2017 |    30    |     26221.8     |   1483.908   |   1561.36    |   1.052   |     5.659     |     41.564     |     49.917      |
| 3 | 2018 |    20    |     16975.6     |   980.231    |   1201.23    |   1.225   |     5.774     |     40.734     |      48.92      |
| 4 | 2019 |    26    |     22831.9     |   1327.747   |   1582.42    |   1.192   |     5.815     |     40.447     |     48.575      |
| 5 | 2020 |    15    |     13179.8     |   800.271    |    882.02    |   1.102   |     6.072     |     38.738     |     46.522      |
| 6 | 2021 |    10    |     6702.4      |   395.337    |    539.41    |   1.364   |     5.898     |     39.877     |     47.891      |
+---+------+----------+-----------------+--------------+--------------+-----------+---------------+----------------+-----------------+

Please refer to LICENSE.md.