Metadata-Version: 2.4
Name: protheustools
Version: 0.1.0
Summary: Biblioteca Python com ferramentas para execução de consultas SQL via API REST do Protheus (TOTVS)
License-Expression: MIT
Project-URL: Homepage, https://github.com/antoniocostajr/ProtheusTools
Project-URL: Issues, https://github.com/antoniocostajr/ProtheusTools/issues
Keywords: protheus,totvs,erp,api,query
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: tzlocal>=4.0
Requires-Dist: pytz>=2024.1
Dynamic: license-file

# ProtheusTools

Biblioteca Python com ferramentas para execução de consultas SQL via API REST do Protheus (TOTVS). Os resultados são retornados como `pandas.DataFrame`.

## Instalação

```bash
pip install protheustools
```

## Uso

### Consultar dados do Protheus

```python
from protheustools import exec_query

df = exec_query(
    query="SELECT A1_COD, A1_NOME FROM SA1010 WHERE D_E_L_E_T_ = ''",
    username="seu_usuario",
    password="sua_senha",
    url="https://seu-servidor.protheus.cloudtotvs.com.br:4050/rest_prd",
)

print(df.head())
```

#### Parâmetros de `exec_query`

| Parâmetro       | Tipo    | Padrão  | Descrição                                      |
|-----------------|---------|---------|------------------------------------------------|
| `query`         | `str`   | —       | Query SQL a ser executada no Protheus          |
| `username`      | `str`   | —       | Usuário de autenticação da API REST            |
| `password`      | `str`   | —       | Senha de autenticação da API REST              |
| `url`           | `str`   | —       | URL base da API REST do Protheus               |
| `useDictionary` | `bool`  | `False` | Usa o dicionário de dados do Protheus          |

#### Retorno

Retorna um `pandas.DataFrame` com os resultados da query.

Em caso de erro, levanta exceções:

| Exceção           | Quando ocorre                                                              |
|-------------------|----------------------------------------------------------------------------|
| `ValueError`      | `query`, `url` ou credenciais não informados                               |
| `ValueError`      | Erro ao codificar o payload da requisição                                  |
| `ValueError`      | Redirecionamento inesperado (HTTP 3xx)                                     |
| `ValueError`      | Erro do cliente na API (HTTP 4xx) — inclui a mensagem de erro da API       |
| `ValueError`      | Erro do servidor (HTTP 5xx) — inclui a mensagem de erro                    |
| `ValueError`      | Erro ao decodificar a resposta da API                                      |
| `ConnectionError` | Falha na conexão com a API do Protheus                                     |

### Gerenciar informações de localização e timezone

#### Obter informações de localização

```python
from protheustools import get_locale_info

info = get_locale_info()
print(info)
# {
#     'country': 'BR',
#     'region': 'SP',
#     'city': 'São Paulo',
#     'ip': '192.168.1.1',
#     'hostname': 'meu-pc',
#     'timezone': 'America/Sao_Paulo',
#     'firewall_tcloud': True
# }
```

**Nota:** Esta função verifica automaticamente se seu IP está em um país permitido pelo firewall do TCloud (Brasil, Estados Unidos ou Canadá).

#### Obter timezone atual

```python
from protheustools import get_timezone

tz = get_timezone()
print(tz)  # 'America/Sao_Paulo'
```

#### Definir timezone

```python
from protheustools import set_timezone

set_timezone('America/Sao_Paulo')  # Padrão
# ou
set_timezone('America/New_York')
```

### Detectar Google Colab

```python
from protheustools import is_colab

if is_colab():
    print("Executando no Google Colab")
else:
    print("Executando localmente")
```

## Requisitos

- Python 3.8+
- `requests >= 2.28.0`
- `pandas >= 1.5.0`
- `tzlocal >= 4.0`
