0
# Table Operations
1

2
Core functionality for creating, accessing, and manipulating table structures. This module provides the fundamental operations for working with tabular data in PETL, including table creation, data access patterns, and conversion utilities.
3

4
## Capabilities
5

6
### Table Creation
7

8
Create tables from various data structures and empty tables for building data programmatically.
9

10
```python { .api }
11
def empty() -> Table:
12
    """Create an empty table with no fields or data."""
13

14
def wrap(table) -> Table:
15
    """
16
    Wrap an iterable as a Table object.
17
    
18
    Parameters:
19
    - table: Any iterable that yields rows (lists, tuples, etc.)
20
    
21
    Returns:
22
    Table object
23
    """
24

25
def fromcolumns(cols, header=None, missing=None) -> Table:
26
    """
27
    Construct a table from a sequence of column arrays.
28
    
29
    Parameters:
30
    - cols: Sequence of column arrays/lists
31
    - header: Optional list of field names
32
    - missing: Value to use for missing data
33
    
34
    Returns:
35
    Table object
36
    """
37
```
38

39
### Data Access
40

41
Access table structure and data using various patterns and formats.
42

43
```python { .api }
44
def header(table):
45
    """
46
    Get the header row of a table.
47
    
48
    Parameters:
49
    - table: Input table
50
    
51
    Returns:
52
    Tuple of field names
53
    """
54

55
def fieldnames(table):
56
    """
57
    Get field names from table header.
58
    
59
    Parameters:
60
    - table: Input table
61
    
62
    Returns:
63
    Tuple of field names
64
    """
65

66
def data(table, *sliceargs):
67
    """
68
    Return data rows from table (excluding header).
69
    
70
    Parameters:
71
    - table: Input table
72
    - sliceargs: Optional slice arguments for row selection
73
    
74
    Returns:
75
    Iterator over data rows
76
    """
77

78
def records(table, *sliceargs, **kwargs):
79
    """
80
    Return table data as Record objects with named field access.
81
    
82
    Parameters:
83
    - table: Input table
84
    - sliceargs: Optional slice arguments
85
    - missing: Value for missing fields
86
    
87
    Returns:
88
    Iterator over Record objects
89
    """
90

91
def dicts(table, *sliceargs, **kwargs):
92
    """
93
    Return table data as dictionaries.
94
    
95
    Parameters:
96
    - table: Input table
97
    - sliceargs: Optional slice arguments
98
    - missing: Value for missing fields
99
    
100
    Returns:
101
    Iterator over dictionaries
102
    """
103

104
def namedtuples(table, *sliceargs, **kwargs):
105
    """
106
    Return table data as named tuples.
107
    
108
    Parameters:
109
    - table: Input table
110
    - sliceargs: Optional slice arguments
111
    - missing: Value for missing fields
112
    
113
    Returns:
114
    Iterator over named tuples
115
    """
116

117
def values(table, *field, **kwargs):
118
    """
119
    Return a container supporting iteration over values in specified field(s).
120
    
121
    Parameters:
122
    - table: Input table
123
    - field: Field name(s) to extract values from
124
    - missing: Value for missing data
125
    
126
    Returns:
127
    Container with field values
128
    """
129
```
130

131
### Data Materialization
132

133
Convert tables to standard Python data structures for further processing.
134

135
```python { .api }
136
def listoflists(table):
137
    """
138
    Materialize table as a list of lists.
139
    
140
    Parameters:
141
    - table: Input table
142
    
143
    Returns:
144
    List of lists (including header)
145
    """
146

147
def listoftuples(table):
148
    """
149
    Materialize table as a list of tuples.
150
    
151
    Parameters:
152
    - table: Input table
153
    
154
    Returns:
155
    List of tuples (including header)
156
    """
157

158
def tupleoftuples(table):
159
    """
160
    Materialize table as a tuple of tuples.
161
    
162
    Parameters:
163
    - table: Input table
164
    
165
    Returns:
166
    Tuple of tuples (including header)
167
    """
168

169
def tupleoflists(table):
170
    """
171
    Materialize table as a tuple of lists.
172
    
173
    Parameters:
174
    - table: Input table
175
    
176
    Returns:
177
    Tuple of lists (including header)
178
    """
179

180
def columns(table, missing=None):
181
    """
182
    Extract table columns as a dictionary of lists.
183
    
184
    Parameters:
185
    - table: Input table
186
    - missing: Value for missing data
187
    
188
    Returns:
189
    Dictionary mapping field names to column lists
190
    """
191

192
def facetcolumns(table, key, missing=None):
193
    """
194
    Extract columns grouped by key values.
195
    
196
    Parameters:
197
    - table: Input table
198
    - key: Field name or function to group by
199
    - missing: Value for missing data
200
    
201
    Returns:
202
    Dictionary mapping key values to column dictionaries
203
    """
204
```
205

206
### Lookup Operations
207

208
Create lookup dictionaries and indexes from table data for fast data access patterns.
209

