dclq 2.89.0__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.
Files changed (9) hide show
  1. dclq-2.89.0/.gitignore +119 -0
  2. dclq-2.89.0/LICENSE +21 -0
  3. dclq-2.89.0/PKG-INFO +280 -0
  4. dclq-2.89.0/README.md +250 -0
  5. dclq-2.89.0/dclq/__init__.py +5 -0
  6. dclq-2.89.0/dclq/__main__.py +5 -0
  7. dclq-2.89.0/dclq/cli.py +1095 -0
  8. dclq-2.89.0/dclq/document.py +598 -0
  9. dclq-2.89.0/pyproject.toml +57 -0
dclq-2.89.0/.gitignore ADDED
@@ -0,0 +1,119 @@
1
+ node_modules/
2
+
3
+ .idea/
4
+ *~
5
+ *.DS_Store
6
+ test/data/constructed_images*
7
+ test/data/doc/constructed_doc*.html
8
+ test/data/doc/constructed_doc*.yaml
9
+ test/data/doc/constructed_doc*.json
10
+ test/data/doc/constructed_doc*.dt
11
+ test/data/doc/constructed_doc*.md
12
+
13
+ # Byte-compiled / optimized / DLL files
14
+ __pycache__/
15
+ *.py[cod]
16
+ *$py.class
17
+
18
+ # C extensions
19
+ *.so
20
+
21
+ # Distribution / packaging
22
+ .Python
23
+ build/
24
+ develop-eggs/
25
+ dist/
26
+ downloads/
27
+ eggs/
28
+ .eggs/
29
+ lib/
30
+ lib64/
31
+ parts/
32
+ sdist/
33
+ var/
34
+ wheels/
35
+ *.egg-info/
36
+ .installed.cfg
37
+ *.egg
38
+ MANIFEST
39
+
40
+ # PyInstaller
41
+ # Usually these files are written by a python script from a template
42
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
43
+ *.manifest
44
+ *.spec
45
+
46
+ # Installer logs
47
+ pip-log.txt
48
+ pip-delete-this-directory.txt
49
+
50
+ # Unit test / coverage reports
51
+ htmlcov/
52
+ .tox/
53
+ .coverage
54
+ .coverage.*
55
+ .cache
56
+ nosetests.xml
57
+ coverage.xml
58
+ *.cover
59
+ .hypothesis/
60
+ .pytest_cache/
61
+
62
+ # Translations
63
+ *.mo
64
+ *.pot
65
+
66
+ # Django stuff:
67
+ *.log
68
+ local_settings.py
69
+ db.sqlite3
70
+
71
+ # Flask stuff:
72
+ instance/
73
+ .webassets-cache
74
+
75
+ # Scrapy stuff:
76
+ .scrapy
77
+
78
+ # Sphinx documentation
79
+ docs/_build/
80
+
81
+ # PyBuilder
82
+ target/
83
+
84
+ # Jupyter Notebook
85
+ .ipynb_checkpoints
86
+
87
+ # pyenv
88
+ .python-version
89
+
90
+ # celery beat schedule file
91
+ celerybeat-schedule
92
+
93
+ # SageMath parsed files
94
+ *.sage.py
95
+
96
+ # Environments
97
+ .env
98
+ .venv
99
+ env/
100
+ venv/
101
+ ENV/
102
+ env.bak/
103
+ venv.bak/
104
+
105
+ # Spyder project settings
106
+ .spyderproject
107
+ .spyproject
108
+
109
+ # Rope project settings
110
+ .ropeproject
111
+
112
+ # mkdocs documentation
113
+ /site
114
+
115
+ # mypy
116
+ .mypy_cache/
117
+
118
+ # VisualStudioCode
119
+ .vscode/
dclq-2.89.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Docling Project
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
dclq-2.89.0/PKG-INFO ADDED
@@ -0,0 +1,280 @@
1
+ Metadata-Version: 2.4
2
+ Name: dclq
3
+ Version: 2.89.0
4
+ Summary: Query DocLang documents: grep, list, outline, and XPath over semantic document structure
5
+ Project-URL: homepage, https://github.com/docling-project
6
+ Project-URL: repository, https://github.com/docling-project/docling-core
7
+ Project-URL: issues, https://github.com/docling-project/docling-core/issues
8
+ Project-URL: changelog, https://github.com/docling-project/docling-core/blob/main/CHANGELOG.md
9
+ Author-email: Christoph Auer <cau@zurich.ibm.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: cli,doclang,docling,grep,query,search,xpath
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Natural Language :: English
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
25
+ Classifier: Topic :: Text Processing
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: <4.0,>=3.10
28
+ Requires-Dist: docling-core[dclq]==2.89.0
29
+ Description-Content-Type: text/markdown
30
+
31
+ # dclq
32
+
33
+ > [!WARNING]
34
+ > **Experimental:** `dclq` is experimental. Its commands, options, output
35
+ > formats, exit codes, and functionality may change in breaking ways without
36
+ > prior warning.
37
+
38
+ <p align="center">
39
+ <strong>Query structured documents.</strong><br>
40
+ Grep, list, outline, and XPath over headings, sections, lists, and
41
+ tables—and get an XPath back for every result.
42
+ </p>
43
+
44
+ ## What is dclq?
45
+
46
+ `dclq` brings the familiar grep workflow to
47
+ [DocLang](https://doclang.ai) documents. It queries semantic document units
48
+ and returns bounded evidence with reusable XPath addresses.
49
+
50
+ ```console
51
+ $ dclq grep 'GPU|CPU' paper.dclg \
52
+ --within-xpath '/heading[13]' --section -n
53
+ /list[4]/ldiv[1]:- AWS EC2 VM ... Nvidia L4 GPU ...
54
+ /text[42]:All experiments ... GPU acceleration ... x86 CPU ...
55
+ ```
56
+
57
+ ## Features
58
+
59
+ - 🔎 **Semantic search** across headings, paragraphs, captions, footnotes,
60
+ list items, table cells, formulas, code, and metadata
61
+ - 🧭 **Structural context** with section-aware neighbours, list siblings, table
62
+ headers, captions, and document reading order
63
+ - 🔗 **Reusable XPath addresses** for every result
64
+ - 🎯 **Precise filters** for sections, XPath regions, pages, layers, and
65
+ semantic types
66
+ - 📑 **Document navigation** with structural inventory, heading outlines,
67
+ semantic retrieval, and raw XPath selection
68
+ - 📦 **DocLang input** from `.dclg`, `.dclg.xml`, `.xml`, `.dclx`, or standard
69
+ input
70
+ - 🤖 **Pipeline-friendly output** in text, JSON, and JSONL
71
+ - ⚡ **grep-compatible behavior** with regular expressions, fixed strings,
72
+ context flags, counts, file listing, quiet mode, and exit codes
73
+ - 🔒 **Local, deterministic, read-only execution** with bounded output
74
+
75
+ ## Quickstart
76
+
77
+ ### 1. Install
78
+
79
+ ```bash
80
+ python -m pip install dclq
81
+ ```
82
+
83
+ ### 2. Convert source documents to DocLang
84
+
85
+ ```bash
86
+ python -m pip install docling
87
+ docling report.pdf handbook.docx --to dclx --output converted
88
+ ```
89
+
90
+ ### 3. Search
91
+
92
+ ```bash
93
+ dclq grep -i 'termination|cancellation' converted/report.dclx
94
+ ```
95
+
96
+ Without a pattern, `dclq list` enumerates units instead:
97
+
98
+ ```bash
99
+ dclq list converted/report.dclx --type table_cell --page 3
100
+ ```
101
+
102
+ ## Examples
103
+
104
+ ### Inspect a document
105
+
106
+ ```console
107
+ $ dclq inspect paper.dclx
108
+ paper.dclx
109
+ Type: dclx
110
+ Pages: 9
111
+ Semantic units: 612
112
+ Elements: caption=9, code=3, formula=4, heading=18, list=5, picture=6, table=5, text=434
113
+ Metadata: author=2, date=1, keywords=1
114
+ ```
115
+
116
+ ### Navigate the heading hierarchy
117
+
118
+ ```console
119
+ $ dclq outline paper.dclg
120
+ Docling: An Efficient Open-Source Toolkit for AI-driven Document Conversion /heading[1]
121
+ Abstract /heading[2]
122
+ 1 Introduction /heading[3]
123
+ ...
124
+ 3 Design and Architecture /heading[5]
125
+ 5 Performance /heading[11]
126
+ 5.2 System Configurations /heading[13]
127
+ ...
128
+ 6 Applications /heading[16]
129
+ ...
130
+ References /heading[19]
131
+ ```
132
+
133
+ ### Retrieve a section by XPath
134
+
135
+ ```console
136
+ $ dclq show paper.dclg '/heading[13]' --section --max-chars 220 -n
137
+ /heading[13]:5.2 System Configurations
138
+ /text[41]:We schedule our benchmark experiments each on two different systems...
139
+ /list[4]/ldiv[1]:- AWS EC2 VM (g6.xlarge)...
140
+ /list[4]/ldiv[2]:- MacBook Pro M3 Max (ARM)...
141
+ /text[42]:All experiments on the AWS EC2 VM...
142
+ /table[1]/ched[1]:Asset
143
+ /table[1]/ched[2]:Version
144
+ ...
145
+ ```
146
+
147
+ Each section element keeps its own reusable XPath.
148
+
149
+ ### Query the source XML
150
+
151
+ JSON includes document identity alongside scalar results:
152
+
153
+ ```console
154
+ $ dclq select paper.dclg 'count(//page_break) + 1' --format json
155
+ {
156
+ "document": "paper.dclg",
157
+ "sha256": "284b9b63bf3e11a75ffd2ad23c7505a9b5e75407531a13044ceae001e0d1550e",
158
+ "value": 8.0
159
+ }
160
+
161
+ $ dclq select paper.dclg \
162
+ 'normalize-space(string(//table[1]/caption))'
163
+ Table 1: Versions and configuration options considered for each tested asset. * denotes the default setting.
164
+ ```
165
+
166
+ ### Search a table cell with its structural context
167
+
168
+ The direct JSON record includes document identity, match offsets, and
169
+ contributing document items; the relevant fields are shown here:
170
+
171
+ ```console
172
+ $ dclq grep -F '2.73 5.39' paper.dclx --format json
173
+ [
174
+ {
175
+ ...
176
+ "xpaths": ["/d:doclang/d:table[1]/d:fcel[8]"],
177
+ "logical_type": "table_cell",
178
+ "text": "2.73 5.39",
179
+ "pages": [1],
180
+ "cell_context": {
181
+ "column_headers": ["Inference time (secs)"],
182
+ "caption": "Table 1. HPO performed in OTSL and HTML representation on the same transformer-based TableFormer..."
183
+ }
184
+ }
185
+ ]
186
+ ```
187
+
188
+ ### Get list-aware context
189
+
190
+ ```console
191
+ $ dclq grep -F 'Third item with numId 2' handbook.dclx \
192
+ -C 1 --context-scope auto -n
193
+ /list[7]/ldiv[2]-2. Second item with numId 2
194
+ /list[7]/ldiv[3]:3. Third item with numId 2
195
+ /list[7]/ldiv[4]-4. Fourth item with numId 2
196
+ ```
197
+
198
+ ### Use dclq in shell pipelines
199
+
200
+ ```bash
201
+ # List matching documents.
202
+ dclq grep -i 'human annotation' documents/*.dclx -l
203
+
204
+ # Count matching semantic units.
205
+ dclq grep -i 'inference|runtime' documents/*.dclx -c
206
+
207
+ # Emit bounded records for an agent or data pipeline.
208
+ dclq grep -i 'accuracy|performance' documents/*.dclx \
209
+ --page 1-4 \
210
+ --type text,table_cell \
211
+ --limit 10 \
212
+ --format jsonl
213
+
214
+ # Check for a match without output.
215
+ if dclq grep -q -F 'CONFIDENTIAL' document.dclx; then
216
+ echo "classified"
217
+ fi
218
+ ```
219
+
220
+ ## Commands
221
+
222
+ | Command | Description |
223
+ | --- | --- |
224
+ | `dclq grep PATTERN INPUT...` | Search semantic document units |
225
+ | `dclq list INPUT...` | Enumerate semantic document units |
226
+ | `dclq inspect INPUT...` | Print a structural inventory |
227
+ | `dclq outline INPUT` | Print the heading hierarchy with XPaths |
228
+ | `dclq show INPUT XPATH` | Retrieve semantic content at an XPath |
229
+ | `dclq select INPUT XPATH` | Evaluate XPath against the source XML |
230
+
231
+ ## Query options
232
+
233
+ | Option | Description |
234
+ | --- | --- |
235
+ | `-e PATTERN` | Add a search pattern; repeatable |
236
+ | `-f FILE` | Read patterns from a file |
237
+ | `-F` | Match fixed strings |
238
+ | `-i` | Ignore case |
239
+ | `-w` | Match whole words |
240
+ | `-A N`, `-B N`, `-C N` | Include semantic context |
241
+ | `--context-scope SCOPE` | Use `auto`, `container`, `section`, or `document` context |
242
+ | `--type TYPE` | Filter semantic unit types |
243
+ | `--layer LAYER` | Filter body, furniture, or background content |
244
+ | `--page LIST` | Filter pages and ranges such as `2-4,7` |
245
+ | `--within-xpath XPATH` | Restrict the query to an XPath selection |
246
+ | `--section` | Expand a selected heading to its section |
247
+ | `--limit N` | Limit the number of results |
248
+ | `-n`, `--with-xpath` | Prefix text output with XPath addresses |
249
+ | `--format FORMAT` | Emit `text`, `json`, or `jsonl` |
250
+ | `-c`, `-l`, `-q` | Count, list matching files, or run quietly |
251
+
252
+ Run `dclq COMMAND --help` for the complete option set.
253
+
254
+ XPath input may omit the namespace and document root: `/formula[1]`,
255
+ `/doclang/formula[1]`, and `/d:doclang/d:formula[1]` are equivalent.
256
+
257
+ ## Exit codes
258
+
259
+ | Code | Meaning |
260
+ | --- | --- |
261
+ | `0` | At least one result |
262
+ | `1` | No results |
263
+ | `2` | Input, query, or usage error |
264
+
265
+ ## Development
266
+
267
+ `dclq` lives in the [docling-core](https://github.com/docling-project/docling-core)
268
+ repository as a workspace member under `packages/dclq`, and is released in
269
+ lockstep with `docling-core` (same version, exact dependency pin). Work on it
270
+ from the repository root:
271
+
272
+ ```bash
273
+ uv sync --all-extras --all-packages
274
+ uv run pytest packages/dclq/tests
275
+ uv run pre-commit run --all-files
276
+ ```
277
+
278
+ ## License
279
+
280
+ `dclq` is available under the [MIT License](LICENSE).
dclq-2.89.0/README.md ADDED
@@ -0,0 +1,250 @@
1
+ # dclq
2
+
3
+ > [!WARNING]
4
+ > **Experimental:** `dclq` is experimental. Its commands, options, output
5
+ > formats, exit codes, and functionality may change in breaking ways without
6
+ > prior warning.
7
+
8
+ <p align="center">
9
+ <strong>Query structured documents.</strong><br>
10
+ Grep, list, outline, and XPath over headings, sections, lists, and
11
+ tables—and get an XPath back for every result.
12
+ </p>
13
+
14
+ ## What is dclq?
15
+
16
+ `dclq` brings the familiar grep workflow to
17
+ [DocLang](https://doclang.ai) documents. It queries semantic document units
18
+ and returns bounded evidence with reusable XPath addresses.
19
+
20
+ ```console
21
+ $ dclq grep 'GPU|CPU' paper.dclg \
22
+ --within-xpath '/heading[13]' --section -n
23
+ /list[4]/ldiv[1]:- AWS EC2 VM ... Nvidia L4 GPU ...
24
+ /text[42]:All experiments ... GPU acceleration ... x86 CPU ...
25
+ ```
26
+
27
+ ## Features
28
+
29
+ - 🔎 **Semantic search** across headings, paragraphs, captions, footnotes,
30
+ list items, table cells, formulas, code, and metadata
31
+ - 🧭 **Structural context** with section-aware neighbours, list siblings, table
32
+ headers, captions, and document reading order
33
+ - 🔗 **Reusable XPath addresses** for every result
34
+ - 🎯 **Precise filters** for sections, XPath regions, pages, layers, and
35
+ semantic types
36
+ - 📑 **Document navigation** with structural inventory, heading outlines,
37
+ semantic retrieval, and raw XPath selection
38
+ - 📦 **DocLang input** from `.dclg`, `.dclg.xml`, `.xml`, `.dclx`, or standard
39
+ input
40
+ - 🤖 **Pipeline-friendly output** in text, JSON, and JSONL
41
+ - ⚡ **grep-compatible behavior** with regular expressions, fixed strings,
42
+ context flags, counts, file listing, quiet mode, and exit codes
43
+ - 🔒 **Local, deterministic, read-only execution** with bounded output
44
+
45
+ ## Quickstart
46
+
47
+ ### 1. Install
48
+
49
+ ```bash
50
+ python -m pip install dclq
51
+ ```
52
+
53
+ ### 2. Convert source documents to DocLang
54
+
55
+ ```bash
56
+ python -m pip install docling
57
+ docling report.pdf handbook.docx --to dclx --output converted
58
+ ```
59
+
60
+ ### 3. Search
61
+
62
+ ```bash
63
+ dclq grep -i 'termination|cancellation' converted/report.dclx
64
+ ```
65
+
66
+ Without a pattern, `dclq list` enumerates units instead:
67
+
68
+ ```bash
69
+ dclq list converted/report.dclx --type table_cell --page 3
70
+ ```
71
+
72
+ ## Examples
73
+
74
+ ### Inspect a document
75
+
76
+ ```console
77
+ $ dclq inspect paper.dclx
78
+ paper.dclx
79
+ Type: dclx
80
+ Pages: 9
81
+ Semantic units: 612
82
+ Elements: caption=9, code=3, formula=4, heading=18, list=5, picture=6, table=5, text=434
83
+ Metadata: author=2, date=1, keywords=1
84
+ ```
85
+
86
+ ### Navigate the heading hierarchy
87
+
88
+ ```console
89
+ $ dclq outline paper.dclg
90
+ Docling: An Efficient Open-Source Toolkit for AI-driven Document Conversion /heading[1]
91
+ Abstract /heading[2]
92
+ 1 Introduction /heading[3]
93
+ ...
94
+ 3 Design and Architecture /heading[5]
95
+ 5 Performance /heading[11]
96
+ 5.2 System Configurations /heading[13]
97
+ ...
98
+ 6 Applications /heading[16]
99
+ ...
100
+ References /heading[19]
101
+ ```
102
+
103
+ ### Retrieve a section by XPath
104
+
105
+ ```console
106
+ $ dclq show paper.dclg '/heading[13]' --section --max-chars 220 -n
107
+ /heading[13]:5.2 System Configurations
108
+ /text[41]:We schedule our benchmark experiments each on two different systems...
109
+ /list[4]/ldiv[1]:- AWS EC2 VM (g6.xlarge)...
110
+ /list[4]/ldiv[2]:- MacBook Pro M3 Max (ARM)...
111
+ /text[42]:All experiments on the AWS EC2 VM...
112
+ /table[1]/ched[1]:Asset
113
+ /table[1]/ched[2]:Version
114
+ ...
115
+ ```
116
+
117
+ Each section element keeps its own reusable XPath.
118
+
119
+ ### Query the source XML
120
+
121
+ JSON includes document identity alongside scalar results:
122
+
123
+ ```console
124
+ $ dclq select paper.dclg 'count(//page_break) + 1' --format json
125
+ {
126
+ "document": "paper.dclg",
127
+ "sha256": "284b9b63bf3e11a75ffd2ad23c7505a9b5e75407531a13044ceae001e0d1550e",
128
+ "value": 8.0
129
+ }
130
+
131
+ $ dclq select paper.dclg \
132
+ 'normalize-space(string(//table[1]/caption))'
133
+ Table 1: Versions and configuration options considered for each tested asset. * denotes the default setting.
134
+ ```
135
+
136
+ ### Search a table cell with its structural context
137
+
138
+ The direct JSON record includes document identity, match offsets, and
139
+ contributing document items; the relevant fields are shown here:
140
+
141
+ ```console
142
+ $ dclq grep -F '2.73 5.39' paper.dclx --format json
143
+ [
144
+ {
145
+ ...
146
+ "xpaths": ["/d:doclang/d:table[1]/d:fcel[8]"],
147
+ "logical_type": "table_cell",
148
+ "text": "2.73 5.39",
149
+ "pages": [1],
150
+ "cell_context": {
151
+ "column_headers": ["Inference time (secs)"],
152
+ "caption": "Table 1. HPO performed in OTSL and HTML representation on the same transformer-based TableFormer..."
153
+ }
154
+ }
155
+ ]
156
+ ```
157
+
158
+ ### Get list-aware context
159
+
160
+ ```console
161
+ $ dclq grep -F 'Third item with numId 2' handbook.dclx \
162
+ -C 1 --context-scope auto -n
163
+ /list[7]/ldiv[2]-2. Second item with numId 2
164
+ /list[7]/ldiv[3]:3. Third item with numId 2
165
+ /list[7]/ldiv[4]-4. Fourth item with numId 2
166
+ ```
167
+
168
+ ### Use dclq in shell pipelines
169
+
170
+ ```bash
171
+ # List matching documents.
172
+ dclq grep -i 'human annotation' documents/*.dclx -l
173
+
174
+ # Count matching semantic units.
175
+ dclq grep -i 'inference|runtime' documents/*.dclx -c
176
+
177
+ # Emit bounded records for an agent or data pipeline.
178
+ dclq grep -i 'accuracy|performance' documents/*.dclx \
179
+ --page 1-4 \
180
+ --type text,table_cell \
181
+ --limit 10 \
182
+ --format jsonl
183
+
184
+ # Check for a match without output.
185
+ if dclq grep -q -F 'CONFIDENTIAL' document.dclx; then
186
+ echo "classified"
187
+ fi
188
+ ```
189
+
190
+ ## Commands
191
+
192
+ | Command | Description |
193
+ | --- | --- |
194
+ | `dclq grep PATTERN INPUT...` | Search semantic document units |
195
+ | `dclq list INPUT...` | Enumerate semantic document units |
196
+ | `dclq inspect INPUT...` | Print a structural inventory |
197
+ | `dclq outline INPUT` | Print the heading hierarchy with XPaths |
198
+ | `dclq show INPUT XPATH` | Retrieve semantic content at an XPath |
199
+ | `dclq select INPUT XPATH` | Evaluate XPath against the source XML |
200
+
201
+ ## Query options
202
+
203
+ | Option | Description |
204
+ | --- | --- |
205
+ | `-e PATTERN` | Add a search pattern; repeatable |
206
+ | `-f FILE` | Read patterns from a file |
207
+ | `-F` | Match fixed strings |
208
+ | `-i` | Ignore case |
209
+ | `-w` | Match whole words |
210
+ | `-A N`, `-B N`, `-C N` | Include semantic context |
211
+ | `--context-scope SCOPE` | Use `auto`, `container`, `section`, or `document` context |
212
+ | `--type TYPE` | Filter semantic unit types |
213
+ | `--layer LAYER` | Filter body, furniture, or background content |
214
+ | `--page LIST` | Filter pages and ranges such as `2-4,7` |
215
+ | `--within-xpath XPATH` | Restrict the query to an XPath selection |
216
+ | `--section` | Expand a selected heading to its section |
217
+ | `--limit N` | Limit the number of results |
218
+ | `-n`, `--with-xpath` | Prefix text output with XPath addresses |
219
+ | `--format FORMAT` | Emit `text`, `json`, or `jsonl` |
220
+ | `-c`, `-l`, `-q` | Count, list matching files, or run quietly |
221
+
222
+ Run `dclq COMMAND --help` for the complete option set.
223
+
224
+ XPath input may omit the namespace and document root: `/formula[1]`,
225
+ `/doclang/formula[1]`, and `/d:doclang/d:formula[1]` are equivalent.
226
+
227
+ ## Exit codes
228
+
229
+ | Code | Meaning |
230
+ | --- | --- |
231
+ | `0` | At least one result |
232
+ | `1` | No results |
233
+ | `2` | Input, query, or usage error |
234
+
235
+ ## Development
236
+
237
+ `dclq` lives in the [docling-core](https://github.com/docling-project/docling-core)
238
+ repository as a workspace member under `packages/dclq`, and is released in
239
+ lockstep with `docling-core` (same version, exact dependency pin). Work on it
240
+ from the repository root:
241
+
242
+ ```bash
243
+ uv sync --all-extras --all-packages
244
+ uv run pytest packages/dclq/tests
245
+ uv run pre-commit run --all-files
246
+ ```
247
+
248
+ ## License
249
+
250
+ `dclq` is available under the [MIT License](LICENSE).
dclq-2.89.0/dclq/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """dclq."""
2
+
3
+ from importlib.metadata import version
4
+
5
+ __version__ = version("dclq")
dclq-2.89.0/dclq/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Run dclq as a module."""
2
+
3
+ from dclq.cli import main
4
+
5
+ raise SystemExit(main())