0
# Core Processing
1

2
Essential functions for parsing Eliot message dictionaries into task objects and rendering them as ASCII trees. These functions form the foundation of eliot-tree's functionality and handle the core transformation from flat log messages to hierarchical visualizations.
3

4
## Capabilities
5

6
### Task Parsing
7

8
Converts an iterable of Eliot message dictionaries into parsed task objects suitable for rendering.
9

10
```python { .api }
11
def tasks_from_iterable(iterable):
12
    """
13
    Parse an iterable of Eliot message dictionaries into tasks.
14

15
    Parameters:
16
    - iterable: Iterable[Dict] - Iterable of serialized Eliot message dictionaries
17

18
    Returns:
19
    Iterable - Iterable of parsed Eliot tasks, suitable for use with render_tasks
20

21
    Raises:
22
    EliotParseError - If parsing fails for any message dictionary
23
    """
24
```
25

26
**Usage Example:**
27

28
```python
29
from eliottree import tasks_from_iterable
30

31
# Eliot message dictionaries from log file or stream
32
messages = [
33
    {"timestamp": 1425356936.278875, "action_status": "started", 
34
     "task_uuid": "f3a32bb3-ea6b-457c-aa99-08a3d0491ab4", 
35
     "action_type": "app:request", "task_level": [1]},
36
    {"timestamp": 1425356937.517161, "action_status": "succeeded",
37
     "task_uuid": "f3a32bb3-ea6b-457c-aa99-08a3d0491ab4", 
38
     "action_type": "app:request", "task_level": [1]}
39
]
40

41
# Parse into task objects
42
tasks = tasks_from_iterable(messages)
43
```
44

45
### Task Rendering
46

47
Renders parsed Eliot tasks as formatted ASCII tree output with extensive customization options.
48

49
```python { .api }
50
def render_tasks(write, tasks, field_limit=0, ignored_fields=None,
51
                 human_readable=False, colorize=None, write_err=None,
52
                 format_node=format_node, format_value=None,
53
                 utc_timestamps=True, colorize_tree=False, ascii=False,
54
                 theme=None):
55
    """
56
    Render Eliot tasks as an ASCII tree.
57

58
    Parameters:
59
    - write: Callable[[text_type], None] - Callable used to write the output
60
    - tasks: Iterable - Iterable of parsed Eliot tasks from tasks_from_iterable
61
    - field_limit: int - Length at which to begin truncating, 0 means no truncation
62
    - ignored_fields: Set[text_type] - Set of field names to ignore, defaults to Eliot metadata
63
    - human_readable: bool - Render field values as human-readable
64
    - colorize: bool - Colorize the output (deprecated, use theme parameter)
65
    - write_err: Callable[[text_type], None] - Callable used to write errors
66
    - format_node: Callable - Node formatting function (see format_node)
67
    - format_value: Callable[[Any], text_type] - Callable to format a value
68
    - utc_timestamps: bool - Format timestamps as UTC
69
    - colorize_tree: bool - Colorize the tree structure itself
70
    - ascii: bool - Render the tree as plain ASCII instead of Unicode
71
    - theme: Theme - Theme object to use for rendering colors and styles
72

73
    Returns:
74
    None - Output is written via the write callback
75
    """
76
```
77

78
**Usage Examples:**
79

80
```python
81
import sys
82
from eliottree import tasks_from_iterable, render_tasks, get_theme
83

84
# Basic rendering
85
tasks = tasks_from_iterable(messages)
86
render_tasks(sys.stdout.write, tasks)
87

88
# With colorization and theme
89
theme = get_theme(dark_background=True)
90
render_tasks(sys.stdout.write, tasks, theme=theme, colorize_tree=True)
91

92
# With field limiting and human-readable formatting
93
render_tasks(
94
    sys.stdout.write, 
95
    tasks,
96
    field_limit=100,          # Truncate long field values
97
    human_readable=True,      # Format timestamps and durations
98
    utc_timestamps=True,      # Use UTC timezone
99
    ascii=True                # Use ASCII characters only
100
)
101

102
# With custom ignored fields
103
ignored = {"task_uuid", "timestamp", "action_status"}
104
render_tasks(sys.stdout.write, tasks, ignored_fields=ignored)
105

106
# With error handling
107
def error_handler(error_text):
108
    print(f"ERROR: {error_text}", file=sys.stderr)
109

110
render_tasks(
111
    sys.stdout.write, 
112
    tasks, 
113
    write_err=error_handler,
114
    theme=theme
115
)
116
```
117

118
### Complete Processing Pipeline
119

120
```python
121
import sys
122
import json
123
from eliottree import tasks_from_iterable, render_tasks, get_theme
124

125
def process_eliot_log(log_file_path):
126
    """Complete pipeline for processing Eliot log files."""
127
    
128
    # Read and parse JSON messages
129
    messages = []
130
    with open(log_file_path, 'r') as f:
131
        for line in f:
132
            messages.append(json.loads(line.strip()))
133
    
134
    # Parse into tasks
135
    tasks = tasks_from_iterable(messages)
136
    
137
    # Setup theme and rendering
138
    theme = get_theme(dark_background=True)
139
    
140
    # Render with full options
141
    render_tasks(
142
        sys.stdout.write,
143
        tasks,
144
        theme=theme,
145
        human_readable=True,
146
        colorize_tree=True,
147
        field_limit=200,
148
        write_err=sys.stderr.write
149
    )
150

151
# Usage
152
process_eliot_log('eliot.log')
153
```
154

155
## Types
156

157
```python { .api }
158
# From six library for Python 2/3 compatibility
159
text_type = str  # In Python 3, or unicode in Python 2
160
```
161

162
## Default Field Handling
163

164
By default, `render_tasks` ignores standard Eliot metadata fields to focus on application-specific data:
165

166
- `action_status` - Action completion status (started/succeeded/failed)
167
- `action_type` - Type identifier for the action
168
- `task_level` - Hierarchical level within the task tree
169
- `task_uuid` - Unique identifier for the task
170
- `message_type` - Message type identifier
171

172
These can be overridden using the `ignored_fields` parameter to customize which fields appear in the output.
173

174
## Output Format
175

176
The rendered output follows a hierarchical tree structure:
177

178
```
179
task-uuid
180
└── action_type/level ⇒ status timestamp ⧖ duration
181
    ├── field1: value1
182
    ├── field2: value2
183
    └── nested_action/level ⇒ status timestamp
184
        └── result: value
185
```
186

187
- **Root**: Task UUID
188
- **Actions**: Action type with level, status, timestamp, and duration
189
- **Fields**: Key-value pairs from message content
190
- **Nesting**: Hierarchical relationships based on task levels