Metadata-Version: 2.4
Name: maxsciencelib
Version: 0.0.13
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"
Requires-Dist: fastexcel; 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             |

---

## leitura_fipe

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 leitura_fipe

df_fipe_categoria = leitura_fipe()

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.


---

## 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       |

---

## media-saneada

Funções para cálculo de **média saneada**, removendo outliers de forma iterativa com base no **coeficiente de variação (CV)**, garantindo maior robustez estatística em conjuntos de valores numéricos.

São disponibilizados duas funções:

* uma função **core**, para uso direto com listas, arrays ou `polars.Series`
* uma função **Expr**, para uso eficiente em pipelines **Polars** (`group_by`, `select`, `with_columns`)

### Funcionalidades

* Cálculo de média robusta com saneamento iterativo
* Remoção automática de outliers com base em:

  * média
  * desvio padrão
  * coeficiente de variação (CV)
* Fallback seguro para **mediana**
* Controle de:

  * número mínimo de amostras
  * CV máximo permitido
* Compatível com:

  * `list`
  * `numpy.ndarray`
  * `polars.Series`
* Integração nativa com **Polars Expressions (`Expr`)**

### Requisitos

* Python **3.10+** (recomendado)
* Polars
* NumPy


### Dependências

```bash
pip install polars numpy
```

---

### `media_saneada`

Calcula a média saneada de um conjunto de valores numéricos.

#### Assinatura

```python
media_saneada(
    valores,
    min_amostras: int = 3,
    cv_max: float = 0.25
) -> float | None
```

#### Parâmetros

| Parâmetro      | Tipo                                | Descrição                                |
| -------------- | ----------------------------------- | ---------------------------------------- |
| `valores`      | `list` | `np.ndarray` | `pl.Series` | Conjunto de valores numéricos            |
| `min_amostras` | `int`                               | Número mínimo de amostras permitidas     |
| `cv_max`       | `float`                             | Coeficiente de variação máximo aceitável |

#### Retorno

```python
float | None
```

* Retorna a **média saneada** se o CV estiver dentro do limite
* Caso contrário, retorna a **mediana** dos últimos `min_amostras` valores
* Retorna `None` se não houver valores válidos

#### Uso básico

```python
from maxsciencelib import agrupamento

media = media_saneada([100, 102, 98, 500, 101])
```

---

### `media_saneada_expr`

Retorna uma **Polars Expression (`Expr`)** para cálculo de média saneada em operações vetorizadas.

Indicada para uso em:

* `group_by().agg()`
* `select()`
* `with_columns()`

#### Assinatura

```python
media_saneada_expr(
    coluna: str,
    min_amostras: int = 3,
    cv_max: float = 0.25
) -> pl.Expr
```

#### Parâmetros

| Parâmetro      | Tipo    | Descrição                                |
| -------------- | ------- | ---------------------------------------- |
| `coluna`       | `str`   | Nome da coluna numérica                  |
| `min_amostras` | `int`   | Número mínimo de amostras permitidas     |
| `cv_max`       | `float` | Coeficiente de variação máximo aceitável |

#### Retorno

```python
polars.Expr
```

#### Exemplo com `group_by`

```python
import polars as pl
from maxsciencelib.estatistica import media_saneada_expr

df = pl.DataFrame({
    "grupo": ["A", "A", "A", "A", "B", "B", "B"],
    "valor": [100, 102, 98, 500, 50, 52, 51]
})

resultado = (
    df
    .group_by("grupo")
    .agg(
        media_saneada_expr("valor").alias("media_saneada")
    )
)
```

### Observações importantes

* A função:

  * **não utiliza `apply` Pandas**
  * mantém lógica estatística **idêntica à versão Pandas**
  * evita cálculos desnecessários
* A versão `Expr`:

  * permite integração total com pipelines Polars
  * pode ser usada em modo **Lazy**
* Algoritmo iterativo → não 100% vetorizável, mas seguro e robusto

## Licença

The MIT License (MIT)

## Autores

Daniel Antunes Cordeiros
