add_expense

Simple expenses tool tracking CLI integrated with your own Google Spreadsheet.

Makes use of gspread, a Python library for Google Sheets API.

table of contents

• why use it?
• how to use it?
• how to install it?
• how to configure it?
• how to run it?

why use it?

This is just a fun program I wrote with Python to exercise a few concepts, but this may still come in handy when all you want is a straightforward approach to fast type and input your monthly expenses (i.e. no mouse pointing and clicking). Sure, it certainly requires improvements so be sure to check out the issues area.

how to use it?

First you'll need a spreadsheet similar to this one.

☝️ go to top

how to install it?

1. Clone or download this project

2. Install python3

3. Setup Google API authentication to your spreadsheet as explained in gspread's documentation

4. Configure the month and expense item coordinates (see next section)

☝️ go to top

how to configure it?

For now, the spreadsheet cells of each expense item (1st column of the above spreadsheet sample) and each month (first row) need to be referenced in the code. Just edit the following few values, in respect to the location of each column and row:

# Constants
COL_OPTIONS                 = 'A'

ROW_START_HOME 	 	    =  6
ROW_TOTALS_HOME 	    = 18

COL_JAN		            = 'B'
COL_FEB		            = 'C'
COL_MAR		            = 'D'
COL_APR		            = 'E'
COL_MAY		            = 'F'
COL_JUN		            = 'G'
COL_JUL		            = 'H'
COL_AUG		            = 'I'
COL_SEP		            = 'J'
COL_OCT		            = 'K'
COL_NOV		            = 'L'
COL_DEC		            = 'M'

☝️ go to top

how to run it?

To list the current expense items in your spreadsheet type add_expense.py --list or add_expense.py -l. This should present something like the below:

Authenticating...
Setting up menu options...
Menu option items:
0 Mortage-rent
1 Phone
2 Electricity
3 Gas
4 Water
5 Cable
6 Maintenance-repairs
7 Supplies
8 Other

To add a new expense, e.g. to your electricity bill, type add_expense.py -a 2 80.50 or add_expense.py --add 2 80.50

and the result will be something similar to this:

Authenticating...
Setting up menu options...
Selected option 2 found: Electricity
Expenses item 'Electricity' is currently empty (July 2020)
Setting Electricity with $80.50...

Note: as of the time of this writing there is still too much verbosity in user's feedback. This will hopefully be corrected in the near future.

Note: updates are always done to the current date's month unless month abbreviation (e.g. Jan, Feb, etc.) is specified.

To read the current expenses from your spreadsheet type add_expense.py -r 6 or add_expense.py --read 6 (i.e. Maintenance/repairs for this example)

Note: read operations are always done to the current date's month unless month abbreviation (e.g. Jan, Feb, etc.) is specified.

Authenticating...
Setting up menu options...
Selected option 6 found: Maintenance/repairs
Maintenance/repairs: 1 117,84 (=391,41+192,45+478,11+55,87)

Note: besides the total, the full formula is also shown.

See more instructions by typing add_expense.py --help

ADD EXPENSE appends currency amounts to your Google Spreadsheet.

Usage:
        add_expense [-h|--help]
        add_expense [-l|--list]
        add_expense [-a|--add] (<option> <value>) [<month>]
        add_expense [-r|--read] <option> [<month>]

Options:
        -h --help  Show this screen
        -l --list  List options
        -a --add   Add new expense (to current month, by default, else use month 3-letter name e.g. Jan Feb Mar etc.)
        -r --read  Reads expenses amount and formula (of current month, by default, else use month 3-letter name e.g. Jan Feb Mar etc.)

☝️ go to top