extract-list 0.7__tar.gz → 0.8__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {extract_list-0.7/extract_list.egg-info → extract_list-0.8}/PKG-INFO +99 -35
- {extract_list-0.7 → extract_list-0.8}/README.md +6 -4
- {extract_list-0.7 → extract_list-0.8}/README_pypi.md +88 -30
- {extract_list-0.7 → extract_list-0.8/extract_list.egg-info}/PKG-INFO +99 -35
- {extract_list-0.7 → extract_list-0.8}/extract_list.egg-info/SOURCES.txt +2 -0
- extract_list-0.8/extract_list.egg-info/requires.txt +12 -0
- {extract_list-0.7 → extract_list-0.8}/pyproject.toml +2 -1
- {extract_list-0.7 → extract_list-0.8}/setup.py +12 -7
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/__main__.py +2 -2
- extract_list-0.8/src/extract_list/cfg_descriptions.py +221 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/commontypes.py +2 -2
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/config_enums.py +6 -0
- extract_list-0.8/src/extract_list/edit_cfg.py +122 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/extract_cmd.py +42 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/extract_config.py +33 -165
- extract_list-0.8/src/extract_list/extract_config_params.py +197 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/extract_data.py +114 -87
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/extract_func.py +9 -3
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/generate_cfg.py +16 -6
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/generate_txt_ex_common.py +7 -7
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/generate_txt_example_json.py +1 -1
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/generate_txt_example_xml.py +18 -6
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/generate_txt_sw_to_rrs.py +27 -9
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/generate_txt_syntax.py +23 -6
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/handle_input.py +4 -4
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/handle_json_xml_output.py +10 -11
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/output_config.py +28 -8
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/validators.py +68 -44
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/xl_migrate_cfg_warn_hook.py +1 -1
- extract_list-0.7/extract_list.egg-info/requires.txt +0 -7
- extract_list-0.7/src/extract_list/extract_config_params.py +0 -143
- {extract_list-0.7 → extract_list-0.8}/LICENSE.txt +0 -0
- {extract_list-0.7 → extract_list-0.8}/extract_list.egg-info/dependency_links.txt +0 -0
- {extract_list-0.7 → extract_list-0.8}/extract_list.egg-info/top_level.txt +0 -0
- {extract_list-0.7 → extract_list-0.8}/setup.cfg +0 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/__init__.py +0 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/handle_output.py +0 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/handle_txt_output.py +0 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/member_paths.py +0 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/py.typed +0 -0
- {extract_list-0.7 → extract_list-0.8}/src/extract_list/xl_version.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: extract-list
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8
|
|
4
4
|
Summary: Extract a list from JSON or XML, save to excel, csv, etc.
|
|
5
5
|
Author: Tom Björkholm
|
|
6
6
|
Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
|
|
@@ -9,6 +9,7 @@ Project-URL: Source code, https://github.com/tom-bjorkholm/extract-list
|
|
|
9
9
|
Classifier: Programming Language :: Python :: 3
|
|
10
10
|
Classifier: Programming Language :: Python :: 3.13
|
|
11
11
|
Classifier: Programming Language :: Python :: 3.14
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
12
13
|
Classifier: Operating System :: OS Independent
|
|
13
14
|
Classifier: Intended Audience :: Other Audience
|
|
14
15
|
Classifier: Intended Audience :: Developers
|
|
@@ -18,14 +19,19 @@ Requires-Python: >=3.13
|
|
|
18
19
|
Description-Content-Type: text/markdown
|
|
19
20
|
License-File: LICENSE.txt
|
|
20
21
|
Requires-Dist: argcomplete>=3.7.2
|
|
21
|
-
Requires-Dist: config-as-json>=1.
|
|
22
|
-
Requires-Dist: tableio>=1.
|
|
23
|
-
Requires-Dist: tableio-cfg-json>=1
|
|
24
|
-
Requires-Dist: versionreporter>=0.
|
|
22
|
+
Requires-Dist: config-as-json>=1.9
|
|
23
|
+
Requires-Dist: tableio>=1.3
|
|
24
|
+
Requires-Dist: tableio-cfg-json>=2.1
|
|
25
|
+
Requires-Dist: versionreporter>=0.5
|
|
25
26
|
Requires-Dist: xmltodict>=1.0.4
|
|
26
27
|
Requires-Dist: types-xmltodict>=1.0.1.20260518
|
|
28
|
+
Requires-Dist: edit-cfg-json>=1.1.0
|
|
29
|
+
Requires-Dist: edit-cfg-json-tk>=1.1.0
|
|
30
|
+
Provides-Extra: textual
|
|
31
|
+
Requires-Dist: edit-cfg-json-textual>=1.1.0; extra == "textual"
|
|
27
32
|
Dynamic: author
|
|
28
33
|
Dynamic: license-file
|
|
34
|
+
Dynamic: provides-extra
|
|
29
35
|
Dynamic: requires-dist
|
|
30
36
|
Dynamic: requires-python
|
|
31
37
|
|
|
@@ -42,20 +48,20 @@ table-like format.
|
|
|
42
48
|
|
|
43
49
|
extract-list:
|
|
44
50
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
51
|
+
- reads data from an XML file or a JSON file
|
|
52
|
+
- extracts the configured parts of that input data
|
|
53
|
+
- writes the extracted data as rows and columns
|
|
48
54
|
|
|
49
55
|
Examples of output formats include:
|
|
50
56
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
57
|
+
- Excel
|
|
58
|
+
- CSV
|
|
59
|
+
- ODS
|
|
60
|
+
- HTML
|
|
61
|
+
- Markdown
|
|
62
|
+
- plain text
|
|
63
|
+
- JSON
|
|
64
|
+
- XML
|
|
59
65
|
|
|
60
66
|
The exact output choices available in an installed environment can be listed
|
|
61
67
|
with the `cfg-example --help` command. Some output formats are provided through
|
|
@@ -87,6 +93,7 @@ python3 -m extract_list --help
|
|
|
87
93
|
python3 -m extract_list cfg-example --help
|
|
88
94
|
python3 -m extract_list extract --help
|
|
89
95
|
python3 -m extract_list cfg-example -k example_json -t Excel -o example.cfg
|
|
96
|
+
python3 -m extract_list editcfg -i example.cfg
|
|
90
97
|
python3 -m extract_list extract -c example.cfg -i input.json -o output.xlsx
|
|
91
98
|
```
|
|
92
99
|
|
|
@@ -97,6 +104,7 @@ python -m extract_list --help
|
|
|
97
104
|
python -m extract_list cfg-example --help
|
|
98
105
|
python -m extract_list extract --help
|
|
99
106
|
python -m extract_list cfg-example -k example_json -t Excel -o example.cfg
|
|
107
|
+
python -m extract_list editcfg -i example.cfg
|
|
100
108
|
python -m extract_list extract -c example.cfg -i input.json -o output.xlsx
|
|
101
109
|
```
|
|
102
110
|
|
|
@@ -108,6 +116,8 @@ python -m extract_list extract -c example.cfg -i input.json -o output.xlsx
|
|
|
108
116
|
description file.
|
|
109
117
|
3. Find the example that is closest to what you want to extract.
|
|
110
118
|
4. Modify that configuration file to match your input data and desired output.
|
|
119
|
+
The `editcfg` sub-command opens it in an editor that explains every setting
|
|
120
|
+
and checks the values (see *Editing a configuration file* below).
|
|
111
121
|
5. Use the `extract` sub-command to read your data and write the output file.
|
|
112
122
|
6. Check the produced output. If needed, adjust the configuration and run the
|
|
113
123
|
extraction again.
|
|
@@ -122,6 +132,41 @@ The generated `.txt` file is the best place to look for detailed configuration
|
|
|
122
132
|
reference text, because it is generated by the same installed version of
|
|
123
133
|
extract-list that will read the configuration.
|
|
124
134
|
|
|
135
|
+
## Editing a configuration file
|
|
136
|
+
|
|
137
|
+
The `editcfg` sub-command (also available as `edit-cfg`) opens a
|
|
138
|
+
configuration file in an editor made for it. The editor shows every setting
|
|
139
|
+
with an explanation of what it does, offers the allowed values to choose from
|
|
140
|
+
where there is a fixed set of them, and checks the whole configuration before
|
|
141
|
+
it is saved, so that a saved file is one that `extract` accepts.
|
|
142
|
+
|
|
143
|
+
```sh
|
|
144
|
+
python3 -m extract_list editcfg -i example.cfg
|
|
145
|
+
python3 -m extract_list editcfg -i example.cfg -o changed.cfg
|
|
146
|
+
python3 -m extract_list editcfg -i example.cfg --ui tk
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
(Use `python` instead of `python3` on Microsoft Windows.)
|
|
150
|
+
|
|
151
|
+
- `-i` names the configuration file to edit. It must exist; create one with
|
|
152
|
+
`cfg-example` first.
|
|
153
|
+
- `-o` names the file to save to, when that is not the input file.
|
|
154
|
+
- `--ui` chooses the user interface. Without it the editor opens in a window
|
|
155
|
+
where there is a display, and in the terminal where there is none. The
|
|
156
|
+
terminal editor is optional and is installed with
|
|
157
|
+
`pip3 install --upgrade "extract-list[textual]"`. `--help` lists the user
|
|
158
|
+
interfaces that can run on the machine.
|
|
159
|
+
|
|
160
|
+
How to use the editor (folding, finding, keys, saving and backups) is described
|
|
161
|
+
in the
|
|
162
|
+
[end user's guide of edit-cfg-json](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/end_users_guide.md).
|
|
163
|
+
Key combinations, backup files and which user interface is preferred are
|
|
164
|
+
settings of the editor itself. They are read from the file named by the
|
|
165
|
+
environment variable `CFG_EDIT_CFG_JSON`, else from `$HOME/.edit-cfg-json-tk.cfg`
|
|
166
|
+
or `$HOME/.edit-cfg-json-textual.cfg` for that editor, else from
|
|
167
|
+
`$HOME/.edit-cfg-json.cfg`. A file name given when saving without an extension
|
|
168
|
+
gets `.cfg`.
|
|
169
|
+
|
|
125
170
|
## Migrating old configuration files
|
|
126
171
|
|
|
127
172
|
Version 0.3 uses the nested `output` configuration object. Older 0.2-style
|
|
@@ -156,16 +201,17 @@ The encoding for the configuration file must be UTF-8. US-ASCII is a subset of
|
|
|
156
201
|
UTF-8.
|
|
157
202
|
|
|
158
203
|
It is recommended to generate a configuration file with `cfg-example` and then
|
|
159
|
-
edit that file
|
|
160
|
-
generated examples are a much safer starting
|
|
204
|
+
edit that file, preferably with `editcfg`. Writing a configuration file
|
|
205
|
+
from scratch is possible, but the generated examples are a much safer starting
|
|
206
|
+
point.
|
|
161
207
|
|
|
162
208
|
### Type of input file
|
|
163
209
|
|
|
164
210
|
The type of input file to read is determined by `infile_type`. `infile_type`
|
|
165
211
|
can have these values:
|
|
166
212
|
|
|
167
|
-
|
|
168
|
-
|
|
213
|
+
- `"JSON"`
|
|
214
|
+
- `"XML"`
|
|
169
215
|
|
|
170
216
|
Both JSON and XML are text file formats, so the input file has a character
|
|
171
217
|
encoding. This is specified with `infile_encoding`. Unless you know that you
|
|
@@ -180,15 +226,15 @@ normalized when the configuration is read.
|
|
|
180
226
|
|
|
181
227
|
Examples of commonly useful `output.format_name` values include:
|
|
182
228
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
229
|
+
- `"Excel"`
|
|
230
|
+
- `"CSV"`
|
|
231
|
+
- `"ODS"`
|
|
232
|
+
- `"HTML"`
|
|
233
|
+
- `"md"`
|
|
234
|
+
- `"txt"`
|
|
235
|
+
- `"JSON"`
|
|
236
|
+
- `"XML"`
|
|
237
|
+
- `"Plaintxt"`
|
|
192
238
|
|
|
193
239
|
Run `python3 -m extract_list cfg-example --help` on macOS or Linux, or
|
|
194
240
|
`python -m extract_list cfg-example --help` on Windows, to see the full list of
|
|
@@ -229,6 +275,17 @@ The `line` member of `main_line` and `linked_lines` is a list of strings. This
|
|
|
229
275
|
list is the path of keys to the input records. Directly below that path there
|
|
230
276
|
is either a list or a dictionary of records.
|
|
231
277
|
|
|
278
|
+
A dictionary directly below that path is normally read as records indexed by
|
|
279
|
+
their keys. For XML input this is ambiguous: an element that is repeated gives
|
|
280
|
+
a list, but the same element occurring only once gives a single record, which
|
|
281
|
+
then would be misread as records indexed by key. Set the
|
|
282
|
+
`dict_at_line_is_record` member to `true` when the path ends at such a repeated
|
|
283
|
+
element (for example one `<customers>` element per customer). A dictionary
|
|
284
|
+
directly below the path is then read as one single record. Keep it `false`
|
|
285
|
+
when the path ends at an element holding the records keyed by their element
|
|
286
|
+
names (for example `<orders><o1>...</o1><o2>...</o2></orders>`). The same rule
|
|
287
|
+
applies to JSON input.
|
|
288
|
+
|
|
232
289
|
The records of the `main_line` are indexed in the input, either by integer
|
|
233
290
|
position in a list or by key in a dictionary. If you want this index or key in
|
|
234
291
|
the output, set `include_key` to `true`. If not, set it to `false`. The output
|
|
@@ -242,7 +299,11 @@ purchase order may contain several purchased items. Because the output is a
|
|
|
242
299
|
list of columns, such an input record must be expanded into several output
|
|
243
300
|
rows. The shared values from the input record are duplicated on those output
|
|
244
301
|
rows. The `expand_at` member contains the relative paths where this expansion
|
|
245
|
-
should happen.
|
|
302
|
+
should happen. The expansion works the same whether the records are held in a
|
|
303
|
+
list or in a dictionary. A list at such a path gives one output row per
|
|
304
|
+
element. A single value that is not a list, such as an XML element that occurs
|
|
305
|
+
only once, or a missing value leaves the record as one row. An empty list gives
|
|
306
|
+
no row, so that record is left out of the output.
|
|
246
307
|
|
|
247
308
|
There can be only one `main_line`. There may be any number of linked lines.
|
|
248
309
|
The linked lines are configured as an array in `linked_lines`.
|
|
@@ -273,8 +334,11 @@ the input has XML attributes, the attribute key has an `@` prefix. To handle
|
|
|
273
334
|
this, `in_xml_strip_at` can be set to `true` or `false`. If it is `true`, a
|
|
274
335
|
leading `@` character is stripped from each key.
|
|
275
336
|
|
|
276
|
-
|
|
277
|
-
|
|
337
|
+
XML output has the root element `<data>` with one `<row>` element per output
|
|
338
|
+
line, in output order. The `out_xml_attributes` setting specifies column names
|
|
339
|
+
that should be written as XML attributes of `<row>` instead of as nested
|
|
340
|
+
elements. For XML output each column name must be a valid XML name: a letter
|
|
341
|
+
or `_` and then only letters, digits, `_`, `-` or `.`.
|
|
278
342
|
|
|
279
343
|
### Output column order
|
|
280
344
|
|
|
@@ -299,10 +363,10 @@ Source code and tests are available at
|
|
|
299
363
|
|
|
300
364
|
## Test summary
|
|
301
365
|
|
|
302
|
-
- Test result:
|
|
366
|
+
- Test result: 1524 passed in 57s
|
|
303
367
|
- No flake8 warnings.
|
|
304
368
|
- No mypy errors found.
|
|
305
369
|
- No pylint warnings.
|
|
306
370
|
- No python layout warnings.
|
|
307
|
-
- Built version(s): 0.
|
|
308
|
-
- Build and test using Python 3.
|
|
371
|
+
- Built version(s): 0.8
|
|
372
|
+
- Build and test using Python 3.15.2
|
|
@@ -25,7 +25,9 @@ This small Python application:
|
|
|
25
25
|
- LaTeX
|
|
26
26
|
|
|
27
27
|
How this is done is governed by a configuration file. The application can
|
|
28
|
-
create example configuration files with accompanying description text files
|
|
28
|
+
create example configuration files with accompanying description text files,
|
|
29
|
+
and open a configuration file in an editor that explains every setting and
|
|
30
|
+
checks the values before saving (the `editcfg` sub-command).
|
|
29
31
|
|
|
30
32
|
## Using it
|
|
31
33
|
|
|
@@ -111,10 +113,10 @@ the built and installed application in the virtual environment `./venv`.
|
|
|
111
113
|
|
|
112
114
|
## Test summary
|
|
113
115
|
|
|
114
|
-
- Test result:
|
|
116
|
+
- Test result: 1524 passed in 57s
|
|
115
117
|
- No flake8 warnings.
|
|
116
118
|
- No mypy errors found.
|
|
117
119
|
- No pylint warnings.
|
|
118
120
|
- No python layout warnings.
|
|
119
|
-
- Built version(s): 0.
|
|
120
|
-
- Build and test using Python 3.
|
|
121
|
+
- Built version(s): 0.8
|
|
122
|
+
- Build and test using Python 3.15.2
|
|
@@ -11,20 +11,20 @@ table-like format.
|
|
|
11
11
|
|
|
12
12
|
extract-list:
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
14
|
+
- reads data from an XML file or a JSON file
|
|
15
|
+
- extracts the configured parts of that input data
|
|
16
|
+
- writes the extracted data as rows and columns
|
|
17
17
|
|
|
18
18
|
Examples of output formats include:
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
20
|
+
- Excel
|
|
21
|
+
- CSV
|
|
22
|
+
- ODS
|
|
23
|
+
- HTML
|
|
24
|
+
- Markdown
|
|
25
|
+
- plain text
|
|
26
|
+
- JSON
|
|
27
|
+
- XML
|
|
28
28
|
|
|
29
29
|
The exact output choices available in an installed environment can be listed
|
|
30
30
|
with the `cfg-example --help` command. Some output formats are provided through
|
|
@@ -56,6 +56,7 @@ python3 -m extract_list --help
|
|
|
56
56
|
python3 -m extract_list cfg-example --help
|
|
57
57
|
python3 -m extract_list extract --help
|
|
58
58
|
python3 -m extract_list cfg-example -k example_json -t Excel -o example.cfg
|
|
59
|
+
python3 -m extract_list editcfg -i example.cfg
|
|
59
60
|
python3 -m extract_list extract -c example.cfg -i input.json -o output.xlsx
|
|
60
61
|
```
|
|
61
62
|
|
|
@@ -66,6 +67,7 @@ python -m extract_list --help
|
|
|
66
67
|
python -m extract_list cfg-example --help
|
|
67
68
|
python -m extract_list extract --help
|
|
68
69
|
python -m extract_list cfg-example -k example_json -t Excel -o example.cfg
|
|
70
|
+
python -m extract_list editcfg -i example.cfg
|
|
69
71
|
python -m extract_list extract -c example.cfg -i input.json -o output.xlsx
|
|
70
72
|
```
|
|
71
73
|
|
|
@@ -77,6 +79,8 @@ python -m extract_list extract -c example.cfg -i input.json -o output.xlsx
|
|
|
77
79
|
description file.
|
|
78
80
|
3. Find the example that is closest to what you want to extract.
|
|
79
81
|
4. Modify that configuration file to match your input data and desired output.
|
|
82
|
+
The `editcfg` sub-command opens it in an editor that explains every setting
|
|
83
|
+
and checks the values (see *Editing a configuration file* below).
|
|
80
84
|
5. Use the `extract` sub-command to read your data and write the output file.
|
|
81
85
|
6. Check the produced output. If needed, adjust the configuration and run the
|
|
82
86
|
extraction again.
|
|
@@ -91,6 +95,41 @@ The generated `.txt` file is the best place to look for detailed configuration
|
|
|
91
95
|
reference text, because it is generated by the same installed version of
|
|
92
96
|
extract-list that will read the configuration.
|
|
93
97
|
|
|
98
|
+
## Editing a configuration file
|
|
99
|
+
|
|
100
|
+
The `editcfg` sub-command (also available as `edit-cfg`) opens a
|
|
101
|
+
configuration file in an editor made for it. The editor shows every setting
|
|
102
|
+
with an explanation of what it does, offers the allowed values to choose from
|
|
103
|
+
where there is a fixed set of them, and checks the whole configuration before
|
|
104
|
+
it is saved, so that a saved file is one that `extract` accepts.
|
|
105
|
+
|
|
106
|
+
```sh
|
|
107
|
+
python3 -m extract_list editcfg -i example.cfg
|
|
108
|
+
python3 -m extract_list editcfg -i example.cfg -o changed.cfg
|
|
109
|
+
python3 -m extract_list editcfg -i example.cfg --ui tk
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
(Use `python` instead of `python3` on Microsoft Windows.)
|
|
113
|
+
|
|
114
|
+
- `-i` names the configuration file to edit. It must exist; create one with
|
|
115
|
+
`cfg-example` first.
|
|
116
|
+
- `-o` names the file to save to, when that is not the input file.
|
|
117
|
+
- `--ui` chooses the user interface. Without it the editor opens in a window
|
|
118
|
+
where there is a display, and in the terminal where there is none. The
|
|
119
|
+
terminal editor is optional and is installed with
|
|
120
|
+
`pip3 install --upgrade "extract-list[textual]"`. `--help` lists the user
|
|
121
|
+
interfaces that can run on the machine.
|
|
122
|
+
|
|
123
|
+
How to use the editor (folding, finding, keys, saving and backups) is described
|
|
124
|
+
in the
|
|
125
|
+
[end user's guide of edit-cfg-json](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/end_users_guide.md).
|
|
126
|
+
Key combinations, backup files and which user interface is preferred are
|
|
127
|
+
settings of the editor itself. They are read from the file named by the
|
|
128
|
+
environment variable `CFG_EDIT_CFG_JSON`, else from `$HOME/.edit-cfg-json-tk.cfg`
|
|
129
|
+
or `$HOME/.edit-cfg-json-textual.cfg` for that editor, else from
|
|
130
|
+
`$HOME/.edit-cfg-json.cfg`. A file name given when saving without an extension
|
|
131
|
+
gets `.cfg`.
|
|
132
|
+
|
|
94
133
|
## Migrating old configuration files
|
|
95
134
|
|
|
96
135
|
Version 0.3 uses the nested `output` configuration object. Older 0.2-style
|
|
@@ -125,16 +164,17 @@ The encoding for the configuration file must be UTF-8. US-ASCII is a subset of
|
|
|
125
164
|
UTF-8.
|
|
126
165
|
|
|
127
166
|
It is recommended to generate a configuration file with `cfg-example` and then
|
|
128
|
-
edit that file
|
|
129
|
-
generated examples are a much safer starting
|
|
167
|
+
edit that file, preferably with `editcfg`. Writing a configuration file
|
|
168
|
+
from scratch is possible, but the generated examples are a much safer starting
|
|
169
|
+
point.
|
|
130
170
|
|
|
131
171
|
### Type of input file
|
|
132
172
|
|
|
133
173
|
The type of input file to read is determined by `infile_type`. `infile_type`
|
|
134
174
|
can have these values:
|
|
135
175
|
|
|
136
|
-
|
|
137
|
-
|
|
176
|
+
- `"JSON"`
|
|
177
|
+
- `"XML"`
|
|
138
178
|
|
|
139
179
|
Both JSON and XML are text file formats, so the input file has a character
|
|
140
180
|
encoding. This is specified with `infile_encoding`. Unless you know that you
|
|
@@ -149,15 +189,15 @@ normalized when the configuration is read.
|
|
|
149
189
|
|
|
150
190
|
Examples of commonly useful `output.format_name` values include:
|
|
151
191
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
192
|
+
- `"Excel"`
|
|
193
|
+
- `"CSV"`
|
|
194
|
+
- `"ODS"`
|
|
195
|
+
- `"HTML"`
|
|
196
|
+
- `"md"`
|
|
197
|
+
- `"txt"`
|
|
198
|
+
- `"JSON"`
|
|
199
|
+
- `"XML"`
|
|
200
|
+
- `"Plaintxt"`
|
|
161
201
|
|
|
162
202
|
Run `python3 -m extract_list cfg-example --help` on macOS or Linux, or
|
|
163
203
|
`python -m extract_list cfg-example --help` on Windows, to see the full list of
|
|
@@ -198,6 +238,17 @@ The `line` member of `main_line` and `linked_lines` is a list of strings. This
|
|
|
198
238
|
list is the path of keys to the input records. Directly below that path there
|
|
199
239
|
is either a list or a dictionary of records.
|
|
200
240
|
|
|
241
|
+
A dictionary directly below that path is normally read as records indexed by
|
|
242
|
+
their keys. For XML input this is ambiguous: an element that is repeated gives
|
|
243
|
+
a list, but the same element occurring only once gives a single record, which
|
|
244
|
+
then would be misread as records indexed by key. Set the
|
|
245
|
+
`dict_at_line_is_record` member to `true` when the path ends at such a repeated
|
|
246
|
+
element (for example one `<customers>` element per customer). A dictionary
|
|
247
|
+
directly below the path is then read as one single record. Keep it `false`
|
|
248
|
+
when the path ends at an element holding the records keyed by their element
|
|
249
|
+
names (for example `<orders><o1>...</o1><o2>...</o2></orders>`). The same rule
|
|
250
|
+
applies to JSON input.
|
|
251
|
+
|
|
201
252
|
The records of the `main_line` are indexed in the input, either by integer
|
|
202
253
|
position in a list or by key in a dictionary. If you want this index or key in
|
|
203
254
|
the output, set `include_key` to `true`. If not, set it to `false`. The output
|
|
@@ -211,7 +262,11 @@ purchase order may contain several purchased items. Because the output is a
|
|
|
211
262
|
list of columns, such an input record must be expanded into several output
|
|
212
263
|
rows. The shared values from the input record are duplicated on those output
|
|
213
264
|
rows. The `expand_at` member contains the relative paths where this expansion
|
|
214
|
-
should happen.
|
|
265
|
+
should happen. The expansion works the same whether the records are held in a
|
|
266
|
+
list or in a dictionary. A list at such a path gives one output row per
|
|
267
|
+
element. A single value that is not a list, such as an XML element that occurs
|
|
268
|
+
only once, or a missing value leaves the record as one row. An empty list gives
|
|
269
|
+
no row, so that record is left out of the output.
|
|
215
270
|
|
|
216
271
|
There can be only one `main_line`. There may be any number of linked lines.
|
|
217
272
|
The linked lines are configured as an array in `linked_lines`.
|
|
@@ -242,8 +297,11 @@ the input has XML attributes, the attribute key has an `@` prefix. To handle
|
|
|
242
297
|
this, `in_xml_strip_at` can be set to `true` or `false`. If it is `true`, a
|
|
243
298
|
leading `@` character is stripped from each key.
|
|
244
299
|
|
|
245
|
-
|
|
246
|
-
|
|
300
|
+
XML output has the root element `<data>` with one `<row>` element per output
|
|
301
|
+
line, in output order. The `out_xml_attributes` setting specifies column names
|
|
302
|
+
that should be written as XML attributes of `<row>` instead of as nested
|
|
303
|
+
elements. For XML output each column name must be a valid XML name: a letter
|
|
304
|
+
or `_` and then only letters, digits, `_`, `-` or `.`.
|
|
247
305
|
|
|
248
306
|
### Output column order
|
|
249
307
|
|
|
@@ -268,10 +326,10 @@ Source code and tests are available at
|
|
|
268
326
|
|
|
269
327
|
## Test summary
|
|
270
328
|
|
|
271
|
-
- Test result:
|
|
329
|
+
- Test result: 1524 passed in 57s
|
|
272
330
|
- No flake8 warnings.
|
|
273
331
|
- No mypy errors found.
|
|
274
332
|
- No pylint warnings.
|
|
275
333
|
- No python layout warnings.
|
|
276
|
-
- Built version(s): 0.
|
|
277
|
-
- Build and test using Python 3.
|
|
334
|
+
- Built version(s): 0.8
|
|
335
|
+
- Build and test using Python 3.15.2
|