👌 IMPROVE: validate URL (#24)

Ensure value of `url` keys match regex used by Sphinx to identify them

Author: chrisjsewell

setup.cfg

@@ -29,7 +29,7 @@ project_urls =
 [options]
 packages = find:
 install_requires =
-    attrs>=19,<21
+    attrs>=19.2,<21
     click~=7.1
     pyyaml
     sphinx~=3.0

sphinx_external_toc/api.py

@@ -3,7 +3,7 @@
 from typing import Any, Dict, Iterator, List, Optional, Set, Union
 
 import attr
-from attr.validators import deep_iterable, instance_of, optional
+from attr.validators import deep_iterable, instance_of, matches_re, optional
 
 
 class FileItem(str):
@@ -23,7 +23,8 @@ class GlobItem(str):
 class UrlItem:
     """A URL in a toctree."""
 
-    url: str = attr.ib(validator=instance_of(str))
+    # regex should match sphinx.util.url_re
+    url: str = attr.ib(validator=[instance_of(str), matches_re(r".+://.*")])
     title: Optional[str] = attr.ib(None, validator=optional(instance_of(str)))
 
 

sphinx_external_toc/parsing.py

@@ -211,12 +211,18 @@ def _parse_doc_item(
                             f"'{item_key}' and '{other_key}' @ '{toc_path}{items_key}/{item_idx}'"
                         )
 
-            if link_keys == {FILE_KEY}:
-                items.append(FileItem(item_data[FILE_KEY]))
-            elif link_keys == {GLOB_KEY}:
-                items.append(GlobItem(item_data[GLOB_KEY]))
-            elif link_keys == {URL_KEY}:
-                items.append(UrlItem(item_data[URL_KEY], item_data.get("title")))
+            try:
+                if link_keys == {FILE_KEY}:
+                    items.append(FileItem(item_data[FILE_KEY]))
+                elif link_keys == {GLOB_KEY}:
+                    items.append(GlobItem(item_data[GLOB_KEY]))
+                elif link_keys == {URL_KEY}:
+                    items.append(UrlItem(item_data[URL_KEY], item_data.get("title")))
+            except (ValueError, TypeError) as exc:
+                exc_arg = exc.args[0] if exc.args else ""
+                raise MalformedError(
+                    f"item validation @ '{toc_path}{items_key}/{item_idx}': {exc_arg}"
+                ) from exc
 
         # generate toc key-word arguments
         keywords = {k: toc_data[k] for k in TOCTREE_OPTIONS if k in toc_data}
@@ -226,16 +232,20 @@ def _parse_doc_item(
 
         try:
             toc_item = TocTree(items=items, **keywords)
-        except TypeError as exc:
-            raise MalformedError(f"toctree validation @ '{toc_path}'") from exc
+        except (ValueError, TypeError) as exc:
+            exc_arg = exc.args[0] if exc.args else ""
+            raise MalformedError(
+                f"toctree validation @ '{toc_path}': {exc_arg}"
+            ) from exc
         toctrees.append(toc_item)
 
     try:
         doc_item = Document(
             docname=data[file_key], title=data.get("title"), subtrees=toctrees
         )
-    except TypeError as exc:
-        raise MalformedError(f"doc validation: {path}") from exc
+    except (ValueError, TypeError) as exc:
+        exc_arg = exc.args[0] if exc.args else ""
+        raise MalformedError(f"doc validation @ '{path}': {exc_arg}") from exc
 
     # list of docs that need to be parsed recursively (and path)
     docs_to_be_parsed_list = [

tests/_bad_toc_files/bad_option_value.yml

@@ -0,0 +1,5 @@
+root: intro
+options:
+  titlesonly: 2
+items:
+- file: doc1

tests/_bad_toc_files/bad_url.yml

@@ -0,0 +1,3 @@
+root: index
+items:
+- url: example.com

tests/test_parsing.py

@@ -26,6 +26,8 @@ def test_create_toc_dict(path: Path, data_regression):
 
 TOC_FILES_BAD = list(Path(__file__).parent.joinpath("_bad_toc_files").glob("*.yml"))
 ERROR_MESSAGES = {
+    "bad_option_value.yml": "toctree validation @ '/': 'titlesonly'",
+    "bad_url.yml": "item validation @ '/items/0': 'url' must match regex",
     "empty.yml": "toc is not a mapping:",
     "file_and_glob_present.yml": "item contains incompatible keys .* @ '/items/0'",
     "list.yml": "toc is not a mapping:",