Metadata-Version: 2.4
Name: maxsciencelib
Version: 0.0.12
Summary: Biblioteca de funções compartilhadas do time de Data Science da Maxpar
Author-email: Daniel Antunes <daniel.ant.cord@gmail.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: polars>=0.20.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: snowflake-connector-python>=3.5.0
Requires-Dist: tableauserverclient>=0.25
Provides-Extra: selenium
Requires-Dist: selenium>=4.15; extra == "selenium"
Dynamic: license-file

# MaxScienceLib

Biblioteca com funções aplicadas a rotina do cientista de dados na Maxpar

## Como usar

Instale com:

```bash
pip install maxscientelib
```

Use no seu código:

```python
from maxsciencelib import leitura_snowflake
```

---

## leitura-snowflake

Biblioteca Python para leitura de dados do **Snowflake** de forma simples, segura e performática, retornando os resultados diretamente como **DataFrame Polars**.

A biblioteca abstrai toda a complexidade de conexão, autenticação via `externalbrowser` e execução de queries, permitindo que o usuário execute consultas com apenas **uma função**.



### Funcionalidades

- Conexão automática com Snowflake via `externalbrowser`
- Execução de queries SQL
- Retorno direto em **Polars DataFrame**
- Uso nativo de **Apache Arrow** (alta performance)
- Silenciamento de logs e warnings internos
- Fechamento seguro de conexão e cursor


### Requisitos

- Python **3.11+** (recomendado)
- Acesso ao Snowflake configurado no navegador

### Dependências

```bash
pip install snowflake-connector-python polars pyarrow
```

### Uso básico

```python
from leitura_snowflake import leitura_snowflake

query = """
SELECT *
FROM MINHA_TABELA
LIMIT 1000
"""

df = leitura_snowflake(
    email_corporativo="nome.sobrenome@empresa.com",
    token_account="abc123.us-east-1",
    query=query
)

df.head()
```

O retorno será um objeto:

```python
polars.DataFrame
```

| Parâmetro           | Tipo  | Descrição                                         |
| ------------------- | ----- | ------------------------------------------------- |
| `email_corporativo` | `str` | Email corporativo utilizado no login do Snowflake |
| `token_account`     | `str` | Identificador da conta Snowflake                  |
| `query`             | `str` | Query SQL a ser executada                         |

--- 

## leitura-tableau

Biblioteca Python para leitura de dados do **Tableau Server** de forma simples, segura e performática, retornando os resultados diretamente como **DataFrame Polars**.

A biblioteca abstrai toda a complexidade de autenticação via **Personal Access Token**, conexão com o Tableau Server (HTTP/HTTPS) e download da view, permitindo que o usuário consuma dados com apenas **uma função**.


### Funcionalidades

* Autenticação via **Personal Access Token (PAT)**
* Conexão automática com Tableau Server (fallback HTTP → HTTPS)
* Download de views diretamente do Tableau
* Retorno direto em **Polars DataFrame**
* Leitura eficiente de CSV em memória
* Silenciamento de warnings internos
* Encerramento seguro da sessão (`sign_out`)

### Requisitos

* Python **3.10+** (recomendado)
* Acesso ao Tableau Server
* Personal Access Token ativo no Tableau


### Dependências

```bash
pip install tableauserverclient polars pyarrow
```


### Uso básico

```python
from maxsciencelib.leitura_tableau import leitura_tableau

df = leitura_tableau(
    nome_token="meu_token_tableau",
    token_acesso="XXXXXXXXXXXXXXXXXXXXXXXX",
    view_id="abcd1234-efgh-5678"
)

df.head()
```

### Retorno

O retorno da função será um objeto:

```python
polars.DataFrame
```

### Parâmetros

| Parâmetro      | Tipo  | Descrição                                           |
| -------------- | ----- | --------------------------------------------------- |
| `nome_token`   | `str` | Nome do Personal Access Token cadastrado no Tableau |
| `token_acesso` | `str` | Token de acesso pessoal do Tableau                  |
| `view_id`      | `str` | Identificador da view no Tableau Server             |

---

## fipes-categoria

