lupaxa-regexlab 0.1.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 (30) hide show
  1. lupaxa_regexlab-0.1.0/.gitignore +24 -0
  2. lupaxa_regexlab-0.1.0/LICENCE +21 -0
  3. lupaxa_regexlab-0.1.0/PKG-INFO +376 -0
  4. lupaxa_regexlab-0.1.0/README.md +313 -0
  5. lupaxa_regexlab-0.1.0/docs/README.md +23 -0
  6. lupaxa_regexlab-0.1.0/pyproject.toml +104 -0
  7. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/__init__.py +14 -0
  8. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/__main__.py +8 -0
  9. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/analyse.py +386 -0
  10. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/benchmark.py +147 -0
  11. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/cli.py +1109 -0
  12. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/colour.py +57 -0
  13. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/compare.py +153 -0
  14. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/config.py +297 -0
  15. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/engines.py +423 -0
  16. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/errors.py +92 -0
  17. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/explain.py +255 -0
  18. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/export.py +227 -0
  19. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/flagset.py +217 -0
  20. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/generate.py +231 -0
  21. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/inputs.py +112 -0
  22. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/interactive.py +283 -0
  23. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/isolate.py +174 -0
  24. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/library.py +132 -0
  25. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/matching.py +97 -0
  26. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/ops.py +253 -0
  27. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/parser.py +1352 -0
  28. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/suite.py +363 -0
  29. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/version.py +10 -0
  30. lupaxa_regexlab-0.1.0/src/lupaxa/regexlab/visualise.py +106 -0
