pylascontrol 1.0.0

pylascontrol. Package for personal financial management. Beta version for educational use.

Pylascontrol

A Python package for personal financial management and budget analysis.

Overview

Pylascontrol helps you manage and visualize your personal finances by loading budget data from Excel spreadsheets and generating insightful charts. It's designed for educational purposes and personal use.

Features

• 📊 Load budget data from Excel files in matrix format
• 📈 Generate multiple chart types (line, bar, balance)
• 💰 Track income, expenses, and contributions
• 📅 Organize data by month, category, and type
• 🎨 Visualize financial trends with Matplotlib

Installation

pip install pylascontrol

Or install from source:

git clone https://github.com/rodrigoaraujorosa/pylascontrol.git
cd pylascontrol
pip install -e .

Requirements

• Python >= 3.12
• pandas
• numpy
• matplotlib
• openpyxl

Usage

Loading Budget Data

import pylascontrol as pc

# Load budget data from Excel file
df = pc.load_budget_excel("personal_budget_example.xlsx", year=2025)

# View the data
print(df.head())

The function expects an Excel file with a sheet named "ORÇAMENTO PESSOAL" containing:

• Months as columns (JAN, FEV, MAR, etc.)
• Categories as rows
• Monetary values in cells

Generating Charts

Line Chart (Income vs Expenses)

pc.plot_chart_by_type(df, year=2025, type="line")

Bar Chart (Side-by-side comparison)

pc.plot_chart_by_type(df, year=2025, type="bar")

Balance Chart (Monthly balance)

pc.plot_chart_by_type(df, year=2025, type="saldo")

Data Structure

Input Excel Format

Your Excel file must follow the format shown in personal_budget_example.xlsx:

• Sheet name: Must be named "ORÇAMENTO PESSOAL"
• Column headers (row 1): Month abbreviations (JAN, FEV, MAR, ABR, MAIO, JUN, JUL, AGO, SET, OUT, NOV, DEZ)
• Row labels: Category groups and specific categories
• Group labels (define transaction types):
  • RECEITA: Income categories
  • APORTES: Investment contributions
  • Other groups: Expense categories (e.g., DOMÉSTICAS, TRANSPORTE, ENTRETENIMENTO, SAÚDE, etc.)
• Values: Numeric monetary values in the cells

Important: Developers must structure their spreadsheet according to this format for the package to work correctly. Refer to personal_budget_example.xlsx as a template.

Output DataFrame

The load_budget_excel function returns a DataFrame with the following columns:

• ano: Year of the record
• mes: Month number (1-12)
• tipo: Type of transaction ('receita', 'despesa', 'aporte')
• grupo: Category group (e.g., 'TRANSPORTE', 'ENTRETENIMENTO')
• categoria: Specific category name
• valor: Monetary value

Example

import pylascontrol as pc

# Load data
df = pc.load_budget_excel("personal_budget_example.xlsx", year=2025)

# Generate all chart types
pc.plot_chart_by_type(df, year=2025, type="line")
pc.plot_chart_by_type(df, year=2025, type="bar")
pc.plot_chart_by_type(df, year=2025, type="saldo")

License

MIT License - see LICENSE file for details

Author

Rodrigo de Araujo Rosa
Email: [e-mail]
GitHub: rodrigoaraujorosa

Contributing

This is a beta version for educational purposes. Contributions, issues, and feature requests are welcome!

Disclaimer

This package is intended for personal and educational use. Always verify financial calculations and consult with financial professionals for important decisions.