Biblioteca Python para **categorização de veículos com base na Tabela FIPE**, utilizando **quantis dinâmicos por tipo de veículo** e separação entre **veículos antigos e recentes**, retornando os resultados em **Polars DataFrame**.

A biblioteca abstrai toda a lógica estatística de cálculo de quantis, tratamento de dados e categorização, permitindo que o usuário obtenha a classificação do veículo com **apenas uma função**.

### Funcionalidades

* Leitura da Tabela FIPE diretamente de arquivo Excel
* Padronização automática de colunas
* Tratamento do ano (`ZERO KM` → ano vigente)
* Criação da chave `FIPE-ANO`
* Separação automática entre:

  * Veículos **antigos** (`ano < 2015`)
  * Veículos **recentes** (`ano ≥ 2015`)
* Categorização baseada em quantis por tipo de veículo:

  * **Antigo Popular**
  * **Antigo Premium**
  * **Popular**
  * **Intermediário**
  * **Premium**
* Processamento totalmente vetorizado em **Polars**
* Alta performance para grandes volumes de dados
* Interface simples e pronta para uso analítico

### Requisitos

* Python **3.10+** (recomendado)
* Acesso ao arquivo da Tabela FIPE
* Estrutura de colunas compatível com a base FIPE padrão

### Dependências

```bash
pip install polars pyarrow fastexcel
```

> O pacote `fastexcel` é utilizado pelo Polars para leitura eficiente de arquivos Excel.

### Uso básico

```python
from maxsciencelib.fipes_categoria import fipes_categoria

df_fipe_categoria = fipes_categoria()

df_fipe_categoria.head()
```

### Retorno

A função retorna um objeto do tipo:

```python
polars.DataFrame
```

com as seguintes colunas:

| Coluna      | Descrição                                    |
| ----------- | -------------------------------------------- |
| `fipe_ano`  | Código FIPE concatenado com o ano do veículo |
| `ano`       | Ano do veículo                               |
| `marca`     | Marca do veículo                             |
| `modelo`    | Modelo do veículo                            |
| `categoria` | Categoria FIPE calculada                     |


### Lógica de categorização

A categorização é feita **por tipo de veículo**, seguindo as regras abaixo:

#### Veículos antigos (`ano < 2015`)

| Condição      | Categoria      |
| ------------- | -------------- |
| `valor ≤ P60` | Antigo Popular |
| `valor > P60` | Antigo Premium |

#### Veículos recentes (`ano ≥ 2015`)

| Condição            | Categoria     |
| ------------------- | ------------- |
| `valor ≤ P50`       | Popular       |
| `P50 < valor ≤ P70` | Intermediário |
| `valor > P70`       | Premium       |

> Os percentis são calculados **dinamicamente por `tipo_veiculo`**.

---

## upload-sharepoint

Biblioteca Python para **upload automático de arquivos no SharePoint** utilizando automação via navegador (**Selenium + Microsoft Edge**).

A função abstrai toda a complexidade de interação com a interface web do SharePoint, permitindo realizar o upload de **todos os arquivos de um diretório local** com apenas **uma chamada de função**.

> Esta funcionalidade utiliza automação de UI e depende do layout do SharePoint. Recomendada para uso interno e controlado.


### Funcionalidades

- Upload automático de múltiplos arquivos para SharePoint
- Suporte a upload em massa a partir de um diretório local
- Automação via Microsoft Edge (Selenium)
- Detecção automática de sobrescrita (`Substituir tudo`)
- Controle de timeout e tempo de espera
- Fechamento seguro do navegador


### Requisitos

- Python **3.11+** (recomendado)
- Microsoft Edge instalado
- Edge WebDriver compatível
- Acesso ao SharePoint via navegador (login manual)


### Dependências

```bash
pip install selenium
````

> Caso esteja usando a biblioteca `maxsciencelib`, recomenda-se instalar com:
>
> ```bash
> pip install maxsciencelib[selenium]
> ```



### Uso básico

```python
from maxsciencelib import upload_sharepoint

