tocs 1.0.2__py3-none-any.whl

tocs/main.py

@@ -0,0 +1,133 @@
+import argparse
+from pathlib import Path
+import re
+import sys
+
+INDENT_LEVEL = "    "
+
+
+def create_toc_row(line: str, max_depth: int = None) -> str:
+    hashes = 0
+    j = 0
+
+    while line[j] == "#":
+        hashes += 1
+        j += 1
+
+    if max_depth and hashes > max_depth:
+        return None
+
+    line_content = line[hashes + 1 :]
+    anchor = create_anchor(line_content)
+    toc_row = f"{INDENT_LEVEL *(hashes-1)}- [{line_content}](#{anchor})"
+    return toc_row
+
+
+def create_anchor(line_content: str) -> str:
+    anchor = re.sub(r"[^a-zA-Z0-9\-_ ]", "", line_content)
+    return anchor.replace(" ", "-").lower()
+
+
+def toggle_ignore_rows_flag(ignore_rows: bool, line: str):
+    """
+    Controls whether to ignore rows inside code snippets that start with ```.
+    Also handles multiline snippets.
+    """
+    if line == "```":
+        return not ignore_rows
+    elif line.startswith("```") and not line.endswith("```"):
+        return True
+    elif line.startswith("```") and line.endswith("```"):
+        return False
+    else:
+        return ignore_rows
+
+
+def process_file(path, depth=None):
+    lines = []
+    tocs = []
+    init_toc_position = -1
+    end_toc_position = -1
+    ignore_rows = False
+
+    try:
+        with open(path, "rt") as f:
+            lines = f.read().splitlines()
+    except (IOError, PermissionError) as e:
+        print(f"Error while reading {path}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    for i, line in enumerate(lines):
+        ignore_rows = toggle_ignore_rows_flag(ignore_rows, line)
+
+        if ignore_rows:
+            continue
+
+        if "<!-- init-tocs -->" in line:
+            init_toc_position = i
+        elif "<!-- end-tocs -->" in line:
+            end_toc_position = i
+        elif line.startswith("#"):
+            toc_row = create_toc_row(line, depth)
+            if toc_row:
+                tocs.append(toc_row)
+
+    if (
+        init_toc_position == -1
+        or end_toc_position == -1
+        or init_toc_position >= end_toc_position
+    ):
+        print(
+            f"Error: Missing or invalid TOC markers. Add '<!-- init-tocs -->' and '<!-- end-tocs -->' to your file.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    lines_before_tocs = lines[: init_toc_position + 1]
+    lines_after_tocs = lines[end_toc_position:]
+    new_lines = lines_before_tocs + tocs + lines_after_tocs
+
+    try:
+        with open(path, "w") as f:
+            for l in new_lines:
+                f.write(l + "\n")
+    except (IOError, PermissionError) as e:
+        print(f"Error while writing {path}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="tocs",
+        description="Generate table of contents for markdown files",
+        epilog="""
+  Examples:
+    tocs /path/to/file.md                    Generate TOC in file.md
+
+  Requirements:
+    The file must contain <!-- init-tocs --> and <!-- end-tocs --> markers.
+  """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument("file", help="Markdown file to process")
+    parser.add_argument(
+        "--depth", type=int, help="Maximum header depth to include in TOC"
+    )
+    parser.add_argument("--version", action="version", version="tocs 1.0.2")
+    args = parser.parse_args()
+    path = Path(args.file).resolve()
+
+    if not path.exists():
+        print(f"Error: File '{args.file}' not found", file=sys.stderr)
+        sys.exit(1)
+
+    if args.depth is not None and args.depth < 1:
+        print(f"Error: depth must be greater than 0", file=sys.stderr)
+        sys.exit(1)
+
+    process_file(path, args.depth)
+
+
+if __name__ == "__main__":
+    main()

tocs-1.0.2.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: tocs
+Version: 1.0.2
+Summary: Generate TOC for markdown files
+Author-email: Andrea Bondanini <bondaniniandrea@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sbundaz/tocs
+Project-URL: Repository, https://github.com/sbundaz/tocs
+Project-URL: Issues, https://github.com/sbundaz/tocs/issues
+Keywords: markdown,tocs,cli,documentation,generator
+Requires-Python: >=3.11.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Dynamic: license-file
+
+# tocs
+**tocs** is a simple CLI application written in Python that generates **the table of contents (TOC)** section for markdown files.<br>
+As a person who loves to write personal technical notes in markdown files, I needed something simple to use.
+
+## How to install and use tocs
+**Prerequisites:** Python 3.11.9+ and pipx installed (`pip install pipx`).
+
+At the moment only a **manual installation** is available:
+- clone the repository
+- from the root of the repository: `pipx install .`
+- to upgrade tocs version: `pipx upgrade tocs`
+
+**Basic usage:**<br>
+- `tocs input_file.md` - Generate TOC for the file
+- `tocs --help` - Show usage instructions
+- `tocs --version` - Display version information
+
+### tocs example
+Given the following markdown file **input_file.md**:
+```md
+# header 1
+Lorem ipsum dolor sit amet...
+
+## header 2
+Lorem ipsum dolor sit amet...
+
+### header 3
+Lorem ipsum dolor sit amet...
+```
+
+Add two tags where you want the TOCs table:
+```md
+<!-- init-tocs -->
+<!-- end-tocs -->
+
+# header 1
+Lorem ipsum dolor sit amet...
+
+## header 2
+Lorem ipsum dolor sit amet...
+
+### header 3
+Lorem ipsum dolor sit amet...
+```
+
+Run `tocs input_file.md` and here's the output:
+
+```md
+<!-- init-tocs -->
+- [header 1](#header-1)
+    - [header 2](#header-2)
+        - [header 3](#header-3)
+
+<!-- end-tocs -->
+
+# header 1
+Lorem ipsum dolor sit amet...
+
+## header 2
+Lorem ipsum dolor sit amet...
+
+### header 3
+Lorem ipsum dolor sit amet...
+```
+
+## Development
+- create venv: `python -m venv .venv`
+- activate venv: `source .venv/bin/activate`
+- install project and dependencies (editable mode): `pip install -e .[dev]`
+- deactivate venv: `deactivate`

tocs-1.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+tocs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tocs/main.py,sha256=ombPe8jl7-cVw9DSQCmNPcVnCbM6gNicojiwINChSlM,3664
+tocs-1.0.2.dist-info/licenses/LICENSE,sha256=qJceCqujZXzRT59eqPEsb4TV_ROPTcT-pPB0HCezJRs,1060
+tocs-1.0.2.dist-info/METADATA,sha256=Kgo34yDoDN9_MIlzK21zgUOui4Bq5_7fLsqS2cZL6ko,2242
+tocs-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tocs-1.0.2.dist-info/entry_points.txt,sha256=_bClPsOh1CuzHjfiFZjZ0_3XOvhgXE_aohdgVlH9-J8,40
+tocs-1.0.2.dist-info/top_level.txt,sha256=1jLTMx9e_xv0vNs8qX52AELh14SGKXnmDNSiF_cAR0o,5
+tocs-1.0.2.dist-info/RECORD,,

tocs-1.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tocs-1.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tocs = tocs.main:main

tocs-1.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Andrea Bondanini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

tocs-1.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+tocs