catworld-sdk 0.1.0__tar.gz

catworld_sdk-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+.next/
+coverage/
+.env
+.env.local
+.env.*.local
+!.env.example
+*.log
+.codex-dev.log
+tmp/
+var/
+dist/
+sdk/python/dist/
+sdk/python/*.egg-info/
+sdk/python/**/__pycache__/sdk/python/.pytest_cache/
+sdk/python/pytest-cache-files-*/

catworld_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Moreira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

catworld_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: catworld-sdk
+Version: 0.1.0
+Summary: Cliente oficial Python para a API Catworld
+Author-email: Vinicius Moreira <vinicius@77indicadores.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# catworld-sdk
+
+Cliente oficial Python para a API Catworld.
+
+## Instalação
+
+```bash
+pip install catworld-sdk
+```
+
+## Uso
+
+```python
+from catworld import CatworldClient
+
+with CatworldClient("https://seu-catworld.exemplo.com", "cw_live_...") as client:
+    projects = client.projects()
+    datasets = client.datasets()
+
+    result = client.upload("dados.csv", dataset_id="...", mode="replace")
+    print(result["status"], result["rowCount"])
+
+    rows = client.query("SELECT TOP 10 * FROM [schema].[tabela]")
+    print(rows["rows"])
+```
+
+## Métodos
+
+- `projects()` / `datasets()` / `tables(dataset_id)` / `rows(table_id, limit=100)`
+- `query(sql, timeout=30, limit=10000)`
+- `upload(path, dataset_id, mode="replace", key_column=None, poll_interval=2)`
+
+O token de API precisa de permissão `WRITE` (ou `ADMIN`) no escopo do dataset para usar `upload()`.

catworld_sdk-0.1.0/README.md

@@ -0,0 +1,33 @@
+# catworld-sdk
+
+Cliente oficial Python para a API Catworld.
+
+## Instalação
+
+```bash
+pip install catworld-sdk
+```
+
+## Uso
+
+```python
+from catworld import CatworldClient
+
+with CatworldClient("https://seu-catworld.exemplo.com", "cw_live_...") as client:
+    projects = client.projects()
+    datasets = client.datasets()
+
+    result = client.upload("dados.csv", dataset_id="...", mode="replace")
+    print(result["status"], result["rowCount"])
+
+    rows = client.query("SELECT TOP 10 * FROM [schema].[tabela]")
+    print(rows["rows"])
+```
+
+## Métodos
+
+- `projects()` / `datasets()` / `tables(dataset_id)` / `rows(table_id, limit=100)`
+- `query(sql, timeout=30, limit=10000)`
+- `upload(path, dataset_id, mode="replace", key_column=None, poll_interval=2)`
+
+O token de API precisa de permissão `WRITE` (ou `ADMIN`) no escopo do dataset para usar `upload()`.

catworld_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+[project]
+name = "catworld-sdk"
+version = "0.1.0"
+description = "Cliente oficial Python para a API Catworld"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Vinicius Moreira", email = "vinicius@77indicadores.com.br" }]
+dependencies = ["httpx>=0.27,<1"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+[tool.hatch.build.targets.wheel]
+packages = ["src/catworld"]

catworld_sdk-0.1.0/src/catworld/__init__.py

@@ -0,0 +1,3 @@
+from .client import CatworldClient
+from .exceptions import AuthenticationError,CatworldError,ConnectionError,PermissionDeniedError,QueryTimeoutError,ValidationError
+__all__=["CatworldClient","CatworldError","AuthenticationError","PermissionDeniedError","ValidationError","QueryTimeoutError","ConnectionError"]

catworld_sdk-0.1.0/src/catworld/client.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+import time
+from pathlib import Path
+from typing import Any
+import httpx
+from .exceptions import AuthenticationError,PermissionDeniedError,ValidationError,QueryTimeoutError,ConnectionError
+class CatworldClient:
+    def __init__(self,base_url:str,token:str,timeout:float=30):
+        self._client=httpx.Client(base_url=base_url.rstrip("/"),headers={"Authorization":f"Bearer {token}"},timeout=timeout)
+    def close(self): self._client.close()
+    def __enter__(self): return self
+    def __exit__(self,*_): self.close()
+    def projects(self): return self._request("GET","/api/v1/projects")
+    def datasets(self): return self._request("GET","/api/v1/datasets")
+    def tables(self,dataset_id:str): return self._request("GET",f"/api/v1/datasets/{dataset_id}/tables")
+    def rows(self,table_id:str,limit:int=100): return self._request("GET",f"/api/v1/tables/{table_id}/rows",params={"limit":limit})
+    def query(self,sql:str,timeout:int=30,limit:int=10000): return self._request("POST","/api/v1/queries",json={"sql":sql,"timeout":timeout,"limit":limit})
+    def upload(self,path:str|Path,dataset_id:str,mode:str="replace",key_column:str|None=None,poll_interval:float=2):
+        file=Path(path);created=self._request("POST","/api/v1/uploads",json={"filename":file.name,"sizeBytes":file.stat().st_size});
+        with file.open("rb") as stream:
+            response=self._client.put(created["sas"]["url"],content=stream,headers={"content-type":"application/octet-stream"},timeout=None);response.raise_for_status()
+        upload_id=created["upload"]["id"];self._request("POST",f"/api/v1/uploads/{upload_id}/uploaded");preview=self._wait(upload_id,"AWAITING_CONFIRMATION",poll_interval)
+        mapping=preview["previewJson"];import json as _json
+        if isinstance(mapping,str): mapping=_json.loads(mapping)
+        self._request("POST",f"/api/v1/uploads/{upload_id}/confirm",json={"datasetId":dataset_id,"mode":mode,"keyColumn":key_column,"mapping":mapping["columns"]})
+        return self._wait(upload_id,"COMPLETED",poll_interval)
+    def _wait(self,upload_id,target,interval):
+        for _ in range(1800):
+            upload=self._request("GET",f"/api/v1/uploads/{upload_id}")
+            if upload["status"]==target:return upload
+            if upload["status"]=="FAILED":raise ValidationError(upload.get("errorMessage") or "Upload falhou")
+            time.sleep(interval)
+        raise QueryTimeoutError("Tempo de processamento excedido")
+    def _request(self,method,path,**kwargs)->Any:
+        try: response=self._client.request(method,path,**kwargs)
+        except httpx.HTTPError as exc: raise ConnectionError(str(exc)) from exc
+        if response.is_success:return response.json()["data"]
+        body=response.json();message=body.get("error",{}).get("message",response.text)
+        if response.status_code==401:raise AuthenticationError(message)
+        if response.status_code==403:raise PermissionDeniedError(message)
+        if response.status_code in (400,422):raise ValidationError(message)
+        if response.status_code==408:raise QueryTimeoutError(message)
+        raise ConnectionError(message)

catworld_sdk-0.1.0/src/catworld/exceptions.py

@@ -0,0 +1,6 @@
+class CatworldError(Exception): pass
+class AuthenticationError(CatworldError): pass
+class PermissionDeniedError(CatworldError): pass
+class ValidationError(CatworldError): pass
+class QueryTimeoutError(CatworldError): pass
+class ConnectionError(CatworldError): pass

catworld_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,5 @@
+from catworld import CatworldClient
+def test_client_constructs():
+    client=CatworldClient("https://catworld.example","cw_live_test")
+    assert client is not None
+    client.close()