n8n-sdk-python 0.1.3
A Python SDK for the n8n automation platform.
Requires Python: >=3.8
Keywords: n8n, sdk, python, automation, api-client, n8n-client, workflow

# n8n-sdk-python

[ English | [繁體中文](docs/README_TW.md) ]

This is an unofficial Python SDK for the [n8n workflow](https://n8n.io/) automation platform. This SDK provides convenient wrappers for interacting with the n8n API, allowing you to manage workflows, executions, credentials, and other n8n resources from your Python applications.

## Table of Contents
- [System Requirements](#system-requirements)
- [Installation](#installation)
- [Initial Setup](#initial-setup)
- [Quick Start](#quick-start)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## System Requirements

Before installing n8n-sdk-python, please ensure your system meets the following requirements:

- Python 3.8 or higher
- A running n8n instance (local or remote)
- n8n API key (for authentication)

## Installation

### Using a Virtual Environment

Using a virtual environment can prevent dependency conflicts:

```bash
# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate
```

### Method 1: Using pip (Recommended)

The easiest way to install is using the pip package manager:

```bash
pip install n8n-sdk-python
```

### Method 2: Installing from Source

If you need the latest development version or want to modify the code, you can install from source:

```bash
# Clone the repository
git clone https://github.com/eric050828/n8n-sdk-python.git
cd n8n-sdk-python

# Install in development mode
pip install -e .
```

## Initial Setup

After installation, you need to perform some initial setup to use the SDK.

### Get n8n API Key

1. Log in to your n8n instance.
2. Click on the user icon in the upper right corner and select "Settings".
3. Click on the "API" tab.
4. Click the "Create" button to generate a new API key.
5. Copy the generated API key (please save it, as it will only be displayed once).

### Set Environment Variables

You can configure the SDK through environment variables, so you don't need to hardcode sensitive information in your code:

#### On Linux/macOS

```bash
export N8N_BASE_URL="http://localhost:5678"
export N8N_API_KEY="your-api-key-here"
```

#### On Windows

```bash
set N8N_BASE_URL=http://localhost:5678
set N8N_API_KEY=your-api-key-here
```

#### Using a .env File

For project development, it is recommended to use a `.env` file to manage environment variables:

1. Create a file named `.env` in your project root directory.
2. Add the following content:

```
N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your-api-key-here
```

3. Load these settings in your program:

```python
from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

# Now you can use os.getenv to get environment variables
base_url = os.getenv("N8N_BASE_URL")
api_key = os.getenv("N8N_API_KEY")
```

Please note that you need to install the `python-dotenv` library to use this feature: `pip install python-dotenv`

## Quick Start

After installation, you can run the following code to verify that the SDK is working correctly:

```python
import asyncio
from n8n_sdk_python import N8nClient
from n8n_sdk_python.models.workflows import WorkflowList

async def test_connection():
    # Initialize the client
    client = N8nClient(
        base_url="http://localhost:5678",  # Replace with your n8n instance URL
        api_key="your-api-key-here"  # Replace with your API key
    )
    
    try:
        # Try to get the workflow list
        workflows: WorkflowList = await client.list_workflows(limit=1)
        print("✅ Connection successful! Number of workflows found:", len(workflows.data))
        return True
    except Exception as e:
        print("❌ Connection failed:", str(e))
        return False

if __name__ == "__main__":
    result = asyncio.run(test_connection())
    print("Test result:", "Success" if result else "Failure")
```

## Troubleshooting

If you encounter problems, here are some common issues and their solutions:

### Installation Issues

**Problem:** "ERROR: Could not find a version that satisfies the requirement n8n-sdk-python" during installation.

**Solution:** Check if your Python version meets the requirements (3.8+) and ensure pip is updated to the latest version:

```bash
python --version
pip install --upgrade pip
```

### Connection Issues

**Problem:** "Connection refused" error when connecting to the n8n instance.

**Solution:** 
- Confirm that the n8n instance is running.
- Check if the URL is correct, including the protocol (http/https) and port.
- Ensure no firewall is blocking the connection.

**Problem:** Received a 401 Unauthorized error.

**Solution:** 
- Confirm the API key is correct.
- Check if the API key has expired or been revoked.
- Verify that the user has sufficient permissions.

### Import Issues

**Problem:** "ModuleNotFoundError: No module named 'n8n_sdk_python'"

**Solution:** 
- Confirm the library is correctly installed: `pip list | grep n8n-sdk-python`
- If using a virtual environment, confirm it is activated: `which python`
- Try reinstalling: `pip install --force-reinstall --no-cache-dir n8n-sdk-python`

### Other Issues

If you encounter other issues, you can:

1. Check the log output for detailed error messages.
2. Enable debug mode for more logs:

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

3. Submit an issue on the GitHub repository with error details and steps to reproduce.