# Fuel Tracker#

I have written a simple fuel tracker application and you can find it here. The idea is a simple system to keep track of fuel records far various vehicles I have owned through the years. I have been keeping track of my fuel records since 2002 across 4 vehicles. I have over 800 records stored in the database. A modest amount, but good information.

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

• Date

• Cost

• 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 is stored in a local SQLite database.

## Installation#

You will need an operating version of Python installed and it should be at least version 3.9. You’ll need to create a virtual environment.

### Linux#

If you use Linux, the installation steps are fairly basic. You will need to have Python correctly installed and available your path (>= v3.9):

python --version

Python 3.9.5


Upgrade pip:

python -m pip install --upgrade pip


Install the virtualenv:

python -m pip install virtualenv


Create the installation folder, for example, ~/opt/ft:

cd ~

mkdir ft

cd ft


Create the virtual environment:

python -m venv .venv


Activate the virtual environment:

source .venv/bin/activate


Install Fuel Tracker:

python -m pip install git+https://github.com/TroyWilliams3687/fuel_tracker.git


### Windows#

You follow, more or less, the same steps as the Linux installation.

## Usage#

### Vehicle#

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


#### Edit and Remove Options#

Note

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

### Fuel Record#

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.
will not be prompted and have to set the
switch.
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

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"


#### Edit, Remove and Show#

Note

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

### Bulk Operations#

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.

#### Delete#

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#

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.

### Report#

#### Show#

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.
--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      |
+---+------+----------+-----------------+--------------+--------------+-----------+---------------+----------------+-----------------+