exceljet-api-client 0.1.0
Client library for the ExcelJet API
License: MIT
Requires Python: >=3.8

# ExcelJet API Client

A Python client for the ExcelJet API. This client library provides convenient access to the ExcelJet API from Python applications.

## Installation

```bash
# Install the package
pip install exceljet-api-client

# For developers: Install with development dependencies
pip install "exceljet-api-client[dev]"

# For local development from source
git clone https://github.com/exceljet2/exceljet-api-client.git
cd exceljet-api-client
pip install -e ".[dev]"
```

## Usage

```python
from exceljet_client import ExceljetClient
from exceljet_client.models import ContentType

# Initialize the client
client = ExceljetClient(api_key="your_api_key")

# List nodes with optional filtering
nodes = client.list_nodes(content_type=ContentType.FUNCTION, limit=10)
print(f"Found {nodes.count} nodes")

# Get a specific node
node = client.get_node(node_id=123)
print(f"Node title: {node.title}")

# Get node as markdown
markdown = client.get_node_markdown(node_id=123)
print(markdown)

# Create a new node
from exceljet_client.models import BackdropNode

new_node = BackdropNode(
    nid=456,
    title="New Function Example",
    type="function",
    path="functions/new-example",
    created=int(time.time()),
    changed=int(time.time()),
    status=True,
    body="Example function body"
)

created_node = client.create_node(new_node)
print(f"Created node: {created_node.nid}")

# Update an existing node
updated_node = client.update_node(node_id=456, node=new_node)

# Delete a node
client.delete_node(node_id=456)
```

## Bulk Operations

The client supports bulk operations for creating, updating, and deleting multiple nodes:

```python
# Bulk create nodes
nodes_to_create = [node1, node2, node3]
result = client.create_nodes_bulk(nodes_to_create)
print(f"Created {result.created} nodes")

# Bulk update nodes
result = client.update_nodes_bulk(nodes_to_update)
print(f"Updated {result.updated} nodes")

# Bulk delete nodes
result = client.delete_nodes_bulk([123, 456, 789])
print(f"Deleted {result.deleted} nodes")
```

## Error Handling

The client raises typed exceptions for different error cases:

```python
from exceljet_client.exceptions import ExceljetApiError, NodeNotFoundError

try:
    node = client.get_node(node_id=999999)
except NodeNotFoundError:
    print("Node not found")
except ExceljetApiError as e:
    print(f"API error: {e.status_code} - {e.detail}")
```

## Running Integration Tests

The library includes integration tests that can be run against a local or remote API server:

```bash
# Run integration tests against localhost:8000 (the default)
pytest tests/test_integration.py

# Skip integration tests
SKIP_INTEGRATION_TESTS=true pytest 

# Run against a different server
EXCELJET_API_URL=http://api.example.com EXCELJET_API_KEY=your_key pytest tests/test_integration.py
```

The integration tests require a running ExcelJet API server. By default, they connect to `http://localhost:8000` using the API key `integration_test_key`. You can customize these using environment variables:

- `EXCELJET_API_URL` - The base URL of the API server
- `EXCELJET_API_KEY` - The API key to use for authentication
- `SKIP_INTEGRATION_TESTS` - Set to "true" to skip integration tests

## API Reference

See the [full API reference](https://docs.exceljet.com/api) for detailed documentation.

## License

MIT