> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install and use the official Essal Python SDK to access all six apps from your Python project.

The `essal-python` library provides a synchronous and async-compatible client for the Essal API. It supports Python 3.9+.

## Installation

```bash theme={null}
pip install essal
```

## Initialisation

```python theme={null}
from essal import EssalClient

client = EssalClient(
    api_key=os.environ["ESSAL_API_KEY"],
    environment="production"  # "production" | "staging" | "sandbox"
)
```

## Usage Examples

### Office

```python theme={null}
# List documents
docs = client.office.documents.list(limit=20)

# Create a document
doc = client.office.documents.create(
    title="Q4 Planning",
    content="<h1>Q4 Planning</h1>",
    content_type="html"
)
print(doc.id)
```

### Sales

```python theme={null}
# Create a contact
contact = client.sales.contacts.create(
    display_name="Jane Smith",
    email="jane@acmecorp.com",
    organization_name="Acme Corp"
)

# Move a deal
client.sales.deals.update(
    "deal_01HXYZAAA",
    stage_id="stg_01HXYZ3333"
)
```

## Async Usage

```python theme={null}
import asyncio
from essal.async_client import AsyncEssalClient

async def main():
    client = AsyncEssalClient(api_key=os.environ["ESSAL_API_KEY"])
    docs = await client.office.documents.list(limit=10)
    for doc in docs.data:
        print(doc.title)

asyncio.run(main())
```

## Error Handling

```python theme={null}
from essal.exceptions import EssalAPIError, RateLimitError

try:
    contact = client.sales.contacts.get("cnt_01HXYZ9999")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except EssalAPIError as e:
    print(f"API error: {e.code} — {e.message}")
```