protheustools 0.1.0

Biblioteca Python com ferramentas para execução de consultas SQL via API REST do Protheus (TOTVS)

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

pip install protheustools

Uso

Consultar dados do Protheus

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

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

from protheustools import get_timezone

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

Definir timezone

from protheustools import set_timezone

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

Detectar Google Colab

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