pylascontrol 1.0.0
pylascontrol. Package for personal financial management. Beta version for educational use.
License: MIT
Requires Python: >=3.12

# 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

```sh
pip install pylascontrol
```

Or install from source:

```sh
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

```python
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)

```python
pc.plot_chart_by_type(df, year=2025, type="line")
```

#### Bar Chart (Side-by-side comparison)

```python
pc.plot_chart_by_type(df, year=2025, type="bar")
```

#### Balance Chart (Monthly balance)

```python
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

```python
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: rodrigoaraujo.r@gmail.com  
GitHub: [rodrigoaraujorosa](https://github.com/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.