fundamentalvision 0.1.0
A package for fundamental analysis of stocks on Brazil B3 Exchange.
Requires Python: >=3.6

# Complete Guide to Using the FundamentalVision Application

Welcome to the complete guide for using the FundamentalVision application, a tool for fundamental analysis of stocks on Brazil's B3 stock exchange. This guide will walk you through the installation, configuration, and usage of the application.

## Index

1. [Installation](#installation)
2. [Project Structure](#project-structure)
3. [Initial Configuration](#initial-configuration)
4. [Using the Application](#using-the-application)
5. [Features](#features)
6. [Testing](#testing)
7. [Contribution](#contribution)
8. [License](#license)
9. [Contact](#contact)

## Installation

To install FundamentalVision, use pip:

```bash
pip install fundamentalvision
```

### Dependencies

The package requires the following libraries:

- pandas
- requests
- beautifulsoup4
- streamlit
- plotly
- fundamentus

These dependencies will be installed automatically when you install FundamentalVision.

## Project Structure

The project is structured as follows:

```
fundamentalvision/
â”‚
â”œâ”€â”€ fundamentalvision/        # DiretÃ³rio do cÃ³digo fonte
â”‚   â”œâ”€â”€ __init__.py           # Inicializador do pacote
â”‚   â””â”€â”€ acoes.py              # Obter dados de AÃ§Ãµes
â”‚   â””â”€â”€ dashboard.py          # Renderizar os dados com Streamlit
â”‚   â””â”€â”€ data_handler.py       # ConfiguraÃ§Ã£o do Dataframe
â”‚   â””â”€â”€ app.py                # CÃ³digo principal
â”‚
â”œâ”€â”€ tests/                    # DiretÃ³rio de testes
â”‚   â”œâ”€â”€ __init__.py
â”‚   â””â”€â”€ test_acao.py          # Testes para o mÃ³dulo Acao
â”‚   â””â”€â”€ test_dashboard.py     # Testes para o mÃ³dulo Dashboard
â”‚   â””â”€â”€ test_data_handler.py  # Testes para o DataHandler 
â”‚   â””â”€â”€ test_app.py           # Testes para o App
â”‚
â”œâ”€â”€ LICENCE                   # Licenca do Projeto
â”œâ”€â”€ README.md                 # DocumentaÃ§Ã£o do projeto
â”œâ”€â”€ setup.py                  # Script de configuraÃ§Ã£o para distribuiÃ§Ã£o
â””â”€â”€ requirements.txt          # DependÃªncias do projeto
```

## Initial Configuration

Before running the application, you may need to configure the locale to ensure data is displayed correctly:

```python
import locale

# Set locale
locale.setlocale(locale.LC_ALL, 'pt_BR.UTF-8')
```

## Using the Application

To use FundamentalVision, follow the example below:

```python
import locale
import pandas as pd
import streamlit as st
from fundamentalvision.acoes import Acao
from fundamentalvision.dashboard import Dashboard
import fundamentus

# Set locale
locale.setlocale(locale.LC_ALL, 'pt_BR.UTF-8')

# Retrieve stock data
actions = fundamentus.get_resultado()

# Create and display the dashboard
dashboard = Dashboard(actions)
dashboard.exibir_dashboard()
```

## Features

- **Load Fundamental Data**: Loads financial information for a specific stock.
- **Retrieve Dividends**: Retrieves information on dividends paid by the stock.
- **Get Details**: Obtains additional details about the stock.
- **Track Price Fluctuations**: Collects data on stock price fluctuations.
- **Interactive Visualization**: Displays interactive charts and tables using Streamlit and Plotly.

## Testing

FundamentalVision includes automated tests using pytest. To run the tests, use the following command:

```bash
pytest
```

## Contribution

Contributions are welcome! Feel free to open issues or pull requests. To contribute, follow these steps:

1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature-name`).
3. Make your changes and commit (`git commit -m 'Add new feature'`).
4. Push to the remote repository (`git push origin feature/your-feature-name`).
5. Open a Pull Request.

## License

This project is licensed under the MIT License. See the LICENSE file for more details.

## Contact

For questions or suggestions, contact:

**Author:** Joel Ferreira Heanna dos Reis
**Email:** heannareis@gmail.com

---

### Project Summary (English)

**FundamentalVision** is a tool designed for fundamental stock analysis on Brazilâ€™s B3 stock exchange. It retrieves and processes financial data, providing insights into company performance. The application allows users to visualize financial metrics interactively using Streamlit and Plotly. 

Key features include:
- **Stock data retrieval** from Fundamentus
- **Dividend tracking**
- **Stock price fluctuation analysis**
- **Interactive dashboards** for financial analysis
- **Automated testing** with pytest

The project is open-source and welcomes contributions from the community.