CSV Budget Analyzer

Project roadmap

1. 01

   Set up the project and sample data

   ~1h

   Create a virtual environment, install pandas, fastapi, uvicorn and pytest, and save them in requirements.txt. Add data/sample.csv with at least 60 transactions over 3 months, with the columns date, description, amount and category. Use negative amounts for spending and positive amounts for income and refunds, and leave a few categories empty. Done when: the environment is set up and the sample file is in the repo.

2. 02

   Load and clean the CSV

   ~1.5h

   Write load_transactions(path) in budget.py that reads the CSV with pandas, converts the date column with pd.to_datetime (dayfirst when needed), converts amounts to numbers, fills empty categories with Uncategorized, and drops rows with an invalid date or amount, printing how many were dropped. Done when: loading the sample returns a clean DataFrame and reports the dropped rows.

3. 03

   Total spending by category and month

   ~1.5h

   Write spending_by_category(df) and spending_by_month(df), which look only at spending (negative amounts, shown as positive numbers) and return totals sorted from largest to smallest. Write monthly_breakdown(df), which returns a table with months as rows and categories as columns, using pivot_table. Done when: the three functions return correct totals for the sample file.

4. 04

   Build the command-line interface

   ~1.5h

   Use argparse so the tool runs like python budget.py data/sample.csv --month 2024-03 --budget budget.json. Print the category totals, the month totals and the breakdown as aligned tables, with amounts rounded to 2 decimals. --month limits the report to one month. Print a clear message for a missing file or a file without the required columns. Done when: the command prints readable tables, and bad input shows a helpful message.

5. 05

   Check budgets

   ~1.5h

   Read budget.json, which maps categories to monthly limits (for example {"Groceries": 400}). For each month, list the categories that went over their limit, with the amount spent, the limit and by how much it was exceeded. Categories without a budget are ignored. Done when: the report shows which categories went over budget in which months.

6. 06

   Serve the summary with FastAPI

   ~1.5h

   Create api.py with a FastAPI app and one endpoint, GET /summary?month=YYYY-MM, that loads the CSV and returns the category totals as JSON, reusing the functions from budget.py. Run it with uvicorn api:app --reload and try it in the automatic docs at /docs. Done when: /summary returns the same totals as the command-line tool.

7. 07

   Write tests

   ~1.5h

   Write pytest tests using a small DataFrame built inside the test: category totals, month totals, refunds reducing spending, empty categories becoming Uncategorized, invalid rows being dropped, and the over-budget check. Done when: pytest passes.

Resources

• Docspandas: 10 minutes to pandas
• Docsargparse tutorial
• DocsFastAPI tutorial
• Docspytest getting started