catworld-sdk
Cliente oficial Python para a API Catworld.
Instalação
pip install catworld-sdk
Início rápido
from catworld import CatworldClient
with CatworldClient("https://seu-catworld.exemplo.com", "cw_live_...") as client:
result = client.query("SELECT * FROM banco_horas", dataset_id="<dataset-id>")
print(result["rows"])
Autenticação
Passe a URL base do seu Catworld e um token de API gerado na interface:
client = CatworldClient(
base_url="https://seu-catworld.exemplo.com",
token="cw_live_...",
timeout=30, # timeout padrão das requisições HTTP (segundos)
)
Use como context manager (with) para fechar a conexão automaticamente, ou chame client.close() manualmente.
Métodos
query(sql, dataset_id=None, project_id=None, timeout=30, limit=10000)
Executa uma query SQL somente leitura.
Contexto de schema — passe dataset_id ou project_id para que o servidor resolva automaticamente tabelas não qualificadas para o schema correto:
# Com dataset_id: resolve tabelas do schema desse dataset
result = client.query("SELECT * FROM banco_horas", dataset_id="<dataset-id>")
# Com project_id: resolve tabelas de qualquer dataset do projeto
result = client.query("SELECT * FROM banco_horas", project_id="<project-id>")
# Sem contexto: você precisa qualificar manualmente com schema.tabela
result = client.query("SELECT * FROM meu_schema.banco_horas")
Se a mesma tabela existir em mais de um schema do contexto informado, o servidor retorna erro pedindo que você qualifique com schema.tabela.
Retorno:
{
"columns": ["col1", "col2", ...],
"rows": [{"col1": ..., "col2": ...}, ...],
"rowCount": 4923,
"truncated": False, # True se o resultado foi cortado pelo limit
"executionTimeMs": 312,
}
Parâmetros:
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
sql |
str |
— | Query SQL (apenas SELECT/WITH) |
dataset_id |
str |
None |
ID do dataset para resolver schemas |
project_id |
str |
None |
ID do projeto para resolver schemas |
timeout |
int |
30 |
Timeout da query no servidor (segundos, máx. 120) |
limit |
int |
10000 |
Número máximo de linhas retornadas |
upload(path, dataset_id, mode="replace", key_column=None, poll_interval=2)
Envia um arquivo para um dataset.
result = client.upload(
"dados.xlsx",
dataset_id="<dataset-id>",
mode="replace", # "replace" sobrescreve, "append" adiciona, "upsert" atualiza/insere
key_column="id", # obrigatório para mode="upsert"
)
print(result["status"], result["rowCount"])
O método aguarda até a importação ser concluída. O arquivo pode ser .csv, .xlsx ou .xls.
Parâmetros:
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
path |
str | Path |
— | Caminho do arquivo local |
dataset_id |
str |
— | ID do dataset de destino |
mode |
str |
"replace" |
Modo de importação: replace, append ou upsert |
key_column |
str |
None |
Coluna chave para mode="upsert" |
poll_interval |
float |
2 |
Intervalo de polling em segundos |
projects()
Lista todos os projetos acessíveis pelo token.
projects = client.projects()
for p in projects:
print(p["id"], p["name"])
datasets()
Lista todos os datasets acessíveis pelo token.
datasets = client.datasets()
for d in datasets:
print(d["id"], d["name"], d["schemaName"])
tables(dataset_id)
Lista as tabelas de um dataset com colunas e tipos.
tables = client.tables("<dataset-id>")
for t in tables:
print(t["name"], [c["sqlName"] for c in t["columns"]])
rows(table_id, limit=100)
Retorna as primeiras linhas de uma tabela pelo ID.
rows = client.rows("<table-id>", limit=50)
print(rows)
Exceções
| Exceção | Quando ocorre |
|---|---|
catworld.ConnectionError |
Falha de rede ou erro inesperado do servidor |
catworld.AuthenticationError |
Token inválido, expirado ou revogado (HTTP 401) |
catworld.PermissionDeniedError |
Token sem permissão para a operação (HTTP 403) |
catworld.ValidationError |
Dados inválidos, SQL inseguro ou upload malformado (HTTP 400/422) |
catworld.QueryTimeoutError |
Query ou importação excedeu o tempo limite |
from catworld import CatworldClient
from catworld.exceptions import PermissionDeniedError, QueryTimeoutError
try:
result = client.query("SELECT * FROM banco_horas", dataset_id="<id>")
except PermissionDeniedError:
print("Token sem acesso a este dataset")
except QueryTimeoutError:
print("Query demorou demais, tente limitar com TOP ou WHERE")
1 maintainer
Metadata
1 maintainer
Release files for catworld-sdk 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| catworld_sdk-0.2.0.tar.gz | 9.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| catworld_sdk-0.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 19.7 kB
Release files / catworld_sdk-0.2.0.tar.gz
| Download URL | catworld_sdk-0.2.0.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
662695e8fff97ab132f75dc789f35920253da63180bbd32b0c8d7847b4180cbe
|
|
BLAKE2b-256 checksum How to use checksums |
983dcf82aa2c5797b49c577e4ade1bf9ef52e9d7abd63e9d9b7eac39d87dd720
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / catworld_sdk-0.2.0-py3-none-any.whl
| Download URL | catworld_sdk-0.2.0-py3-none-any.whl |
|---|---|
| Size | 10.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
202acb278ed4d28a7053c85ec644bece70e68a2fcdd90e41e816aa7685813631
|
|
BLAKE2b-256 checksum How to use checksums |
0a9cf6aae8151362a9df76fb7d77555251261222eb1682c4eb0c433f818f2db5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for catworld-sdk 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
