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")

Metadata

Release files for catworld-sdk 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for catworld-sdk 0.3.1
File	Size	Uploaded	Provenance
catworld_sdk-0.3.1.tar.gz	6.4 kB	Jul 7, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for catworld-sdk 0.3.1
File	Interpreter	ABI	Platform	Reset
catworld_sdk-0.3.1-py3-none-any.whl 7.5 kB Jul 7, 2026 Without provenance	Python 3	none	any	Details

Total release size: 13.9 kB

Release files / catworld_sdk-0.3.1.tar.gz

Download URL	catworld_sdk-0.3.1.tar.gz
Size	6.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`69061a0ba8737526a5b0437a5050b0984ca8a35aba152f52e4474dbf1c563a6a`
BLAKE2b-256 checksum How to use checksums	`e4b6022220c2dd5064e77fd41ae6a24899d0c2239caaa853cedeb87330c02682`
Upload date	Jul 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / catworld_sdk-0.3.1-py3-none-any.whl

Download URL	catworld_sdk-0.3.1-py3-none-any.whl
Size	7.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6bf903804982c829d8f26f46aba1d0754ea28d75bda096a5115eab4d79c8da91`
BLAKE2b-256 checksum How to use checksums	`a133b0b189cd9f913aee60a03b7da160af94a8f15fd3f4532b31085d8042be76`
Upload date	Jul 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Security for catworld-sdk 0.3.1

Report project as malware

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.