> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/pt-br/sdks/python/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# SDK para Python

O pacote é [`basement-gateway`](https://pypi.org/project/basement-gateway/). O código está no [GitHub](https://github.com/Get-Basement/gateway-python).

## Instalar

```bash
pip install basement-gateway
```

## Criar o cliente

```python
import os
from basement_gateway import BasementGateway

basement = BasementGateway(api_key=os.environ["BASEMENT_API_KEY"])
```

Quando você não informa `api_key`, o cliente lê a variável de ambiente `BASEMENT_API_KEY`.

## Chamar o Gateway

Cada ferramenta é um método. Os argumentos são nomeados, e as respostas são objetos com tipos.

```python
# Documentos
docs = basement.docs.list().docs
doc = basement.docs.read(doc_id=docs[0].id)

basement.docs.edit(
    doc_id=doc.id,
    old_text="Preços em USD",
    new_text="Preços em BRL",
    change_summary="Moeda",
)

# Buscar, e ler uma parte de um texto
results = basement.search(query="preço").results
found = basement.text.find(doc_id=doc.id, query="desconto")

# Tarefas
task = basement.tasks.create(title="Revisar os preços do 4º trimestre")
basement.tasks.update(task_id=task.task_id, status="done")

# Serviços conectados
connected = basement.services.list().connected
issue = basement.services.execute(
    tool_slug="jira__getJiraIssue",
    arguments={"issueIdOrKey": "OPS-12"},
)
```

## Assíncrono

`AsyncBasementGateway` tem os mesmos métodos, com `await`:

```python
import asyncio
from basement_gateway import AsyncBasementGateway

basement = AsyncBasementGateway()

async def main():
    docs = (await basement.docs.list()).docs
    print(len(docs))

asyncio.run(main())
```

## Tratar erros

Uma chamada que o Gateway recusa lança um `ApiError`, com o status HTTP e o corpo do erro.

```python
from basement_gateway.core.api_error import ApiError

try:
    basement.tasks.create(title="Revisar os preços do 4º trimestre")
except ApiError as error:
    print(error.status_code)         # 403
    print(error.body.error.code)     # "forbidden"
    print(error.body.error.message)  # "Role lacks write access"
```

Veja [Erros e limites](/pt-br/sdks/errors-and-limits) para cada status.

## Tempo limite e novas tentativas

Uma chamada expira depois de 60 segundos. O cliente tenta de novo, até mais 2 vezes, quando recebe `408`, `429` ou um status `5xx`. Mude os dois no cliente ou em uma chamada:

```python
basement = BasementGateway(timeout=30)

basement.docs.list(request_options={"timeout_in_seconds": 10, "max_retries": 3})
```

## Outro endereço

O cliente fala com `https://mcp.basement.chat`. Para usar outra instalação, informe `base_url`:

```python
basement = BasementGateway(base_url="http://127.0.0.1:3214")
```

> Use o Gateway em Python, com um cliente síncrono ou assíncrono.