tocs 1.0.7__tar.gz → 1.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.
- {tocs-1.0.7 → tocs-1.0.8}/PKG-INFO +9 -1
- {tocs-1.0.7 → tocs-1.0.8}/README.md +8 -0
- {tocs-1.0.7 → tocs-1.0.8}/pyproject.toml +1 -1
- {tocs-1.0.7 → tocs-1.0.8}/tests/test_toc.py +68 -0
- {tocs-1.0.7 → tocs-1.0.8}/tocs/main.py +28 -7
- {tocs-1.0.7 → tocs-1.0.8}/tocs.egg-info/PKG-INFO +9 -1
- {tocs-1.0.7 → tocs-1.0.8}/LICENSE +0 -0
- {tocs-1.0.7 → tocs-1.0.8}/setup.cfg +0 -0
- {tocs-1.0.7 → tocs-1.0.8}/tocs/__init__.py +0 -0
- {tocs-1.0.7 → tocs-1.0.8}/tocs.egg-info/SOURCES.txt +0 -0
- {tocs-1.0.7 → tocs-1.0.8}/tocs.egg-info/dependency_links.txt +0 -0
- {tocs-1.0.7 → tocs-1.0.8}/tocs.egg-info/entry_points.txt +0 -0
- {tocs-1.0.7 → tocs-1.0.8}/tocs.egg-info/requires.txt +0 -0
- {tocs-1.0.7 → tocs-1.0.8}/tocs.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tocs
|
|
3
|
-
Version: 1.0.
|
|
3
|
+
Version: 1.0.8
|
|
4
4
|
Summary: Generate TOC for markdown files
|
|
5
5
|
Author-email: Andrea Bondanini <bondaniniandrea@gmail.com>
|
|
6
6
|
License: MIT
|
|
@@ -38,10 +38,18 @@ pip install --upgrade tocs
|
|
|
38
38
|
### Basic usage:
|
|
39
39
|
- `tocs input_file.md` - Generate TOC for the file
|
|
40
40
|
- `tocs --depth 2 input_file.md` - Limit the TOC generation to headers up to a specified depth
|
|
41
|
+
- `tocs --clear-depth input_file.md` - Remove a previously locked depth and generate a TOC with no depth limit
|
|
41
42
|
- `tocs --dry-run input_file.md` - Preview TOC without modifying the file
|
|
42
43
|
- `tocs --help` - Show usage instructions
|
|
43
44
|
- `tocs --version` - Display version information
|
|
44
45
|
|
|
46
|
+
### Depth lock
|
|
47
|
+
The first time you run `tocs` with `--depth N`, that value is written as a
|
|
48
|
+
`<!-- depth=N -->` marker inside the TOC block. On later runs, if you don't
|
|
49
|
+
pass `--depth` again, tocs reads that marker and reuses the same depth, so
|
|
50
|
+
you don't have to keep repeating the flag. Passing a new `--depth` overwrites
|
|
51
|
+
the lock, and `--clear-depth` removes it, going back to an unlimited TOC.
|
|
52
|
+
|
|
45
53
|
### tocs example
|
|
46
54
|
Given the following markdown file **input_file.md**:
|
|
47
55
|
```md
|
|
@@ -20,10 +20,18 @@ pip install --upgrade tocs
|
|
|
20
20
|
### Basic usage:
|
|
21
21
|
- `tocs input_file.md` - Generate TOC for the file
|
|
22
22
|
- `tocs --depth 2 input_file.md` - Limit the TOC generation to headers up to a specified depth
|
|
23
|
+
- `tocs --clear-depth input_file.md` - Remove a previously locked depth and generate a TOC with no depth limit
|
|
23
24
|
- `tocs --dry-run input_file.md` - Preview TOC without modifying the file
|
|
24
25
|
- `tocs --help` - Show usage instructions
|
|
25
26
|
- `tocs --version` - Display version information
|
|
26
27
|
|
|
28
|
+
### Depth lock
|
|
29
|
+
The first time you run `tocs` with `--depth N`, that value is written as a
|
|
30
|
+
`<!-- depth=N -->` marker inside the TOC block. On later runs, if you don't
|
|
31
|
+
pass `--depth` again, tocs reads that marker and reuses the same depth, so
|
|
32
|
+
you don't have to keep repeating the flag. Passing a new `--depth` overwrites
|
|
33
|
+
the lock, and `--clear-depth` removes it, going back to an unlimited TOC.
|
|
34
|
+
|
|
27
35
|
### tocs example
|
|
28
36
|
Given the following markdown file **input_file.md**:
|
|
29
37
|
```md
|
|
@@ -3,7 +3,7 @@ name = "tocs"
|
|
|
3
3
|
description = "Generate TOC for markdown files"
|
|
4
4
|
authors = [{ name = "Andrea Bondanini", email = "bondaniniandrea@gmail.com" }]
|
|
5
5
|
license = { text = "MIT" }
|
|
6
|
-
version = "1.0.
|
|
6
|
+
version = "1.0.8"
|
|
7
7
|
requires-python = ">=3.11.9"
|
|
8
8
|
readme = "README.md"
|
|
9
9
|
keywords = ["markdown", "tocs", "cli", "documentation", "generator"]
|
|
@@ -167,6 +167,74 @@ def test_create_toc_remove_special_chars():
|
|
|
167
167
|
assert result == "- [Hello!?.:;'\"()[]{}@#$%^&*+=<>/\\|`~World](#helloworld)"
|
|
168
168
|
|
|
169
169
|
|
|
170
|
+
def test_depth_lock_persists_across_runs():
|
|
171
|
+
with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
|
|
172
|
+
shutil.copy("tests/fixtures/lorem_ipsum_depth_2_input.md", tmp.name)
|
|
173
|
+
|
|
174
|
+
first = subprocess.run(
|
|
175
|
+
["python3", "tocs/main.py", tmp.name, "--depth", "2"],
|
|
176
|
+
capture_output=True,
|
|
177
|
+
text=True,
|
|
178
|
+
)
|
|
179
|
+
assert first.returncode == 0
|
|
180
|
+
|
|
181
|
+
second = subprocess.run(
|
|
182
|
+
["python3", "tocs/main.py", tmp.name], capture_output=True, text=True
|
|
183
|
+
)
|
|
184
|
+
assert second.returncode == 0
|
|
185
|
+
|
|
186
|
+
with open(tmp.name) as f:
|
|
187
|
+
actual = f.read()
|
|
188
|
+
|
|
189
|
+
with open("tests/fixtures/lorem_ipsum_depth_2_output.md") as f:
|
|
190
|
+
expected = f.read()
|
|
191
|
+
|
|
192
|
+
assert actual == expected
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def test_clear_depth_removes_lock():
|
|
196
|
+
with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
|
|
197
|
+
shutil.copy("tests/fixtures/lorem_ipsum_depth_2_input.md", tmp.name)
|
|
198
|
+
|
|
199
|
+
first = subprocess.run(
|
|
200
|
+
["python3", "tocs/main.py", tmp.name, "--depth", "2"],
|
|
201
|
+
capture_output=True,
|
|
202
|
+
text=True,
|
|
203
|
+
)
|
|
204
|
+
assert first.returncode == 0
|
|
205
|
+
|
|
206
|
+
second = subprocess.run(
|
|
207
|
+
["python3", "tocs/main.py", tmp.name, "--clear-depth"],
|
|
208
|
+
capture_output=True,
|
|
209
|
+
text=True,
|
|
210
|
+
)
|
|
211
|
+
assert second.returncode == 0
|
|
212
|
+
|
|
213
|
+
with open(tmp.name) as f:
|
|
214
|
+
actual = f.read()
|
|
215
|
+
|
|
216
|
+
with open("tests/fixtures/lorem_ipsum_depth_2_cleared_output.md") as f:
|
|
217
|
+
expected = f.read()
|
|
218
|
+
|
|
219
|
+
assert actual == expected
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def test_init_tocs_as_last_line_returns_standard_error():
|
|
223
|
+
with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
|
|
224
|
+
tmp.write("<!-- init-tocs -->")
|
|
225
|
+
tmp.flush()
|
|
226
|
+
|
|
227
|
+
result = subprocess.run(
|
|
228
|
+
["python3", "tocs/main.py", tmp.name], capture_output=True, text=True
|
|
229
|
+
)
|
|
230
|
+
|
|
231
|
+
assert result.returncode == 1
|
|
232
|
+
assert (
|
|
233
|
+
result.stderr
|
|
234
|
+
== "Error: Missing or invalid TOC markers. Add '<!-- init-tocs -->' and '<!-- end-tocs -->' to your file.\n"
|
|
235
|
+
)
|
|
236
|
+
|
|
237
|
+
|
|
170
238
|
def test_dry_run():
|
|
171
239
|
with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
|
|
172
240
|
shutil.copy("tests/fixtures/lorem_ipsum_input.md", tmp.name)
|
|
@@ -6,7 +6,9 @@ import sys
|
|
|
6
6
|
INDENT_LEVEL = " "
|
|
7
7
|
|
|
8
8
|
|
|
9
|
-
def create_toc_row(
|
|
9
|
+
def create_toc_row(
|
|
10
|
+
line: str, anchor_occurrences: dict[str, int], max_depth: int | None = None
|
|
11
|
+
):
|
|
10
12
|
hashes = 0
|
|
11
13
|
j = 0
|
|
12
14
|
|
|
@@ -50,12 +52,12 @@ def toggle_ignore_rows_flag(ignore_rows, line):
|
|
|
50
52
|
return ignore_rows
|
|
51
53
|
|
|
52
54
|
|
|
53
|
-
def generate_toc(original_lines, max_depth):
|
|
55
|
+
def generate_toc(original_lines: list[str], max_depth: int | None, clear_depth: bool):
|
|
54
56
|
tocs = []
|
|
55
57
|
init_toc_position = -1
|
|
56
58
|
end_toc_position = -1
|
|
57
59
|
ignore_rows = False
|
|
58
|
-
anchor_occurrences = {}
|
|
60
|
+
anchor_occurrences: dict[str, int] = {}
|
|
59
61
|
|
|
60
62
|
for i, line in enumerate(original_lines):
|
|
61
63
|
ignore_rows = toggle_ignore_rows_flag(ignore_rows, line)
|
|
@@ -65,6 +67,20 @@ def generate_toc(original_lines, max_depth):
|
|
|
65
67
|
|
|
66
68
|
if "<!-- init-tocs -->" in line:
|
|
67
69
|
init_toc_position = i
|
|
70
|
+
|
|
71
|
+
if clear_depth:
|
|
72
|
+
continue
|
|
73
|
+
|
|
74
|
+
if max_depth:
|
|
75
|
+
tocs.append(f"<!-- depth={max_depth} -->")
|
|
76
|
+
elif init_toc_position + 1 < len(original_lines):
|
|
77
|
+
depth_match = re.fullmatch(
|
|
78
|
+
r"<!-- depth=(\d+) -->", original_lines[init_toc_position + 1]
|
|
79
|
+
)
|
|
80
|
+
if depth_match:
|
|
81
|
+
max_depth = int(depth_match.group(1))
|
|
82
|
+
tocs.append(f"<!-- depth={max_depth} -->")
|
|
83
|
+
|
|
68
84
|
elif "<!-- end-tocs -->" in line:
|
|
69
85
|
end_toc_position = i
|
|
70
86
|
elif line.startswith("#"):
|
|
@@ -109,9 +125,9 @@ def write_to(path, lines):
|
|
|
109
125
|
sys.exit(1)
|
|
110
126
|
|
|
111
127
|
|
|
112
|
-
def process(path: Path, depth: int | None = None, dry_run: bool = False):
|
|
128
|
+
def process(path: Path, depth: int | None = None, dry_run: bool = False, clear_depth: bool = False):
|
|
113
129
|
original_lines = read_lines_from(path)
|
|
114
|
-
lines_before_tocs, tocs, lines_after_tocs = generate_toc(original_lines, depth)
|
|
130
|
+
lines_before_tocs, tocs, lines_after_tocs = generate_toc(original_lines, depth, clear_depth)
|
|
115
131
|
|
|
116
132
|
if dry_run:
|
|
117
133
|
for t in tocs:
|
|
@@ -138,7 +154,12 @@ def main():
|
|
|
138
154
|
parser.add_argument(
|
|
139
155
|
"--depth", type=int, help="Maximum header depth to include in TOC"
|
|
140
156
|
)
|
|
141
|
-
parser.add_argument(
|
|
157
|
+
parser.add_argument(
|
|
158
|
+
"--clear-depth",
|
|
159
|
+
action="store_true",
|
|
160
|
+
help="Clear the max depth once it has been set and locked in the TOC marker",
|
|
161
|
+
)
|
|
162
|
+
parser.add_argument("--version", action="version", version="tocs 1.0.8")
|
|
142
163
|
parser.add_argument(
|
|
143
164
|
"--dry-run",
|
|
144
165
|
action="store_true",
|
|
@@ -155,7 +176,7 @@ def main():
|
|
|
155
176
|
print(f"Error: depth must be greater than 0", file=sys.stderr)
|
|
156
177
|
sys.exit(1)
|
|
157
178
|
|
|
158
|
-
process(path, args.depth, args.dry_run)
|
|
179
|
+
process(path, args.depth, args.dry_run, args.clear_depth)
|
|
159
180
|
|
|
160
181
|
|
|
161
182
|
if __name__ == "__main__":
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tocs
|
|
3
|
-
Version: 1.0.
|
|
3
|
+
Version: 1.0.8
|
|
4
4
|
Summary: Generate TOC for markdown files
|
|
5
5
|
Author-email: Andrea Bondanini <bondaniniandrea@gmail.com>
|
|
6
6
|
License: MIT
|
|
@@ -38,10 +38,18 @@ pip install --upgrade tocs
|
|
|
38
38
|
### Basic usage:
|
|
39
39
|
- `tocs input_file.md` - Generate TOC for the file
|
|
40
40
|
- `tocs --depth 2 input_file.md` - Limit the TOC generation to headers up to a specified depth
|
|
41
|
+
- `tocs --clear-depth input_file.md` - Remove a previously locked depth and generate a TOC with no depth limit
|
|
41
42
|
- `tocs --dry-run input_file.md` - Preview TOC without modifying the file
|
|
42
43
|
- `tocs --help` - Show usage instructions
|
|
43
44
|
- `tocs --version` - Display version information
|
|
44
45
|
|
|
46
|
+
### Depth lock
|
|
47
|
+
The first time you run `tocs` with `--depth N`, that value is written as a
|
|
48
|
+
`<!-- depth=N -->` marker inside the TOC block. On later runs, if you don't
|
|
49
|
+
pass `--depth` again, tocs reads that marker and reuses the same depth, so
|
|
50
|
+
you don't have to keep repeating the flag. Passing a new `--depth` overwrites
|
|
51
|
+
the lock, and `--clear-depth` removes it, going back to an unlimited TOC.
|
|
52
|
+
|
|
45
53
|
### tocs example
|
|
46
54
|
Given the following markdown file **input_file.md**:
|
|
47
55
|
```md
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|