@@ -0,0 +1,24 @@
1
+ # OS
2
+ .DS_Store
3
+
4
+ # Cursor
5
+ .cursor/
6
+ .superpowers/
7
+ .worktrees/
8
+ cursor-docs
9
+
10
+ # Make
11
+ .makefiles/
12
+
13
+ # MkDocs
14
+ site/
15
+
16
+ # Python
17
+ .venv/
18
+ __pycache__/
19
+ .mypy_cache/
20
+ .ruff_cache/
21
+ .pytest_cache/
22
+ dist/
23
+ build/
24
+ *.egg-info/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) The Lupaxa 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.
@@ -0,0 +1,376 @@
1
+ Metadata-Version: 2.5
2
+ Name: lupaxa-regexlab
3
+ Version: 0.1.0
4
+ Summary: Explain, test, generate, compare, and debug regular expressions from the command line.
5
+ Project-URL: Homepage, https://github.com/lupaxa-developers-toolbox/regexlab
6
+ Project-URL: Documentation, https://github.com/lupaxa-developers-toolbox/regexlab
7
+ Project-URL: Repository, https://github.com/lupaxa-developers-toolbox/regexlab
8
+ Project-URL: Issues, https://github.com/lupaxa-developers-toolbox/regexlab/issues
9
+ Author: The Lupaxa Project
10
+ License: MIT License
11
+
12
+ Copyright (c) The Lupaxa Project
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+ License-File: LICENCE
32
+ Keywords: cli,regex,regular-expressions,testing,textual
33
+ Classifier: Development Status :: 3 - Alpha
34
+ Classifier: Environment :: Console
35
+ Classifier: Intended Audience :: Developers
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Operating System :: OS Independent
38
+ Classifier: Programming Language :: Python :: 3
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Programming Language :: Python :: 3.13
42
+ Classifier: Programming Language :: Python :: 3.14
43
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
44
+ Classifier: Topic :: Utilities
45
+ Requires-Python: >=3.11
46
+ Requires-Dist: rich>=13.0
47
+ Requires-Dist: textual>=0.80
48
+ Provides-Extra: dev
49
+ Requires-Dist: bump-my-version>=1.2.0; extra == 'dev'
50
+ Requires-Dist: hatch>=1.12.0; extra == 'dev'
51
+ Requires-Dist: mypy>=1.12.0; extra == 'dev'
52
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
53
+ Requires-Dist: pytest>=8.0; extra == 'dev'
54
+ Requires-Dist: ruff>=0.6.0; extra == 'dev'
55
+ Provides-Extra: pcre2
56
+ Requires-Dist: python-pcre2>=0.4; extra == 'pcre2'
57
+ Provides-Extra: regex
58
+ Requires-Dist: regex>=2024.0; extra == 'regex'
59
+ Provides-Extra: test
60
+ Requires-Dist: pytest-cov>=5.0; extra == 'test'
61
+ Requires-Dist: pytest>=8.0; extra == 'test'
62
+ Description-Content-Type: text/markdown
63
+
64
+ <p align="center">
65
+ <a href="https://github.com/lupaxa-developers-toolbox">
66
+ <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/developers-toolbox/readme-logo.png" alt="Developers Toolbox" />
67
+ </a>
68
+ </p>
69
+
70
+ <h1 align="center">Regexlab</h1>
71
+
72
+ Regex Lab is an offline workbench for regular expressions. It explains a
73
+ pattern from a syntax tree, runs it, generates examples, and compares
74
+ samples. It does not claim that two patterns are equivalent.
75
+
76
+ The PyPI name is `lupaxa-regexlab`. The import path is `lupaxa.regexlab`.
77
+ The console scripts are `regex-lab` and `regexlab`. Examples below use
78
+ `regex-lab`. `lupaxa` is a namespace package.
79
+
80
+ ## Install
81
+
82
+ ```bash
83
+ pip install lupaxa-regexlab
84
+ ```
85
+
86
+ Requires Python 3.11+.
87
+
88
+ > **Note:** `python-regex` and `pcre2` are optional. If they are not
89
+ > installed, `regex-lab engines` says so. Regex Lab will not switch to
90
+ > another engine.
91
+ >
92
+ > **Note:** `NO_COLOR`, including an empty value, turns colour off.
93
+ > `--no-colour` does the same. Matches are then marked with `« »`.
94
+
95
+ With no arguments, a terminal opens the interactive workbench. A pipe
96
+ prints help and exits 2.
97
+
98
+ ## What it Does
99
+
100
+ `regex-lab` parses the pattern before it runs it. Explain, lint, and the
101
+ diagrams read that tree. Matching, replacement, splitting, generation,
102
+ comparison, and benchmarks run in a worker process that can be killed on
103
+ timeout.
104
+
105
+ ```bash
106
+ regex-lab explain '^(?P<name>[a-z]+)-(?P<id>\d+)$'
107
+ regex-lab parse '^(?P<name>[a-z]+)-(?P<id>\d+)$'
108
+ regex-lab test '^(?P<name>[a-z]+)-(?P<id>\d+)$' 'ab-12'
109
+ regex-lab generate '[ab]{2}' --count 3 --seed 1 --min-length 2 --max-length 2
110
+ regex-lab compare 'a+' 'b+' aaa bbb --fail-on-difference
111
+ regex-lab --version
112
+ ```
113
+
114
+ `regexlab` accepts the same commands: `explain`, `parse`, `test`,
115
+ `interactive`, `matches`, `findall`, `replace`, `split`, `generate`,
116
+ `compare`, `analyse`, `lint`, `benchmark`, `visualise`, `escape`,
117
+ `suite`, `library`, `export`, `engines`, `flags`, `config`, and
118
+ `version`.
119
+
120
+ ## Explain
121
+
122
+ ```bash
123
+ regex-lab explain '^(?P<name>[a-z]+)-(?P<id>\d+)$'
124
+ ```
125
+
126
+ ```text
127
+ Start of the string.
128
+ Capture "name" as one or more lowercase letters.
129
+ A hyphen "-".
130
+ Capture "id" as one or more decimal digits.
131
+ End of the string.
132
+ ```
133
+
134
+ `--detail summary` is one paragraph. `--detail technical` adds the engine,
135
+ flags, and offsets. `--flags a` describes `\d` as an ASCII digit.
136
+ `--flags m` describes `^` as the start of a line.
137
+
138
+ ## Parse
139
+
140
+ Parse prints the tree and does not run the pattern.
141
+
142
+ ```bash
143
+ regex-lab parse '^(?P<name>[a-z]+)-(?P<id>\d+)$'
144
+ ```
145
+
146
+ ```text
147
+ Expression
148
+ ├── Start anchor
149
+ ├── Named group: name
150
+ │ └── Character class: a-z
151
+ │ └── Repeat: one or more
152
+ ├── Literal: -
153
+ ├── Named group: id
154
+ │ └── Digit
155
+ │ └── Repeat: one or more
156
+ └── End anchor
157
+ ```
158
+
159
+ An invalid pattern names the position and a fragment.
160
+
161
+ ```bash
162
+ regex-lab parse '('
163
+ ```
164
+
165
+ ```text
166
+ error: Unclosed group. Expected ')'.
167
+ position: 0
168
+ fragment: (
169
+ ```
170
+
171
+ That command exits 3.
172
+
173
+ ## Test
174
+
175
+ The default mode is `fullmatch`. `matches` and `findall` default to
176
+ `finditer` unless you set `--mode`.
177
+
178
+ ```bash
179
+ regex-lab test '^(?P<name>[a-z]+)-(?P<id>\d+)$' 'ab-12'
180
+ ```
181
+
182
+ ```text
183
+ subject: arg1
184
+ engine: python-re
185
+ flags: (none)
186
+ mode: fullmatch
187
+ matches: 1
188
+ highlighted: «ab-12»
189
+ match 1
190
+ text: ab-12
191
+ span: 0-5
192
+ line: 1
193
+ column: 1
194
+ groups: ab, 12
195
+ named: name=ab, id=12
196
+ pass
197
+ ```
198
+
199
+ A miss exits 1.
200
+
201
+ ```bash
202
+ regex-lab test '^[a-z]+$' 'AB'
203
+ ```
204
+
205
+ ```text
206
+ subject: arg1
207
+ engine: python-re
208
+ flags: (none)
209
+ mode: fullmatch
210
+ matches: 0
211
+ no match
212
+ fail: arg1
213
+ ```
214
+
215
+ `replace` previews on stdout. It writes a file only with `--output`, or
216
+ with `--in-place --yes`. On `python-re`, write replacements as `\1` or
217
+ `\g<name>`. An unescaped `$1` is rejected.
218
+
219
+ ## Generate and Compare
220
+
221
+ Generation checks every positive sample with the engine and mode. With
222
+ `--include-invalid`, each negative sample is checked the other way and
223
+ labelled.
224
+
225
+ ```bash
226
+ regex-lab generate '[ab]{2}' --count 3 --seed 1 --min-length 2 --max-length 2 --include-invalid
227
+ ```
228
+
229
+ ```text
230
+ positive: aa
231
+ positive: ba
232
+ positive: bb
233
+ negative: wrong-character: Za
234
+ negative: truncated: a
235
+ negative: extra-character: aa!
236
+ negative: case-flip: Aa
237
+ ```
238
+
239
+ The same `--seed` repeats the same samples. Backreferences, recursion,
240
+ conditionals, and lookaround are reported instead of skipped.
241
+
242
+ ```bash
243
+ regex-lab compare 'a+' 'b+' aaa bbb --fail-on-difference
244
+ ```
245
+
246
+ ```text
247
+ both: 0
248
+ neither: 0
249
+ only first: 1
250
+ only second: 1
251
+ capture diffs: 0
252
+ span diffs: 0
253
+ replacement diffs: 0
254
+ Sample comparison only. This does not prove the patterns are equivalent.
255
+ ```
256
+
257
+ That command exits 9 because `--fail-on-difference` was set.
258
+
259
+ ## Engines
260
+
261
+ ```bash
262
+ regex-lab engines
263
+ ```
264
+
265
+ ```text
266
+ Available
267
+ python-re
268
+ Not installed
269
+ python-regex
270
+ pip install 'lupaxa-regexlab[regex]'
271
+ pcre2
272
+ pip install 'lupaxa-regexlab[pcre2]'
273
+ ```
274
+
275
+ `python-re` is always available. The other two appear under Available
276
+ when their packages import.
277
+
278
+ ```bash
279
+ regex-lab explain a --engine python-regex
280
+ ```
281
+
282
+ ```text
283
+ error: engine python-regex is not installed. pip install 'lupaxa-regexlab[regex]'. Regex Lab will not substitute another engine.
284
+ ```
285
+
286
+ That command exits 7 when the `regex` package is absent.
287
+
288
+ ## Flags
289
+
290
+ | Flag | Default | Meaning |
291
+ | ------------- | ----------- | --------------------------------------------------------- |
292
+ | `--engine` | `python-re` | Engine name. A missing engine is an error. |
293
+ | `--flags` | (none) | Letters such as `im`, or names such as `IGNORECASE`. |
294
+ | `--mode` | `fullmatch` | `search`, `match`, `fullmatch`, `finditer`, or `findall`. |
295
+ | `--json` | off | UTF-8 object with schema `1.0` and no colour codes. |
296
+ | `--no-colour` | off | Disable colour. A set `NO_COLOR` does the same. |
297
+ | `--timeout` | `1` | Seconds before a match worker is stopped. |
298
+ | `--strict` | off | Unknown config keys fail. Lint warnings exit 10. |
299
+ | `--seed` | `0` | Seed for generation and comparison. |
300
+ | `--config` | user file | Extra TOML file. Command-line options win. |
301
+
302
+ `regex-lab flags` lists every letter. `regex-lab config` prints the
303
+ effective settings. Precedence is the command line, then `--config`, then
304
+ the user file, then the defaults.
305
+
306
+ ```bash
307
+ regex-lab explain a --json
308
+ ```
309
+
310
+ ```json
311
+ {
312
+ "schema_version": "1.0",
313
+ "ok": true,
314
+ "command": "explain",
315
+ "engine": "python-re",
316
+ "pattern": "a",
317
+ "flags": "",
318
+ "mode": "fullmatch",
319
+ "error": null,
320
+ "warnings": [],
321
+ "explanation": "The literal 'a'.",
322
+ "detail": "detailed"
323
+ }
324
+ ```
325
+
326
+ ## Regex Policy
327
+
328
+ Patterns are read as text. Suite files and config files are TOML, parsed
329
+ with `tomllib`, and never executed.
330
+
331
+ `python-re` is the default. Possessive quantifiers and atomic groups are
332
+ accepted there on Python 3.11 and newer. Property escapes, recursion, and
333
+ pattern-position `\g<name>` are rejected for that engine. Lookahead,
334
+ lookbehind, conditionals, and backreferences parse, and generation says
335
+ when it cannot expand them.
336
+
337
+ Replacement text follows the selected engine. Splits report segments and
338
+ separators. Escape uses that engine's escape function.
339
+
340
+ Lint reports findings and does not rewrite the pattern. `--strict` turns
341
+ a warning into exit 10. Analysis heuristics are labelled `heuristic`.
342
+
343
+ Benchmarks run in a separate process. A timeout is not mixed into the
344
+ average, and a hung worker is killed.
345
+
346
+ HTML and SVG diagrams escape the pattern. They do not load remote assets.
347
+
348
+ ## Exit Codes
349
+
350
+ | Code | Result |
351
+ | ---- | -------------------------------------------------------------- |
352
+ | `0` | Success, or a test and suite that passed. |
353
+ | `1` | General failure, including a subject that missed `--expect`. |
354
+ | `2` | Bad arguments, unknown config keys, or no TTY for interactive. |
355
+ | `3` | The pattern is not valid on the selected engine. |
356
+ | `4` | A suite assertion failed. |
357
+ | `5` | The match exceeded `--timeout`. The worker is killed. |
358
+ | `6` | An input or match limit was exceeded. |
359
+ | `7` | Missing engine, or a construct that engine does not support. |
360
+ | `8` | Generation or comparison did not finish the requested sample. |
361
+ | `9` | Patterns differed and `--fail-on-difference` was set. |
362
+ | `10` | Lint found a warning or error under `--strict`. |
363
+
364
+ ```bash
365
+ regex-lab version
366
+ ```
367
+
368
+ ```text
369
+ regex-lab 0.0.0
370
+ ```
371
+
372
+ `regex-lab --version` prints the same line.
373
+
374
+ <a href="https://github.com/the-lupaxa-project">
375
+ <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
376
+ </a>