product
This commit is contained in:
229
README.md
Normal file
229
README.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# ACH File Parser
|
||||
|
||||
A robust Python-based parser for ACH (Automated Clearing House) transaction report files with fixed-width format.
|
||||
|
||||
## Features
|
||||
|
||||
✅ **Flexible Field Extraction**
|
||||
- Parses delimiter-separated fields (using `-` as separator)
|
||||
- Extracts last column as remarks to handle any pattern (P-pattern or C-pattern)
|
||||
- Supports multi-page reports (form feed separated)
|
||||
|
||||
✅ **Comprehensive Data Extraction**
|
||||
- Report metadata (Report ID, Bank Name, Branch, Currency, Maker/Checker IDs)
|
||||
- Transaction details (SNO, Account, Customer Name, Amount, Date, Status)
|
||||
- Summary totals (Transaction counts and amounts)
|
||||
|
||||
✅ **Robust Logging**
|
||||
- Console output with timestamps
|
||||
- Rolling file logs (10MB max per file, 5 backups)
|
||||
- Debug logging for troubleshooting
|
||||
|
||||
✅ **Multiple Output Formats**
|
||||
- Console display with formatted tables
|
||||
- JSON export for data processing
|
||||
- Extensible for CSV/Excel export
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
ach_ui_dbtl_file_based/
|
||||
├── main.py # Application entry point
|
||||
├── ach_parser.py # ACH parser logic
|
||||
├── export_to_json.py # JSON export utility
|
||||
├── logging_config.py # Logging configuration
|
||||
├── requirements.txt # Python dependencies
|
||||
├── .gitignore # Git ignore rules
|
||||
├── .env.example # Environment variables template
|
||||
└── parsed_ach_data.json # Exported transaction data
|
||||
```
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### 1. Create Virtual Environment
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 3. Configure Environment (Optional)
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### View Parsed Data in Console
|
||||
```bash
|
||||
source venv/bin/activate
|
||||
python ach_parser.py
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
REPORT METADATA
|
||||
================================================================================
|
||||
REPORT_ID : TF0504-01
|
||||
BANK_NAME : MURSHIDABAD D C C B LTD.
|
||||
RUN_DATE : 19/01/2026 10:32
|
||||
BRANCH : 99944
|
||||
CURRENCY : INR
|
||||
MAKER_ID : 0009991
|
||||
CHECKER_ID : 0000000
|
||||
|
||||
SNO CUST ACCT CUSTOMER NAME DATE AMOUNT REMARKS
|
||||
================================================================================
|
||||
1 122001447784 Mr. ATUL DEY 19/01/26 26.26 P0126049D07E0?IOCL LPG SUBSIDY
|
||||
2 122005893950 Mr. SUMEJAHAN BIBI 19/01/26 26.25 P01260491D89C?HPCL LPG SUBSIDY
|
||||
...
|
||||
```
|
||||
|
||||
### Export to JSON
|
||||
```bash
|
||||
python export_to_json.py
|
||||
```
|
||||
|
||||
**Output:** `parsed_ach_data.json`
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"report_id": "TF0504-01",
|
||||
"bank_name": "MURSHIDABAD D C C B LTD.",
|
||||
...
|
||||
},
|
||||
"summary": {
|
||||
"tot_processed": {
|
||||
"debit_count": "0",
|
||||
"credit_count": "178",
|
||||
"credit_amount": "41132.29"
|
||||
}
|
||||
},
|
||||
"transactions": [
|
||||
{
|
||||
"sno": "1",
|
||||
"cust_acct": "122001447784",
|
||||
"lpg_susp": "93615999445",
|
||||
"customer_name": "Mr. ATUL DEY",
|
||||
"jrnl_no": "514103",
|
||||
"date": "19/01/26",
|
||||
"amount": "26.26",
|
||||
"sys": "23-DEP-PROCESSED",
|
||||
"message": "23-DEP-PROCESSED",
|
||||
"cr_suspense": "",
|
||||
"suspense_msg": "",
|
||||
"remarks": "P0126049D07E0?IOCL LPG SUBSIDY"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Transaction Field Details
|
||||
|
||||
| Field | Description | Example |
|
||||
|-------|-------------|---------|
|
||||
| SNO | Serial Number | 1, 2, 3... |
|
||||
| CUST_ACCT | Customer Account Number | 122001447784 |
|
||||
| LPG_SUSP | LPG Suspense Code | 93615999445 |
|
||||
| CUSTOMER_NAME | Customer Name | Mr. ATUL DEY |
|
||||
| JRNL_NO | Journal Number | 514103 |
|
||||
| DATE | Transaction Date | 19/01/26 |
|
||||
| AMOUNT | Transaction Amount | 26.26 |
|
||||
| SYS | System Status Code | 23-DEP-PROCESSED |
|
||||
| MESSAGE | Processing Message | 23-DEP-PROCESSED |
|
||||
| REMARKS | Remarks/Reference Code | P0126049D07E0?IOCL LPG SUBSIDY |
|
||||
|
||||
## Supported Remarks Patterns
|
||||
|
||||
The parser flexibly handles different remarks patterns:
|
||||
- **P-pattern**: `P0126049D07E0?IOCL LPG SUBSIDY`
|
||||
- **C-pattern**: `C012634266856?MDM BURWAN BLOCK`
|
||||
- **Any pattern**: Takes the last column regardless of prefix
|
||||
|
||||
## Logging
|
||||
|
||||
Logs are written to:
|
||||
- **Console**: Real-time output during execution
|
||||
- **File**: `logs/app.log` (rotating, 10MB max, 5 backups)
|
||||
|
||||
Log levels can be configured in `logging_config.py`:
|
||||
```python
|
||||
from logging_config import setup_logging
|
||||
setup_logging(log_level=logging.DEBUG) # Change to DEBUG for verbose output
|
||||
```
|
||||
|
||||
## Example: Using in Your Code
|
||||
|
||||
```python
|
||||
from ach_parser import ACHParser, get_logger
|
||||
from logging_config import setup_logging
|
||||
|
||||
# Setup logging
|
||||
setup_logging()
|
||||
logger = get_logger(__name__)
|
||||
|
||||
# Parse ACH file
|
||||
parser = ACHParser('path/to/ach_file.txt')
|
||||
transactions, metadata, summary = parser.parse()
|
||||
|
||||
# Access data
|
||||
print(f"Parsed {len(transactions)} transactions")
|
||||
for txn in transactions:
|
||||
print(f"{txn['sno']}: {txn['customer_name']} - ₹{txn['amount']}")
|
||||
|
||||
# Export to JSON
|
||||
from export_to_json import export_to_json
|
||||
export_to_json(transactions, metadata, summary, 'output.json')
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
To test with sample data:
|
||||
```bash
|
||||
python ach_parser.py
|
||||
```
|
||||
|
||||
The parser includes debug logging for troubleshooting:
|
||||
```python
|
||||
logger = get_logger(__name__)
|
||||
logger.debug(f"Parsing transaction: {line}")
|
||||
```
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- Assumes fixed-width format with `-` delimiters between main fields
|
||||
- Remarks must be the last column (no fields after remarks)
|
||||
- Form feeds (`\f`) are used to separate pages
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] CSV export support
|
||||
- [ ] Excel export support
|
||||
- [ ] Database storage integration
|
||||
- [ ] Validation and error correction
|
||||
- [ ] Support for different ACH report formats
|
||||
- [ ] Batch processing multiple files
|
||||
- [ ] Web API for file upload and parsing
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **python-dotenv**: Environment variable management
|
||||
- **pytest**: Testing framework
|
||||
- **black**: Code formatting
|
||||
- **flake8**: Code linting
|
||||
|
||||
See `requirements.txt` for exact versions.
|
||||
|
||||
## License
|
||||
|
||||
Internal use only.
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions, check the logs in `logs/app.log` for detailed error information.
|
||||
Reference in New Issue
Block a user