jmulhall00/detailtrialbalance
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

updated README.md file

Browse source
This commit is contained in:
John Mulhall 2026-07-01 10:26:21 -04:00
parent 363f0ec2d6
commit fbfd23b2e6
1 changed files with 415 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

415
README.md
View file

@ -1,2 +1,417 @@
# detailtrialbalance
# MEDITECH Detail Trial Balance Parser
A Streamlit application for parsing MEDITECH Detail Trial Balance PDFs into structured Excel workbooks.
The app allows a user to upload a MEDITECH Detail Trial Balance PDF, extracts transaction-level detail and account summary data, previews the parsed results in the browser, and exports the results to an Excel workbook.
---
## Features
* Upload a MEDITECH Detail Trial Balance PDF
* Parse transaction detail into a structured table
* Parse account-level summary balances
* Preview parsed data inside Streamlit
* Export results to an Excel workbook
* Creates separate Excel tabs for:
* `Transactions`
* `Account Summary`
* Adds basic workbook formatting:
* Report title
* Frozen panes
* Excel tables
* Auto-sized columns
---
## Project Structure
```text
detailtrialbalance/
│
├── streamlit_app.py # Streamlit user interface
├── trial_balance_parser.py # PDF parsing and Excel export logic
├── requirements.txt # Python package dependencies
├── README.md # Project documentation
└── .gitignore # Files excluded from Git
```
---
## Requirements
This project uses Python 3.10+.
Required Python packages:
```txt
streamlit
pdfplumber
pandas
openpyxl
```
---
## Setup
### 1. Clone the repository
```powershell
git clone <your-repository-url>
cd detailtrialbalance
```
### 2. Create a virtual environment
```powershell
python -m venv .venv
```
### 3. Activate the virtual environment
```powershell
.\.venv\Scripts\activate
```
### 4. Install dependencies
```powershell
pip install -r requirements.txt
```
---
## Running the Application
From the project folder, run:
```powershell
streamlit run streamlit_app.py
```
Streamlit will open the application in your browser.
If it does not open automatically, copy the local URL from the terminal and paste it into your browser.
---
## How to Use
1. Open the Streamlit app.
2. Click **Browse files**.
3. Upload a MEDITECH Detail Trial Balance PDF.
4. Click **Parse PDF**.
5. Review the parsed transaction and account summary previews.
6. Click **Download Excel File** to save the parsed workbook.
---
## Output Workbook
The generated Excel workbook contains two sheets.
### Transactions
This sheet includes transaction-level detail such as:
* Account Name
* Account Number
* Journal
* Date
* Batch
* Entry
* Debits
* Credits
* Description
### Account Summary
This sheet includes account-level totals such as:
* Account Name
* Account Number
* Opening Balance
* Total Debits
* Total Credits
* Net Change
* Closing Balance
---
## Main Files
### `streamlit_app.py`
Handles the web interface.
Responsibilities:
* Displays the upload screen
* Accepts PDF uploads
* Calls the parser module
* Displays parsed results
* Provides the Excel download button
### `trial_balance_parser.py`
Contains the reusable parsing and export logic.
Responsibilities:
* Reads the uploaded PDF
* Extracts text using `pdfplumber`
* Parses account headers
* Parses transaction lines
* Parses account summaries
* Cleans repeated page header text from descriptions
* Builds the Excel file in memory
---
## Command-Line Usage
The parser module can also be used outside of Streamlit.
Example:
```python
from trial_balance_parser import parse_trial_balance_to_excel
pdf_path = r"C:\Users\YourName\Downloads\trial_balance.pdf"
out_xlsx = "parsed_trial_balance.xlsx"
excel_bytes, df_txn, df_acct, title = parse_trial_balance_to_excel(pdf_path)
with open(out_xlsx, "wb") as f:
f.write(excel_bytes)
print("Parsed successfully")
print("Transactions:", df_txn.shape)
print("Account Summary:", df_acct.shape)
print("Output:", out_xlsx)
```
---
## Git Ignore Recommendations
Do not commit PDFs, Excel output files, virtual environments, or sensitive local configuration files.
Recommended `.gitignore`:
```gitignore
.venv/
__pycache__/
*.pyc
.env
# Input/output files
*.pdf
*.xlsx
*.xls
# Streamlit local config
.streamlit/secrets.toml
```
---
## Important Data Handling Note
Detail Trial Balance reports may contain sensitive financial information.
Do not commit source PDFs or exported Excel files to the repository.
Only commit source code and documentation.
---
## Troubleshooting
### `git` is not recognized
If PowerShell says:
```text
git : The term 'git' is not recognized
```
Git is either not installed or not added to the Windows PATH.
Install Git for Windows and choose the option:
```text
Git from the command line and also from 3rd-party software
```
Then restart PyCharm and confirm:
```powershell
git --version
```
---
### Streamlit will not start
Make sure the virtual environment is activated:
```powershell
.\.venv\Scripts\activate
```
Then run:
```powershell
streamlit run streamlit_app.py
```
---
### Missing packages
If you see an import error such as:
```text
ModuleNotFoundError: No module named 'pdfplumber'
```
Run:
```powershell
pip install -r requirements.txt
```
---
### Excel export error
If Excel export fails, confirm that the parser returned valid dataframes.
The Streamlit app should display:
* Number of transaction rows
* Number of account summary rows
If both are zero, the PDF text layout may not match the parser’s expected MEDITECH report format.
---
### PDF parses zero rows
This parser depends on text extraction from `pdfplumber`.
A PDF may fail to parse correctly if:
* It is scanned as an image instead of text
* The report format is different from the expected MEDITECH Detail Trial Balance layout
* The account number pattern is different
* Journal/date/entry fields appear in a different order
* The PDF text columns are not extracted cleanly
The current parser expects account headers similar to:
```text
00.00000.00000 - 00 Account Name
```
And transaction lines similar to:
```text
JOURNAL 01/01/26 12345 debit credit description
```
---
## Development Notes
The original parser was written as a standalone script using a hard-coded PDF path and output file path.
The current version separates the logic into a reusable module:
```text
trial_balance_parser.py
```
This allows the same parsing logic to be used by:
* Streamlit
* A command-line script
* Future scheduled jobs
* Future internal web applications
---
## Updating Dependencies
To install dependencies:
```powershell
pip install -r requirements.txt
```
To add a new dependency, install it first:
```powershell
pip install package-name
```
Then update `requirements.txt` manually or regenerate it.
Manual minimal approach:
```txt
streamlit
pdfplumber
pandas
openpyxl
```
Full freeze approach:
```powershell
pip freeze > requirements.txt
```
The manual approach is usually cleaner for this small application.
---
## Pushing Updates to the Repository
After making changes:
```powershell
git status
git add .
git commit -m "Update trial balance parser application"
git push
```
Before pushing, confirm that no PDFs, Excel exports, `.env` files, or virtual environment folders are being committed.
---
## Future Enhancements
Potential improvements:
* Add validation checks comparing transaction totals to account summary totals
* Add better error handling for unsupported PDF layouts
* Add support for multiple PDF uploads
* Add a reconciliation summary tab
* Add logging
* Add user authentication if deployed internally
* Add configurable output file names
* Add support for additional MEDITECH financial reports
---
## Application Summary
This application converts MEDITECH Detail Trial Balance PDFs into structured Excel output with minimal manual cleanup. It is designed to support finance, reporting, and data analysis workflows where PDF-based reports need to be transformed into spreadsheet-ready datasets.