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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tocs
3
- Version: 1.0.7
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.7"
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(line, anchor_occurrences, max_depth=None):
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("--version", action="version", version="tocs 1.0.7")
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.7
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