# Go-Server Python SDK
Python SDK for the go-server distributed task scheduling system. This SDK provides both client and worker libraries for interacting with the go-server scheduler.
## Features
- 🚀 **Easy Integration**: Simple APIs for both clients and workers
- 🔄 **Automatic Retry**: Built-in retry mechanisms for robust operation
- 📡 **WebSocket Support**: Real-time communication with the scheduler
- 🛡️ **Type Safety**: Full type hints support for better development experience
- 📚 **Method Documentation**: Support for documenting registered methods
- ⚖️ **Load Balancing**: Automatic task distribution across workers
## Prerequisites
### Starting the Scheduler
**Important**: Before using this Python SDK, you must have the go-server scheduler running. The scheduler is the core component that manages and distributes tasks to workers.
#### Quick Start with go-server
1. **Clone the go-server repository**:
```bash
git clone https://github.com/go-enols/go-server.git
cd go-server
```
2. **Build and run the scheduler**:
```bash
# Build the project
go build -o scheduler ./go-sdk/examples/scheduler/scheduler
# Run the scheduler (default port: 8080)
./scheduler
```
For detailed configuration options and advanced setup, please refer to the [go-server documentation](https://github.com/go-enols/go-server).
**Note**: The scheduler must be running and accessible before you can use any of the SDK features. All examples in this documentation assume the scheduler is running on `http://localhost:8080`.
## Installation
install from requirements.txt:
```bash
pip install -r requirements.txt
```
install from source:
```bash
python setup.py install
```
## Quick Start
### Client Usage
```python
from python_sdk.scheduler import SchedulerClient
# Create a client
client = SchedulerClient("http://localhost:8080")
# Execute a task synchronously
result = client.execute_sync("add", {"a": 1, "b": 2}, timeout=30.0)
print(f"Result: {result.result}") # Output: Result: 3
# Execute a task asynchronously
response = client.execute("add", {"a": 5, "b": 3})
task_id = response.task_id
# Get the result later
result = client.get_result(task_id)
print(f"Async result: {result.result}") # Output: Async result: 8
```
### Worker Usage
```python
from python_sdk.worker import Worker, Config
import time
# Define your methods
def add_numbers(params):
"""Add two numbers"""
return params["a"] + params["b"]
def multiply_numbers(params):
"""Multiply two numbers"""
return params["a"] * params["b"]
def long_running_task(params):
"""Simulate a long-running task"""
time.sleep(params.get("duration", 5))
return {"status": "completed", "message": "Task finished"}
# Create worker configuration
config = Config(
scheduler_url="http://localhost:8080",
worker_group="math_workers",
max_retry=3,
ping_interval=30
)
# Create and configure worker
worker = Worker(config)
# Register methods with documentation
worker.register_method(
"add",
add_numbers,
"Add two numbers",
"Parameters: {\"a\": number, \"b\": number}",
"Returns: number"
)
worker.register_method(
"multiply",
multiply_numbers,
"Multiply two numbers",
"Parameters: {\"a\": number, \"b\": number}",
"Returns: number"
)
worker.register_method(
"long_task",
long_running_task,
"Execute a long-running task",
"Parameters: {\"duration\": number (optional, default: 5)}",
"Returns: {\"status\": string, \"message\": string}"
)
# Start the worker
try:
worker.start()
print("Worker started. Press Ctrl+C to stop.")
# Keep the worker running
import signal
import sys
def signal_handler(sig, frame):
print("\nStopping worker...")
worker.stop()
sys.exit(0)
signal.signal(signal.SIGINT, signal_handler)
signal.pause()
except Exception as e:
print(f"Error starting worker: {e}")
worker.stop()
```
### Simple Call Function
For quick one-off calls, you can use the simple `call` function:
```python
from python_sdk.worker import call
# Simple synchronous call
result = call("http://localhost:8080", "add", {"a": 1, "b": 2})
print(f"Result: {result}") # Output: Result: 3
# Call with type hint
result: int = call("http://localhost:8080", "add", {"a": 1, "b": 2}, int)
# Async call
from python_sdk.worker import call_async, get_result
task_id = call_async("http://localhost:8080", "long_task", {"duration": 10})
print(f"Task submitted: {task_id}")
# Get result later
result = get_result("http://localhost:8080", task_id)
print(f"Task result: {result}")
```
### Retry Client
For more robust operation, use the retry client:
```python
from python_sdk.scheduler import RetryClient
# Create retry client with custom settings
client = RetryClient(
base_url="http://localhost:8080",
max_retries=5,
retry_delay=2.0,
timeout=30
)
# Execute with automatic retry
result = client.execute_with_retry("add", {"a": 1, "b": 2})
print(f"Result: {result.result}")
# Synchronous execution with retry
result = client.execute_sync_with_retry("multiply", {"a": 3, "b": 4}, timeout=60.0)
print(f"Result: {result.result}")
```
## API Reference
### SchedulerClient
- `execute(method, params)`: Execute a task asynchronously
- `get_result(task_id)`: Get result for a task (with polling)
- `execute_sync(method, params, timeout)`: Execute a task synchronously
### RetryClient
- `execute_with_retry(method, params)`: Execute with automatic retry
- `execute_sync_with_retry(method, params, timeout)`: Synchronous execution with retry
### Worker
- `register_method(name, handler, *docs)`: Register a method handler
- `start()`: Start the worker
- `stop()`: Stop the worker
### Configuration
```python
config = Config(
scheduler_url="http://localhost:8080", # Scheduler URL
worker_group="my_workers", # Worker group name
max_retry=3, # Connection retry attempts
ping_interval=30 # Heartbeat interval (seconds)
)
```
## Error Handling
The SDK provides comprehensive error handling:
```python
from python_sdk.scheduler import SchedulerClient
import requests
client = SchedulerClient("http://localhost:8080")
try:
result = client.execute_sync("nonexistent_method", {})
except requests.RequestException as e:
print(f"Network error: {e}")
except ValueError as e:
print(f"Invalid response: {e}")
except RuntimeError as e:
print(f"Task execution error: {e}")
except TimeoutError as e:
print(f"Timeout: {e}")
```
## Development
### Running Tests
```bash
pip install -e ".[dev]"
pytest
```
### Code Formatting
```bash
black python_sdk/
flake8 python_sdk/
mypy python_sdk/
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": "https://github.com/go-enols/go-server",
"name": "go-server-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "distributed computing, task scheduling, websocket, rpc",
"author": "go-server team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e4/0d/47971dea216bd125b637b7c7954c4ead0443e32e1a77ffcfd6e42eaaa357/go_server_sdk-2.0.1.tar.gz",
"platform": null,
"description": "# Go-Server Python SDK\r\n\r\nPython SDK for the go-server distributed task scheduling system. This SDK provides both client and worker libraries for interacting with the go-server scheduler.\r\n\r\n## Features\r\n\r\n- \ud83d\ude80 **Easy Integration**: Simple APIs for both clients and workers\r\n- \ud83d\udd04 **Automatic Retry**: Built-in retry mechanisms for robust operation\r\n- \ud83d\udce1 **WebSocket Support**: Real-time communication with the scheduler\r\n- \ud83d\udee1\ufe0f **Type Safety**: Full type hints support for better development experience\r\n- \ud83d\udcda **Method Documentation**: Support for documenting registered methods\r\n- \u2696\ufe0f **Load Balancing**: Automatic task distribution across workers\r\n\r\n## Prerequisites\r\n\r\n### Starting the Scheduler\r\n\r\n**Important**: Before using this Python SDK, you must have the go-server scheduler running. The scheduler is the core component that manages and distributes tasks to workers.\r\n\r\n#### Quick Start with go-server\r\n\r\n1. **Clone the go-server repository**:\r\n ```bash\r\n git clone https://github.com/go-enols/go-server.git\r\n cd go-server\r\n ```\r\n\r\n2. **Build and run the scheduler**:\r\n ```bash\r\n # Build the project\r\n go build -o scheduler ./go-sdk/examples/scheduler/scheduler\r\n \r\n # Run the scheduler (default port: 8080)\r\n ./scheduler\r\n ```\r\n\r\nFor detailed configuration options and advanced setup, please refer to the [go-server documentation](https://github.com/go-enols/go-server).\r\n\r\n**Note**: The scheduler must be running and accessible before you can use any of the SDK features. All examples in this documentation assume the scheduler is running on `http://localhost:8080`.\r\n\r\n## Installation\r\n\r\ninstall from requirements.txt:\r\n\r\n```bash\r\npip install -r requirements.txt\r\n```\r\n\r\ninstall from source:\r\n\r\n```bash\r\npython setup.py install\r\n```\r\n\r\n## Quick Start\r\n\r\n### Client Usage\r\n\r\n```python\r\nfrom python_sdk.scheduler import SchedulerClient\r\n\r\n# Create a client\r\nclient = SchedulerClient(\"http://localhost:8080\")\r\n\r\n# Execute a task synchronously\r\nresult = client.execute_sync(\"add\", {\"a\": 1, \"b\": 2}, timeout=30.0)\r\nprint(f\"Result: {result.result}\") # Output: Result: 3\r\n\r\n# Execute a task asynchronously\r\nresponse = client.execute(\"add\", {\"a\": 5, \"b\": 3})\r\ntask_id = response.task_id\r\n\r\n# Get the result later\r\nresult = client.get_result(task_id)\r\nprint(f\"Async result: {result.result}\") # Output: Async result: 8\r\n```\r\n\r\n### Worker Usage\r\n\r\n```python\r\nfrom python_sdk.worker import Worker, Config\r\nimport time\r\n\r\n# Define your methods\r\ndef add_numbers(params):\r\n \"\"\"Add two numbers\"\"\"\r\n return params[\"a\"] + params[\"b\"]\r\n\r\ndef multiply_numbers(params):\r\n \"\"\"Multiply two numbers\"\"\"\r\n return params[\"a\"] * params[\"b\"]\r\n\r\ndef long_running_task(params):\r\n \"\"\"Simulate a long-running task\"\"\"\r\n time.sleep(params.get(\"duration\", 5))\r\n return {\"status\": \"completed\", \"message\": \"Task finished\"}\r\n\r\n# Create worker configuration\r\nconfig = Config(\r\n scheduler_url=\"http://localhost:8080\",\r\n worker_group=\"math_workers\",\r\n max_retry=3,\r\n ping_interval=30\r\n)\r\n\r\n# Create and configure worker\r\nworker = Worker(config)\r\n\r\n# Register methods with documentation\r\nworker.register_method(\r\n \"add\", \r\n add_numbers,\r\n \"Add two numbers\",\r\n \"Parameters: {\\\"a\\\": number, \\\"b\\\": number}\",\r\n \"Returns: number\"\r\n)\r\n\r\nworker.register_method(\r\n \"multiply\", \r\n multiply_numbers,\r\n \"Multiply two numbers\",\r\n \"Parameters: {\\\"a\\\": number, \\\"b\\\": number}\",\r\n \"Returns: number\"\r\n)\r\n\r\nworker.register_method(\r\n \"long_task\",\r\n long_running_task,\r\n \"Execute a long-running task\",\r\n \"Parameters: {\\\"duration\\\": number (optional, default: 5)}\",\r\n \"Returns: {\\\"status\\\": string, \\\"message\\\": string}\"\r\n)\r\n\r\n# Start the worker\r\ntry:\r\n worker.start()\r\n print(\"Worker started. Press Ctrl+C to stop.\")\r\n \r\n # Keep the worker running\r\n import signal\r\n import sys\r\n \r\n def signal_handler(sig, frame):\r\n print(\"\\nStopping worker...\")\r\n worker.stop()\r\n sys.exit(0)\r\n \r\n signal.signal(signal.SIGINT, signal_handler)\r\n signal.pause()\r\n \r\nexcept Exception as e:\r\n print(f\"Error starting worker: {e}\")\r\n worker.stop()\r\n```\r\n\r\n### Simple Call Function\r\n\r\nFor quick one-off calls, you can use the simple `call` function:\r\n\r\n```python\r\nfrom python_sdk.worker import call\r\n\r\n# Simple synchronous call\r\nresult = call(\"http://localhost:8080\", \"add\", {\"a\": 1, \"b\": 2})\r\nprint(f\"Result: {result}\") # Output: Result: 3\r\n\r\n# Call with type hint\r\nresult: int = call(\"http://localhost:8080\", \"add\", {\"a\": 1, \"b\": 2}, int)\r\n\r\n# Async call\r\nfrom python_sdk.worker import call_async, get_result\r\n\r\ntask_id = call_async(\"http://localhost:8080\", \"long_task\", {\"duration\": 10})\r\nprint(f\"Task submitted: {task_id}\")\r\n\r\n# Get result later\r\nresult = get_result(\"http://localhost:8080\", task_id)\r\nprint(f\"Task result: {result}\")\r\n```\r\n\r\n### Retry Client\r\n\r\nFor more robust operation, use the retry client:\r\n\r\n```python\r\nfrom python_sdk.scheduler import RetryClient\r\n\r\n# Create retry client with custom settings\r\nclient = RetryClient(\r\n base_url=\"http://localhost:8080\",\r\n max_retries=5,\r\n retry_delay=2.0,\r\n timeout=30\r\n)\r\n\r\n# Execute with automatic retry\r\nresult = client.execute_with_retry(\"add\", {\"a\": 1, \"b\": 2})\r\nprint(f\"Result: {result.result}\")\r\n\r\n# Synchronous execution with retry\r\nresult = client.execute_sync_with_retry(\"multiply\", {\"a\": 3, \"b\": 4}, timeout=60.0)\r\nprint(f\"Result: {result.result}\")\r\n```\r\n\r\n## API Reference\r\n\r\n### SchedulerClient\r\n\r\n- `execute(method, params)`: Execute a task asynchronously\r\n- `get_result(task_id)`: Get result for a task (with polling)\r\n- `execute_sync(method, params, timeout)`: Execute a task synchronously\r\n\r\n### RetryClient\r\n\r\n- `execute_with_retry(method, params)`: Execute with automatic retry\r\n- `execute_sync_with_retry(method, params, timeout)`: Synchronous execution with retry\r\n\r\n### Worker\r\n\r\n- `register_method(name, handler, *docs)`: Register a method handler\r\n- `start()`: Start the worker\r\n- `stop()`: Stop the worker\r\n\r\n### Configuration\r\n\r\n```python\r\nconfig = Config(\r\n scheduler_url=\"http://localhost:8080\", # Scheduler URL\r\n worker_group=\"my_workers\", # Worker group name\r\n max_retry=3, # Connection retry attempts\r\n ping_interval=30 # Heartbeat interval (seconds)\r\n)\r\n```\r\n\r\n## Error Handling\r\n\r\nThe SDK provides comprehensive error handling:\r\n\r\n```python\r\nfrom python_sdk.scheduler import SchedulerClient\r\nimport requests\r\n\r\nclient = SchedulerClient(\"http://localhost:8080\")\r\n\r\ntry:\r\n result = client.execute_sync(\"nonexistent_method\", {})\r\nexcept requests.RequestException as e:\r\n print(f\"Network error: {e}\")\r\nexcept ValueError as e:\r\n print(f\"Invalid response: {e}\")\r\nexcept RuntimeError as e:\r\n print(f\"Task execution error: {e}\")\r\nexcept TimeoutError as e:\r\n print(f\"Timeout: {e}\")\r\n```\r\n\r\n## Development\r\n\r\n### Running Tests\r\n\r\n```bash\r\npip install -e \".[dev]\"\r\npytest\r\n```\r\n\r\n### Code Formatting\r\n\r\n```bash\r\nblack python_sdk/\r\nflake8 python_sdk/\r\nmypy python_sdk/\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for go-server distributed task scheduling system",
"version": "2.0.1",
"project_urls": {
"Bug Reports": "https://github.com/go-enols/go-server/issues",
"Documentation": "https://github.com/go-enols/go-server/blob/main/README.md",
"Homepage": "https://github.com/go-enols/go-server",
"Source": "https://github.com/go-enols/go-server"
},
"split_keywords": [
"distributed computing",
" task scheduling",
" websocket",
" rpc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7927f90b09155f4381b3e34255c5bf22eda3b69cac3039e44b5e9dcab8096ccf",
"md5": "f358015e4be02701e483f11327a49ec5",
"sha256": "0eea31d3f19c918ad6451affeeb1477c1ede134a1fbbebbe8786a69c613d3635"
},
"downloads": -1,
"filename": "go_server_sdk-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f358015e4be02701e483f11327a49ec5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10662,
"upload_time": "2025-06-15T13:53:37",
"upload_time_iso_8601": "2025-06-15T13:53:37.657047Z",
"url": "https://files.pythonhosted.org/packages/79/27/f90b09155f4381b3e34255c5bf22eda3b69cac3039e44b5e9dcab8096ccf/go_server_sdk-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e40d47971dea216bd125b637b7c7954c4ead0443e32e1a77ffcfd6e42eaaa357",
"md5": "4adc8d1462c2d6168ae8ebbfb4144555",
"sha256": "4a7916fb84fd5eba1ace441765476b8079288f0d30c6c7139b730e3ad438ed3f"
},
"downloads": -1,
"filename": "go_server_sdk-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4adc8d1462c2d6168ae8ebbfb4144555",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9949,
"upload_time": "2025-06-15T13:53:39",
"upload_time_iso_8601": "2025-06-15T13:53:39.506414Z",
"url": "https://files.pythonhosted.org/packages/e4/0d/47971dea216bd125b637b7c7954c4ead0443e32e1a77ffcfd6e42eaaa357/go_server_sdk-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-06-15 13:53:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "go-enols",
"github_project": "go-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "go-server-sdk"
}
JSON
