PyFinBot

Table of Contents

• Introduction
• Key Features
• Planned Milestones
• Testing
• License

Introduction

PyFinBot is a lightweight, extensible financial tracking tool built in Python, designed to help users manage and analyze their stock trading activity. By leveraging relational database design and SQL-based reporting, PyFinBot offers precise insights into holdings, transaction history, and capital gains or losses per financial year. Ideal for personal investors or hobbyist traders, it serves as a transparent and customizable alternative to spreadsheet-based tracking.

🚀 Key Features

• 📊 Transaction Recording: Track Buy/Sell orders with support for fees, prices, values, and financial year grouping.
• 📆 Holdings Snapshot: Query real-time or historical stock units held as of any given date.
• 💰 Capital Gain/Loss Calculation: Determine net gains/losses per stock by financial year using average cost basis.
• 🔗 Relational Database Design: Clean, normalized schema to ensure data integrity and efficient queries.
• 🔐 Multi-user Support (optional): Track transactions per user if needed.
• 📦 Modular Architecture: Built to be extended with additional features like tax reports, visualizations, or API integration.

🎯 Planned Milestones

1. ✅ MVP – Schema design, basic transaction insertion, and SQL-based queries.
2. 🔄 Import System – CSV or Excel import of stock transactions.
3. 📈 Reporting Module – Generate FY-based reports for holdings and capital gains.
4. 🧮 FIFO Method Support – Accurate gain/loss computation based on FIFO accounting.
5. 🌐 CLI Interface – Interact via command line with exportable summaries.
6. 🖥️ Web Dashboard (optional) – View and interact with data through a simple Flask or Django front end.

Testing

PyFinBot includes a comprehensive suite of unit tests to ensure the reliability and stability of its features. Tests cover various aspects of the core functionality.

Running Tests

To run the tests, navigate to the project root directory and execute the following command:

bash python -m unittest discover -s tests

Create a virtual environment and install the required dependencies: bash alembic init src/pyfinbot/alembic

Create a new migration script for the initial schema: bash alembic revision --autogenerate -m "Initial schema"

bash alembic upgrade head

License

PyFinBot is licensed under the MIT License, see LICENSE for more information.