conductor-oss / conductor-oss/getting-started
Python SDK: TaskHandler context manager silently starts 0 workers if start_processes() is not called explicitly
- Dominant language
- No language data
- Stars
- 2
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Using `TaskHandler` as a context manager (`with TaskHandler(...) as th:`) without calling `th.start_processes()` inside the block silently starts **zero workers**. No error is raised. The workflow hangs in `RUNNING` state indefinitely. The context manager gives no indication it hasn't started anything.
## Steps to reproduce
```python
from conductor.client.automator.task_handler import TaskHandler
from conductor.client.configuration.configuration import Configuration
from conductor.client.orkes_clients import OrkesClients
from conductor.client.worker.worker_task import worker_task
@worker_task(task_definition_name='my_worker', register_task_def=True)
def my_worker(name: str) -> str:
return f'Hello {name}'
config = Configuration()
executor = OrkesClients(configuration=config).get_workflow_executor()
# ... register workflow ...
with TaskHandler(configuration=config, scan_for_annotated_workers=True) as th:
# Forgot to call th.start_processes()
run = executor.execute(name='my_workflow', version=1, workflow_input={'name': 'x'})
print(run.status) # RUNNING — workflow stuck, never completed
```
## What happens
```
TaskHandler initialized
Starting worker processes... Started 0 TaskRunner process(es) ← silent
Status: RUNNING
```
Actually the "Starting worker processes" log is NOT printed because `start_processes()` was never called. Workers were never started. The workflow queues a task, no worker picks it up, and `execute()` times out returning `RUNNING`.
## Why this is confusing
In Python, context managers conventionally handle setup in `__enter__`. A user reading:
```python
with TaskHandler(configuration=config, scan_for_annotated_workers=True) as th:
th.start_processes()
```
naturally wonders: **why do I need to call `start_processes()` explicitly when I'm already inside the `with` block?** The answer (the `with` only ensures cleanup/stop on exit, not startup) is not documented at the point of use.
This leads to two failure modes:
1. Skip `start_processes()` entirely → 0 workers, workflow hangs
2. Move `start_processes()` outside the `with` block → workers not cleaned up properly on exception
## Expected behavior
Either:
- `__enter__` should call `start_processes()` automatically (conventional Python behavior)
- Or the context manager should warn/raise if `start_processes()` was never called before `execute()` is invoked
At minimum, the docstring/README should explicitly warn that `start_processes()` is **required** inside the `with` block and explain why.
## Environment
- Python 3.14, conductor-python 1.3.8, Conductor OSS
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the TaskHandler context-manager entry point and its start_processes() method in the Python SDK usage shown in the issue. Compare the README or docstring guidance with the demonstrated with block, then determine whether the project wants automatic startup, a warning/error, or documentation only. Done means the zero-worker hang is prevented or clearly documented, with the relevant usage verified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 38/100