PocketWise Finance

Personal Finance Categorization and Budget Analysis Package

Group Project – Python Data Analysis II

Team Members - Group 3:

• JUAN CAMILO LUJÁN GONZÁLEZ
• LAURENZ JAKOB KLUTH
• RALUCA-TEO GOGOSOIU
• SILVIA MENDOZA MEDINA
• STEPHAN PENTCHEV STEFANOV

---

1. Project Context

PocketWise Finance is a Python package developed as part of the Python Data Analysis II course.

The objective of this project was to:

• Design and implement a reusable Python package
• Apply object oriented programming concepts
• Publish the package to TestPyPI
• Separate the library from a Streamlit application
• Follow modern packaging standards using uv and pyproject.toml

This package focuses on automated categorization and aggregation of personal finance transactions exported from bank CSV files.

---

2. Technical Objective

The goal of the package is to transform raw transactional data into structured, categorized, and summarized financial information.

The package performs the following pipeline:

1. CSV ingestion
2. Object transformation into immutable Transaction instances
3. Rule based categorization using regular expressions
4. Aggregation by month and category
5. Optional export via CLI

The design prioritizes:

• Modularity
• Testability
• Extensibility
• Clear separation of responsibilities

---

3. Architecture Overview

The project follows a src/ layout and is structured as follows:

pocketwise-finance/
  pyproject.toml
  README.md
  src/
    pocketwise/
      models.py
      rules.py
      io.py
      engine.py
      reporting.py
      cli.py
  tests/

Core Modules

models.py

Defines the Transaction class as a frozen dataclass.

• Immutable and hashable
• Uses type hints
• Stores date, description, amount, currency, category

rules.py

Implements a rule engine using inheritance.

• BaseRule abstract class
• RegexRule subclass implementing regex matching
• RuleSet class storing ordered rules
• First match wins strategy

io.py

Handles CSV ingestion.

• Uses pathlib.Path
• Streams transactions using a generator
• Parses dates using datetime

engine.py

Applies categorization logic.

• Categorizer class uses composition with RuleSet
• Returns new immutable Transaction objects

reporting.py

Handles aggregation logic.

• Groups transactions by month and category
• Uses defaultdict
• Formats dates using strftime

cli.py

Implements command line interface using argparse.

• Accepts CSV path
• Optional output path
• Writes JSON summary

---

4. Object Oriented Design

This project demonstrates several OOP principles:

• Classes and instances
• Immutable objects (Transaction is frozen)
• Class attributes (default category)
• Instance attributes
• Inheritance (BaseRule → RegexRule)
• Composition (Categorizer contains RuleSet)
• Magic methods (__len__, __iter__, __repr__)
• Encapsulation of rule logic

The rule engine is extensible. New rule types can be added by subclassing BaseRule.

---

5. Installation (TestPyPI)

Install the package from TestPyPI:

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pocketwise-finance

---

6. Usage as a Python Library

Example usage:

from pathlib import Path
from pocketwise.io import stream_transactions_csv
from pocketwise.rules import RuleSet, RegexRule
from pocketwise.engine import Categorizer
from pocketwise.reporting import summarize_by_month_and_category

rules = RuleSet([
    RegexRule("Groceries", r"carrefour|mercadona|aldi|lidl"),
    RegexRule("Transport", r"uber|bolt|metro|renfe|cabify"),
    RegexRule("Subscriptions", r"netflix|spotify|prime|hbo"),
])

categorizer = Categorizer(rules)

transactions = list(stream_transactions_csv(Path("transactions.csv")))
categorized = categorizer.categorize_all(transactions)

summary = summarize_by_month_and_category(categorized)

print(summary)

---

7. Command Line Interface

After installation, the following command is available:

pocketwise transactions.csv --out summary.json

This command:

• Reads the CSV file
• Applies default rules
• Generates a monthly summary
• Writes results to JSON

To view CLI help:

pocketwise --help

---

8. Expected CSV Format

The CSV file should contain:

• date (YYYY-MM-DD)
• description
• amount

Example:

date,description,amount
2026-03-01,Mercadona purchase,-35.60
2026-03-02,Netflix subscription,-12.99
2026-03-03,Salary,2500.00

---

9. Testing

The package includes unit tests using pytest.

Run tests with:

uv run pytest

Tests validate:

• Rule matching behavior
• Default categorization
• CSV ingestion
• Aggregation logic

---

10. Build and Publish

Build distribution files:

uv run python -m build

Upload to TestPyPI:

uv run twine upload --repository-url https://test.pypi.org/legacy/ dist/*

---

11. Academic Scope

This project demonstrates:

• Python packaging with uv
• Publishing to TestPyPI
• Modular software architecture
• Rule based classification using regex
• Datetime handling and formatting
• CLI development with argparse
• Automated testing

This package serves as the backend library for a separate Streamlit application.

---