HDFC Demat Statement Parser & CSV Exporter

A privacy-first tool to parse HDFC Demat Transaction Statements (.xls and .xlsx) and export clean, standardized CSV files.

This repository provides both a 100% client-side Progressive Web App (PWA) that runs directly in your browser and a standalone Python library.

Disclaimer: I do not work for HDFC Bank, and this is an unofficial tool that I have made for personal use

---

🌐 Live Web App (No Installation or Server Required)

You do not need to install Python, Node.js, or run a local server to use this tool!

👉 Use the Web App: https://sspathak.github.io/HDFC-demat-parser/

Simply drag and drop your HDFC Demat .xls or .xlsx statement file into the browser:

• Instant CSV Export: Download the converted CSV file in one click.
• Custom Columns: Choose which fields to include in the preview and CSV export.
• Portfolio Analytics: View scrip-level share inflows vs. outflows and monthly activity timelines.
• Offline Capable: Install it as a PWA and use it completely offline.

---

🔒 Privacy by Design

Demat statements contain sensitive personal identifiers, DP account numbers, and transaction records. This utility is engineered with a strict zero-knowledge architecture:

• Zero Server Uploads: Processing happens 100% client-side in your browser's local memory (RAM) via JavaScript.
• No Backend: There is no server receiving, storing, or inspecting your files.
• Strict Content Security: No telemetry, tracking scripts, cookies, or external API calls.
• Volatile Storage: Data exists only while the page is open. Refreshing or closing the tab instantly clears all parsed data.

---

🚀 Key Features

• Handles Complex Merged Formats: Intelligently un-merges ISIN rows, maps company scrip headers to their trade rows, and skips non-transaction footers.
• Multi-Format Support: Reads both legacy binary Excel (.xls / BIFF8) and modern OpenXML Excel (.xlsx) files.
• Customizable Output: Default export includes ISIN, Date, Name of Scrip, Debit, and Credit. Optionally include Reference No., Description, Market Type, Setlno, and Counter Party Details.
• Interactive Visualizations: Includes scrip-level credit/debit comparison charts and transaction search filters.
• Automated CI/CD: Pre-configured GitHub Actions workflow that automatically tests and deploys updates to GitHub Pages.

---

🐍 Python Library Usage

For developers who want to use the parser programmatically in Python scripts or data pipelines:

Installation

Requires Python 3.9+ with pandas, xlrd (for .xls), and openpyxl (for .xlsx):

pip install pandas xlrd openpyxl

Or using Pixi:

pixi exec --spec pandas --spec xlrd --spec openpyxl python your_script.py

Basic Example

from hdfc_demat_parser import HDFCDematParser

# Initialize parser with default columns: ISIN, Date, Name of Scrip, Debit, Credit
parser = HDFCDematParser()

# Parse directly into a Pandas DataFrame
df = parser.parse("path/to/statement.xls")
print(df.head())

# Or export directly to a clean CSV
parser.to_csv("path/to/statement.xls", output_path="demat_transactions.csv")

Custom Column Selection

# Include all statement columns
parser_all = HDFCDematParser(target_columns='all')
df_all = parser_all.parse("path/to/statement.xls")

# Or specify custom columns
custom_parser = HDFCDematParser(target_columns=["Date", "Name of Scrip", "Credit", "Debit", "Reference No."])
df_custom = custom_parser.parse("path/to/statement.xls")

---

🛠️ Developer Guide (Running Locally)

If you are developing or contributing to the web application:

Prerequisites

• Node.js 18+ and npm

Running the Web App Locally

cd webapp
npm install
npm run dev

Open http://localhost:5173/ in your browser.

Building Production Assets

cd webapp
npm run build

Production-ready static files are built to webapp/dist/.

---

🧪 Testing

The repository includes automated unit tests using the sanitized fixture test.xls:

# Using Pixi
pixi exec --spec pandas --spec xlrd --spec openpyxl --spec pytest pytest tests/

# Or using pytest directly
pytest tests/

---

🚢 GitHub Pages Deployment

The automated GitHub Actions workflow (.github/workflows/deploy.yml) runs on every push to main or master:

1. Executes the Python test suite on test.xls.
2. Installs Node dependencies and builds the production web app.
3. Automatically deploys the static site to GitHub Pages.

To enable GitHub Pages in your repository:

1. Go to your repository on GitHub: Settings > Pages.
2. Under Build and deployment > Source, select GitHub Actions.

---

📄 License

MIT License. See LICENSE for details.