tocs 1.0.2__tar.gz

tocs-1.0.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,70 @@
+# 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/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "tocs"
+description = "Generate TOC for markdown files"
+authors = [{ name = "Andrea Bondanini", email = "bondaniniandrea@gmail.com" }]
+license = { text = "MIT" }
+version = "1.0.2"
+requires-python = ">=3.11.9"
+readme = "README.md"
+keywords = ["markdown", "tocs", "cli", "documentation", "generator"]
+urls = { "Homepage" = "https://github.com/sbundaz/tocs", "Repository" = "https://github.com/sbundaz/tocs", "Issues" = "https://github.com/sbundaz/tocs/issues" }
+
+[project.optional-dependencies]
+dev = ["pytest", "black"]
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["tocs"]
+
+[project.scripts]
+tocs = "tocs.main:main"
+
+[tool.black]
+line-length = 88
+include = '\.pyi?$'
+extend-exclude = '''
+  /(
+    # directories
+    \.eggs
+    | \.git
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | build
+    | dist
+  )/
+  '''

tocs-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tocs-1.0.2/tests/test_toc.py

@@ -0,0 +1,148 @@
+import shutil
+import subprocess
+import tempfile
+import pytest
+from tocs.main import INDENT_LEVEL, create_toc_row
+
+
+def test_lorem_ipsum():
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
+        shutil.copy("tests/fixtures/lorem_ipsum_input.md", tmp.name)
+
+        result = subprocess.run(
+            ["python3", "tocs/main.py", tmp.name], capture_output=True, text=True
+        )
+
+        assert result.returncode == 0
+
+        with open(tmp.name) as f:
+            actual = f.read()
+
+        with open("tests/fixtures/lorem_ipsum_output.md") as f:
+            expected = f.read()
+
+        assert actual == expected
+
+
+def test_lorem_ipsum_depth_2():
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
+        shutil.copy("tests/fixtures/lorem_ipsum_depth_2_input.md", tmp.name)
+
+        result = subprocess.run(
+            ["python3", "tocs/main.py", tmp.name, "--depth", "2"],
+            capture_output=True,
+            text=True,
+        )
+
+        assert result.returncode == 0
+
+        with open(tmp.name) as f:
+            actual = f.read()
+
+        with open("tests/fixtures/lorem_ipsum_depth_2_output.md") as f:
+            expected = f.read()
+
+        assert actual == expected
+
+
+def test_lorem_ipsum_with_invalid_depth():
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
+        shutil.copy("tests/fixtures/lorem_ipsum_depth_2_input.md", tmp.name)
+
+        result = subprocess.run(
+            ["python3", "tocs/main.py", tmp.name, "--depth", "0"],
+            capture_output=True,
+            text=True,
+        )
+
+        print(result)
+
+        assert result.returncode == 1
+        assert result.stderr == "Error: depth must be greater than 0\n"
+
+
+@pytest.mark.parametrize(
+    "fixture_file_name",
+    [
+        "wrong_toc_config_init.md",
+        "wrong_toc_config_end.md",
+        "wrong_toc_config_order.md",
+    ],
+)
+def test_invalid_toc_configuration(fixture_file_name):
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md") as tmp:
+        shutil.copy(f"tests/fixtures/{fixture_file_name}", tmp.name)
+
+        result = subprocess.run(
+            ["python3", "tocs/main.py", tmp.name], capture_output=True, text=True
+        )
+
+        assert result.returncode == 1
+        assert (
+            result.stderr
+            == "Error: Missing or invalid TOC markers. Add '<!-- init-tocs -->' and '<!-- end-tocs -->' to your file.\n"
+        )
+
+
+def test_create_toc_row_h1():
+    header = "# Hello World"
+
+    result = create_toc_row(header)
+
+    assert result == "- [Hello World](#hello-world)"
+
+
+def test_create_toc_row_h2():
+    header = "## Hello World"
+
+    result = create_toc_row(header)
+
+    assert result == f"{INDENT_LEVEL}- [Hello World](#hello-world)"
+
+
+def test_create_toc_row_h3():
+    header = "### Hello World"
+
+    result = create_toc_row(header)
+
+    assert result == f"{INDENT_LEVEL}{INDENT_LEVEL}- [Hello World](#hello-world)"
+
+
+def test_create_toc_with_hyphen():
+    header = "# Hello-World"
+
+    result = create_toc_row(header)
+
+    assert result == "- [Hello-World](#hello-world)"
+
+
+def test_create_toc_with_multiple_hyphens():
+    header = "# Hello--World"
+
+    result = create_toc_row(header)
+
+    assert result == "- [Hello--World](#hello--world)"
+
+
+def test_create_toc_with_underscore():
+    header = "# Hello_World"
+
+    result = create_toc_row(header)
+
+    assert result == "- [Hello_World](#hello_world)"
+
+
+def test_create_toc_with_multiple_underscore():
+    header = "# Hello__World"
+
+    result = create_toc_row(header)
+
+    assert result == "- [Hello__World](#hello__world)"
+
+
+def test_create_toc_remove_special_chars():
+    header = "# Hello!?.:;'\"()[]{}@#$%^&*+=<>/\\|`~World"
+
+    result = create_toc_row(header)
+
+    assert result == "- [Hello!?.:;'\"()[]{}@#$%^&*+=<>/\\|`~World](#helloworld)"

tocs-1.0.2/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/tocs.egg-info/PKG-INFO

@@ -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/tocs.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_toc.py
+tocs/__init__.py
+tocs/main.py
+tocs.egg-info/PKG-INFO
+tocs.egg-info/SOURCES.txt
+tocs.egg-info/dependency_links.txt
+tocs.egg-info/entry_points.txt
+tocs.egg-info/requires.txt
+tocs.egg-info/top_level.txt

tocs-1.0.2/tocs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tocs-1.0.2/tocs.egg-info/entry_points.txt

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

tocs-1.0.2/tocs.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest
+black

tocs-1.0.2/tocs.egg-info/top_level.txt

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