How mayureshw/mftools works
1. Overall shape
- This repository is a Python batch-processing tool for mutual fund portfolio analysis.
- It is not a web app or service; the architecture is a file-in / file-out pipeline: user-provided statements and fund master data are read, normalized, analyzed, and rendered into text reports.
2. Main entry points
- pfviews.py is the primary executable for report generation. It orchestrates the full portfolio analysis workflow and writes the report files.
- amfi2gfg.py is a separate utility focused on one data-preparation task: building grandfathered NAV data from AMFI.
- The remaining modules are support libraries rather than standalone entry points.
3. Input sources and external boundaries
- The tool consumes CAMS registrar statements: transaction history (txns.xls) and current valuation (bals.xls).
- It also consumes Value Research fund analysis data, converted from spreadsheet to CSV before use.
- Optional reference data comes from:
- cii.json for Cost Inflation Index values.
- gfnav.json for grandfathered NAV values.
- These files are treated as external or semi-external inputs, usually located under MFDOCSDIR / PFDATDIR.
4. Configuration boundary
- conf.py likely centralizes environment-driven paths and runtime settings.
- The runtime depends on environment variables described in the README:
- XLS2PYSPECDIR for spreadsheet parsing templates,
- MFDOCSDIR for shared fund documents,
- PFDATDIR for personal statement files,
- PYTHONPATH to expose the xls2pyobj dependency.
- This means the application is configured primarily by filesystem layout plus environment, not by a database or server config.
5. Data ingestion and normalization
- pfdata.py is the likely ingestion/model layer.
- Its responsibility is to parse registrar statements and fund metadata into a common internal representation: funds, holdings, buy/sell transactions, valuation snapshots, and reference attributes.
- This is the main boundary where heterogeneous inputs are normalized into a consistent portfolio data model.
6. Reference-data enrichment
- cii.json is used to compute indexed cost and indexed gain where applicable.
- gfnav.json is used to compute grandfathered gains for equity funds with holdings or sales spanning the 31 Jan 2018 cutoff.
- The application enriches transaction/holding data with these auxiliary datasets before report generation.
7. Analysis and business logic
- reports.py likely contains the core computation and formatting logic for:
- current portfolio value, cost, gain, CAGR,
- unrealized gain per buy lot,
- realized gain per sale transaction,
- cashflow totals by financial year and transaction type.
- The business rules include tax-related distinctions such as equity vs debt treatment and holding-period thresholds.
- This layer is where portfolio math, gain classification, and grouping logic live.
8. Report generation outputs
- pfviews.py produces plain-text report artifacts in the current working directory:
- pfreports.txt for portfolio summaries and category views,
- pfgainreport.txt for unrealized gains,
- rgainreport.txt for realized gains,
- cashflowreport.txt for year-wise cashflow totals.
- The output format is intentionally simple and human-readable, suggesting the tool is designed for manual review and tax/portfolio reconciliation.
9. AMFI utility flow
- amfi2gfg.py is a focused side pipeline that retrieves 31-Jan-2018 NAV data from AMFI and writes it into the gfnav.json format expected by the main reporting flow.
- This utility supports one specific enrichment step in the main architecture rather than participating in daily report generation.
10. Technology and operational profile
- The repo is pure Python 3 with no server runtime, no persistent database, and no frontend.
- It relies on local files, spreadsheet conversion tooling, and the xls2pyobj package for reading Excel-derived inputs.
- The architecture is therefore best represented as:
- External documents and reference files → Python parsing/normalization layer → analysis/reporting layer → text reports.
Main entry points: pfdata.py Portfolio data · pfviews.py Runner · reports.py Reports · conf.py Config
Components 16
Inputs
External statements and reference datasets consumed by the batch pipeline.
- CAMS txns · Transaction history input from CAMS registrar statements.
- CAMS bals · Current valuation input from CAMS registrar statements.
- VR data · Fund analysis and master data converted from spreadsheet to CSV.
- CII data · Cost Inflation Index values used for indexed cost and gain.
cii.json - GF NAV · Grandfathered NAV values for equity tax calculations.
gfnav.json - XLS parser · Spreadsheet parsing helper exposed through PYTHONPATH.
- AMFI NAV · AMFI 31-Jan-2018 NAV source used to populate grandfathered NAV data.
Core
Parsing, normalization, and portfolio analysis logic.
- Config · Environment-driven paths and runtime settings.
conf.py - Portfolio data · Parses statements and fund metadata into the internal portfolio model.
pfdata.py - Reports · Computes holdings, gains, cashflows, and report sections.
reports.py - Runner · Orchestrates the full portfolio workflow and writes report files.
pfviews.py
Outputs
Human-readable report artifacts written by the runner.
- Portfolio report · Summary and category views for the portfolio.
- Unrealized gains · Per-lot unrealized gain report.
- Realized gains · Sale-level realized gain report.
- Cashflows · Year-wise cashflow totals and transaction breakdowns.
Utility
Standalone data-preparation helper for grandfathered NAVs.
- AMFI prep · Builds grandfathered NAV data from AMFI source data.
amfi2gfg.py
Connections 16
- CAMS txns → Portfolio data: parse · Transaction history is normalized into the portfolio model.
- CAMS bals → Portfolio data: parse · Current valuation snapshots are normalized into the portfolio model.
- VR data → Portfolio data: enrich · Fund metadata and analysis data are attached during ingestion.
- XLS parser → Portfolio data: read xls · Excel parsing support for registrar statements and derived sheets.
- Config → Portfolio data: paths · Provides filesystem locations and runtime settings for ingestion.
- Config → Reports: settings · Controls report-time paths and runtime behavior.
- Portfolio data → Reports: portfolio model · Normalized holdings, transactions, and reference attributes feed analysis.
- CII data → Reports: indexed cost · Inflation index values support indexed cost and gain calculations.
- GF NAV → Reports: tax basis · Grandfathered NAV values support equity gain calculations.
- Reports → Runner: render · Computed sections are assembled into final report files.
- Runner → Portfolio report: write · Writes the main portfolio summary report.
- Runner → Unrealized gains: write · Writes unrealized gain details.
- Runner → Realized gains: write · Writes realized gain details.
- Runner → Cashflows: write · Writes cashflow summaries.
- AMFI NAV → AMFI prep: source · AMFI source data is used to derive grandfathered NAV entries.
- AMFI prep → GF NAV: build · Produces the gfnav.json reference used by the main report flow.