210
```python { .api }
211
def lookup(table, key, value=None, dictionary=None):
212
    """
213
    Load a dictionary with data from the table, allowing multiple values per key.
214
    
215
    Parameters:
216
    - table: Input table
217
    - key: Field name for dictionary keys
218
    - value: Field name for values (defaults to remaining fields)
219
    - dictionary: Existing dictionary to extend
220
    
221
    Returns:
222
    Dictionary mapping keys to lists of values
223
    """
224

225
def lookupone(table, key, value=None, dictionary=None, strict=False):
226
    """
227
    Load a dictionary expecting one value per key.
228
    
229
    Parameters:
230
    - table: Input table
231
    - key: Field name for dictionary keys
232
    - value: Field name for values
233
    - dictionary: Existing dictionary to extend
234
    - strict: If True, raise error on duplicate keys
235
    
236
    Returns:
237
    Dictionary mapping keys to single values
238
    """
239

240
def dictlookup(table, key, dictionary=None):
241
    """
242
    Load a dictionary where values are complete rows as dictionaries.
243
    
244
    Parameters:
245
    - table: Input table
246
    - key: Field name for dictionary keys
247
    - dictionary: Existing dictionary to extend
248
    
249
    Returns:
250
    Dictionary mapping keys to lists of row dictionaries
251
    """
252

253
def dictlookupone(table, key, dictionary=None, strict=False):
254
    """
255
    Load a dictionary where each value is a single row dictionary.
256
    
257
    Parameters:
258
    - table: Input table
259
    - key: Field name for dictionary keys
260
    - dictionary: Existing dictionary to extend
261
    - strict: If True, raise error on duplicate keys
262
    
263
    Returns:
264
    Dictionary mapping keys to row dictionaries
265
    """
266

267
def recordlookup(table, key, dictionary=None):
268
    """
269
    Load a dictionary where values are Record objects.
270
    
271
    Parameters:
272
    - table: Input table
273
    - key: Field name for dictionary keys
274
    - dictionary: Existing dictionary to extend
275
    
276
    Returns:
277
    Dictionary mapping keys to lists of Record objects
278
    """
279

280
def recordlookupone(table, key, dictionary=None, strict=False):
281
    """
282
    Load a dictionary where each value is a single Record object.
283
    
284
    Parameters:
285
    - table: Input table
286
    - key: Field name for dictionary keys
287
    - dictionary: Existing dictionary to extend
288
    - strict: If True, raise error on duplicate keys
289
    
290
    Returns:
291
    Dictionary mapping keys to Record objects
292
    """
293
```
294

295
### Advanced Functions
296

297
Specialized functions for complex data access patterns and expression evaluation.
298

299
```python { .api }
300
def expr(expression_text, trusted=True):
301
    """
302
    Create a function from a Python expression string for field operations.
303
    
304
    Parameters:
305
    - expression_text: Python expression as string
306
    - trusted: If True, allow all Python expressions
307
    
308
    Returns:
309
    Function that can be used in field operations
310
    """
311

312
def rowgroupby(table, key, value=None):
313
    """
314
    Group table rows by key and return grouped data.
315
    
316
    Parameters:
317
    - table: Input table
318
    - key: Field name or function for grouping
319
    - value: Field name for values
320
    
321
    Returns:
322
    Iterator over (key, group) pairs
323
    """
324

325
def nrows(table):
326
    """
327
    Count the number of data rows in the table.
328
    
329
    Parameters:
330
    - table: Input table
331
    
332
    Returns:
333
    Integer count of rows (excluding header)
334
    """
335
```
336

337
## Usage Examples
338

339
### Basic Table Creation and Access
340

341
```python
342
import petl as etl
343

344
# Create table from lists
345
data = [['name', 'age', 'city'], 
346
        ['Alice', 25, 'New York'], 
347
        ['Bob', 30, 'London']]
348
table = etl.wrap(data)
349

350
# Access header and data
351
print(etl.header(table))  # ('name', 'age', 'city')
352
print(list(etl.data(table)))  # [('Alice', 25, 'New York'), ('Bob', 30, 'London')]
353

354
# Convert to different formats
355
records = list(etl.records(table))
356
print(records[0].name)  # 'Alice'
357

358
dicts = list(etl.dicts(table))
359
print(dicts[0]['age'])  # 25
360
```
361

362
### Creating Lookup Dictionaries
363

364
```python
365
import petl as etl
366

367
table = etl.fromcsv('people.csv')  # name, age, city, country
368

369
# Create lookups for fast data access
370
age_lookup = etl.lookupone(table, 'name', 'age')
371
print(age_lookup['Alice'])  # 25
372

373
# Multiple values per key
374
city_lookup = etl.lookup(table, 'country', 'city')
375
print(city_lookup['USA'])  # ['New York', 'Los Angeles', 'Chicago']
376

377
# Full record lookup
378
record_lookup = etl.recordlookupone(table, 'name')
379
print(record_lookup['Alice'].city)  # 'New York'
380
```