upload_sharepoint(
    url_sharepoint="https://autoglass365.sharepoint.com/sites/XXXXXXXXX/Shared%20Documents/Forms/AllItems.aspx",
    diretorio=r"C:\Users\usuario\Desktop\arquivos_para_upload"
)
```


### Comportamento da função

* Todos os arquivos presentes no diretório informado serão enviados
* Caso o arquivo já exista no SharePoint, a função tentará clicar em **“Substituir tudo”**
* O navegador será fechado automaticamente ao final do processo
* Em caso de erro, a função lança exceções claras (`FileNotFoundError`, `RuntimeError`)


### Parâmetros

| Parâmetro          | Tipo  | Descrição                                                               |
| ------------------ | ----- | ----------------------------------------------------------------------- |
| `url_sharepoint`   | `str` | URL do diretório do SharePoint onde os arquivos serão carregados        |
| `diretorio`        | `str` | Caminho local contendo **apenas** os arquivos a serem enviados          |
| `tempo_espera_fim` | `int` | Tempo (em segundos) de espera após o upload antes de fechar o navegador |
| `timeout`          | `int` | Timeout máximo (em segundos) para espera de elementos na interface      |


### Retorno

```python
None
```

A função não retorna valores.
Caso ocorra algum erro durante o processo, uma exceção será lançada.



Perfeito. Segue o **markdown pronto**, no mesmo **padrão de documentação** do `## leitura-tableau`, já no tom de biblioteca corporativa para você **copiar e colar direto no README**.

---

## agrupar-produto

Biblioteca Python para **padronização e agrupamento de descrições de produtos automotivos**, abstraindo regras complexas de **marca**, **lado (LE/LD)** e **casos específicos por tipo de peça**, retornando o resultado diretamente no **DataFrame original** com uma nova coluna agrupada.

A biblioteca foi desenhada para que o usuário precise chamar **apenas uma função**, informando o **DataFrame**, a **coluna de origem** e o **nome da nova coluna**, mantendo a coluna original intacta.


### Funcionalidades

* Agrupamento automático por **tipo de produto**

  * Vidro
  * Retrovisor
  * Farol / Lanterna
* Remoção padronizada de **marca**
* Remoção padronizada de **lado (LE / LD / E / D)**
* Tratamento de **casos específicos**
* Limpeza de sufixos como:

  * `EXC`
  * `AMT`
  * `AMT CNT`
  * `AMT AER`
* Preserva a coluna original
* Compatível com valores nulos (`NaN`)
* Interface simples, orientada a **DataFrame**
* Pronta para uso em pipelines analíticos e feature engineering


### Requisitos

* Python **3.9+**
* Pandas

### Dependências

```bash
pip install pandas
```


### Uso básico

```python
from maxsciencelib.agrupamento import agrupar_produto

df = agrupar_produto(
    df,
    coluna_origem="produto_descricao",
    coluna_nova="produto_agrupado"
)

df.head()
```

### Uso com controle de regras

```python
df = agrupar_produto(
    df,
    coluna_origem="produto_descricao",
    coluna_nova="produto_agrupado",
    agrupar_marca=False,
    agrupar_lado=True
)
```

### Retorno

A função retorna o próprio DataFrame com a nova coluna adicionada:

```python
pandas.DataFrame
```

### Parâmetros

| Parâmetro       | Tipo      | Descrição                                                      |
| --------------- | --------- | -------------------------------------------------------------- |
| `df`            | DataFrame | DataFrame de entrada                                           |
| `coluna_origem` | `str`     | Nome da coluna que contém a descrição original do produto      |
| `coluna_nova`   | `str`     | Nome da nova coluna com o produto agrupado                     |
| `agrupar_marca` | `bool`    | Remove marcas do produto (`True` por padrão)                   |
| `agrupar_lado`  | `bool`    | Remove indicação de lado (LE / LD / E / D) (`True` por padrão) |


### Regras de agrupamento (interno)

A função identifica automaticamente o tipo de produto com base na descrição:

| Tipo identificado | Regra aplicada                    |
| ----------------- | --------------------------------- |
| `VID`             | Agrupamento de vidros             |
| `RETROV`          | Agrupamento de retrovisores       |
| `FAROL` / `LANT`  | Agrupamento de faróis e lanternas |
| Outros            | Mantém a descrição original       |


## Licença

The MIT License (MIT)

## Autores

Daniel Antunes Cordeiros
