Fython

Fython is a keyboard-first personal finance tracker with a full-screen terminal UI, optional desktop GUI, and an importer for HDFC bank statement exports.

This repository is prepared for public sharing: local statements, generated CSVs, personalization files, and app state are kept out of Git by default.

Features

• Import HDFC statement exports from local .csv, .xls, .xlsx, and .qif files
• Normalize transactions into a single CSV for analysis and editing
• Auto-categorize spending into main and sub-categories
• Review anomalies such as duplicate groups, date coverage gaps, and spend outliers
• Browse transactions in a full-screen terminal UI with filters, search, and per-account views

Requirements

• Python 3.10+
• macOS, Linux, or another environment that supports the dependencies in requirements.txt

Install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run The App

Terminal UI using the included demo dataset:

python -m fython --normalized sample_normalized.csv --data-dir data

Terminal UI with your own imported data:

python -m fython

Desktop GUI:

python -m fython gui

Import-only mode:

python -m fython.main import

Private Data Handling

• Put your own bank statement exports in data/ when running imports locally.
• data/, normalized.csv, example_data.csv, and local database/state files are ignored by Git.
• The included sample_normalized.csv is anonymized demo data for screenshots, testing, and first-run exploration.

Common Commands

python -m fython.main --help
python -m fython.main import --data-dir data --normalized normalized.csv
python -m fython.main --normalized sample_normalized.csv --data-dir data
python -m fython.main gui

TUI Keys

• r sync statements from data/
• n add a new transaction
• e edit the selected transaction
• d dashboard
• t transactions
• m monthly summary
• c category breakdown
• a anomalies and data-quality checks
• / search
• Esc clear search
• q quit

Project Layout

• fython/ application package
• config/ categorization, scoring, and localization data
• data/ local-only import directory kept out of Git
• sample_normalized.csv anonymized demo dataset
• USAGE.md detailed workflow notes

Notes

• The importer is designed for HDFC export formats.
• Running the app without a normalized CSV will open the UI with an empty dataset until you import data.
• The terminal UI is the default entrypoint when no subcommand is provided.