mkdocs-include-markdown-plugin 6.0.5__tar.gz → 6.0.7__tar.gz

{mkdocs_include_markdown_plugin-6.0.5 → mkdocs_include_markdown_plugin-6.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mkdocs-include-markdown-plugin
-Version: 6.0.5
+Version: 6.0.7
 Summary: Mkdocs Markdown includer plugin.
 Project-URL: Source, https://github.com/mondeja/mkdocs-include-markdown-plugin
 Project-URL: Documentation, https://github.com/mondeja/mkdocs-include-markdown-plugin#documentation

{mkdocs_include_markdown_plugin-6.0.5 → mkdocs_include_markdown_plugin-6.0.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "6.0.5"
+version = "6.0.7"
 description = "Mkdocs Markdown includer plugin."
 readme = "README.md"
 license = "Apache-2.0"
@@ -74,7 +74,7 @@ dependencies = ["pytest~=7.0", "coverage~=6.4", "covdefaults"]
 
 [[tool.hatch.envs.tests.matrix]]
 python = ["py38", "py39", "py310", "py311", "py312"]
-mkdocs = ["1.4.0", "1.4.3", "1.5.0", "1.5.3"]
+mkdocs = ["1.4.0", "1.4.3", "1.5.0", "1.5.3", "1.6.0"]
 cache = ["yes", "no"]
 
 [tool.hatch.envs.tests.overrides]
@@ -83,6 +83,7 @@ matrix.mkdocs.dependencies = [
   { value = "mkdocs==1.4.3", if = ["1.4.3"] },
   { value = "mkdocs==1.5.0", if = ["1.5.0"] },
   { value = "mkdocs==1.5.3", if = ["1.5.3"] },
+  { value = "mkdocs==1.6.0", if = ["1.6.0"] },
 ]
 matrix.cache.dependencies = [{ value = "platformdirs", if = ["yes"] }]
 

{mkdocs_include_markdown_plugin-6.0.5 → mkdocs_include_markdown_plugin-6.0.7}/src/mkdocs_include_markdown_plugin/directive.py

@@ -8,6 +8,7 @@ import string
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from mkdocs.exceptions import PluginError
 from wcmatch import glob
 
 from mkdocs_include_markdown_plugin import process
@@ -174,19 +175,19 @@ def parse_bool_options(
 
 
 def resolve_file_paths_to_include(
-    filename_or_url: str,
-    includer_page_src_path: str,
+    include_string: str,
+    includer_page_src_path: str | None,
     docs_dir: str,
     ignore_paths: list[str],
 ) -> tuple[list[str], bool]:
     """Resolve the file paths to include for a directive."""
-    if process.is_url(filename_or_url):
-        return [filename_or_url], True
+    if process.is_url(include_string):
+        return [include_string], True
 
-    if process.is_absolute_path(filename_or_url):
+    if process.is_absolute_path(include_string):
         if os.name == 'nt':  # pragma: nt cover
             # Windows
-            fpath = os.path.normpath(filename_or_url)
+            fpath = os.path.normpath(include_string)
             if not os.path.isfile(fpath):
                 return [], False
 
@@ -195,13 +196,19 @@ def resolve_file_paths_to_include(
             ), False
         return process.filter_paths(
             glob.iglob(
-                os.path.normpath(filename_or_url),
+                os.path.normpath(include_string),
                 flags=GLOB_FLAGS,
             ),
             ignore_paths,
         ), False
 
-    if process.is_relative_path(filename_or_url):
+    if process.is_relative_path(include_string):
+        if includer_page_src_path is None:  # pragma: no cover
+            raise PluginError(
+                'Relative paths are not allowed when the includer page'
+                ' source path is not provided. The include string'
+                f" '{include_string}' is located inside a generated page.",
+            )
         root_dir = os.path.abspath(
             os.path.dirname(includer_page_src_path),
         )
@@ -209,7 +216,7 @@ def resolve_file_paths_to_include(
             (
                 os.path.normpath(os.path.join(root_dir, fp))
                 for fp in glob.iglob(
-                    filename_or_url,
+                    include_string,
                     flags=GLOB_FLAGS,
                     root_dir=root_dir,
                 )
@@ -221,7 +228,7 @@ def resolve_file_paths_to_include(
         (
             os.path.normpath(os.path.join(docs_dir, fp))
             for fp in glob.iglob(
-                filename_or_url,
+                include_string,
                 flags=GLOB_FLAGS,
                 root_dir=docs_dir,
             )
@@ -232,7 +239,7 @@ def resolve_file_paths_to_include(
 
 def resolve_file_paths_to_exclude(
     exclude_string: str,
-    includer_page_src_path: str,
+    includer_page_src_path: str | None,
     docs_dir: str,
 ) -> list[str]:
     """Resolve the file paths to exclude for a directive."""
@@ -241,6 +248,12 @@ def resolve_file_paths_to_exclude(
         return glob.glob(exclude_string, flags=GLOB_FLAGS)
 
     if process.is_relative_path(exclude_string):
+        if includer_page_src_path is None:  # pragma: no cover
+            raise PluginError(
+                'Relative paths are not allowed when the includer page'
+                ' source path is not provided. The exclude string'
+                f" '{exclude_string}' is located inside a generated page.",
+            )
         root_dir = os.path.abspath(
             os.path.dirname(includer_page_src_path),
         )

{mkdocs_include_markdown_plugin-6.0.5 → mkdocs_include_markdown_plugin-6.0.7}/src/mkdocs_include_markdown_plugin/event.py

@@ -58,9 +58,42 @@ def lineno_from_content_start(content: str, start: int) -> int:
     return content[:start].count('\n') + 1
 
 
+def safe_os_path_relpath(path: str, start: str) -> str:
+    """Return the relative path of a file from a start directory.
+
+    Safe version of `os.path.relpath` that catches `ValueError` exceptions
+    on Windows and returns the original path in case of error.
+    On Windows, `ValueError` is raised when `path` and `start` are on
+    different drives.
+    """
+    if os.name != 'nt':  # pragma: nt no cover
+        return os.path.relpath(path, start)
+    try:  # pragma: nt cover
+        return os.path.relpath(path, start)
+    except ValueError:  # pragma: no cover
+        return path
+
+
+def file_lineno_message(
+        page_src_path: str | None,
+        docs_dir: str,
+        lineno: int,
+) -> str:
+    """Return a message with the file path and line number."""
+    if page_src_path is None:  # pragma: no cover
+        return f'generated page content (line {lineno})'
+    return (
+        f'{safe_os_path_relpath(page_src_path, docs_dir)}'
+        f':{lineno}'
+    )
+
+
 def get_file_content(  # noqa: PLR0913, PLR0915
         markdown: str,
-        page_src_path: str,
+        # Generated pages return `None` for `file.abs_src_path` because
+        # they are not read from a file. In this case, page_src_path is
+        # set to `None`.
+        page_src_path: str | None,
         docs_dir: str,
         tags: IncludeTags,
         defaults: DefaultValues,
@@ -85,8 +118,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             )
             raise PluginError(
                 "Found no path passed including with 'include'"
-                f' directive at {os.path.relpath(page_src_path, docs_dir)}'
-                f':{lineno}',
+                ' directive at'
+                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
             )
 
         arguments_string = match['arguments']
@@ -114,9 +147,10 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 )
                 raise PluginError(
                     "Invalid empty 'exclude' argument in 'include'"
-                    f' directive at {os.path.relpath(page_src_path, docs_dir)}'
-                    f':{lineno}',
+                    ' directive at'
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
+
             ignore_paths.extend(
                 resolve_file_paths_to_exclude(
                     exclude_string,
@@ -139,9 +173,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 directive_match_start,
             )
             raise PluginError(
-                f"No files found including '{raw_filename}'"
-                f' at {os.path.relpath(page_src_path, docs_dir)}'
-                f':{lineno}',
+                f"No files found including '{raw_filename}' at"
+                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
             )
 
         if files_watcher is not None and not is_url:
@@ -160,8 +193,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             raise PluginError(
                 f"Invalid value for '{invalid_bool_args[0]}' argument of"
                 " 'include' directive at"
-                f' {os.path.relpath(page_src_path, docs_dir)}'
-                f':{lineno}. Possible values are true or false.',
+                f' {file_lineno_message(page_src_path, docs_dir, lineno)}.'
+                f' Possible values are true or false.',
             )
 
         start_match = ARGUMENT_REGEXES['start'].search(arguments_string)
@@ -173,8 +206,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                     directive_match_start,
                 )
                 raise PluginError(
-                    "Invalid empty 'start' argument in 'include' directive at "
-                    f'{os.path.relpath(page_src_path, docs_dir)}:{lineno}',
+                    "Invalid empty 'start' argument in 'include' directive at"
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
         else:
             start = defaults['start']
@@ -188,8 +221,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                     directive_match_start,
                 )
                 raise PluginError(
-                    "Invalid empty 'end' argument in 'include' directive at "
-                    f'{os.path.relpath(page_src_path, docs_dir)}:{lineno}',
+                    "Invalid empty 'end' argument in 'include' directive at"
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
         else:
             end = defaults['end']
@@ -204,8 +237,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 )
                 raise PluginError(
                     "Invalid empty 'encoding' argument in 'include'"
-                    ' directive at '
-                    f'{os.path.relpath(page_src_path, docs_dir)}:{lineno}',
+                    ' directive at'
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
         else:
             encoding = defaults['encoding']
@@ -270,7 +303,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             if expected_but_any_found[i]:
                 delimiter_value = locals()[delimiter_name]
                 readable_files_to_include = ', '.join([
-                    os.path.relpath(fpath, docs_dir)
+                    safe_os_path_relpath(fpath, docs_dir)
                     for fpath in file_paths_to_include
                 ])
                 plural_suffix = 's' if len(file_paths_to_include) > 1 else ''
@@ -278,12 +311,14 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                     markdown,
                     directive_match_start,
                 )
-                relative_path = os.path.relpath(page_src_path, docs_dir)
+                file_lineno = file_lineno_message(
+                    page_src_path, docs_dir, lineno,
+                )
                 logger.warning(
                     (
                         f"Delimiter {delimiter_name} '{delimiter_value}'"
                         " of 'include' directive at"
-                        f' {relative_path}:{lineno}'
+                        f' {file_lineno}'
                         f' not detected in the file{plural_suffix}'
                         f' {readable_files_to_include}'
                     ),
@@ -307,8 +342,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             )
             raise PluginError(
                 "Found no path passed including with 'include-markdown'"
-                f' directive at {os.path.relpath(page_src_path, docs_dir)}'
-                f':{lineno}',
+                f' directive at'
+                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
             )
 
         arguments_string = match['arguments']
@@ -336,8 +371,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 )
                 raise PluginError(
                     "Invalid empty 'exclude' argument in 'include-markdown'"
-                    f' directive at {os.path.relpath(page_src_path, docs_dir)}'
-                    f':{lineno}',
+                    f' directive at'
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
             ignore_paths.extend(
                 resolve_file_paths_to_exclude(
@@ -362,8 +397,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             )
             raise PluginError(
                 f"No files found including '{raw_filename}' at"
-                f' {os.path.relpath(page_src_path, docs_dir)}'
-                f':{lineno}',
+                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
             )
 
         if files_watcher is not None and not is_url:
@@ -386,8 +420,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             raise PluginError(
                 f"Invalid value for '{invalid_bool_args[0]}' argument of"
                 " 'include-markdown' directive at"
-                f' {os.path.relpath(page_src_path, docs_dir)}'
-                f':{lineno}. Possible values are true or false.',
+                f' {file_lineno_message(page_src_path, docs_dir, lineno)}.'
+                f' Possible values are true or false.',
             )
 
         # start and end arguments
@@ -401,8 +435,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 )
                 raise PluginError(
                     "Invalid empty 'start' argument in 'include-markdown'"
-                    f' directive at {os.path.relpath(page_src_path, docs_dir)}'
-                    f':{lineno}',
+                    f' directive at'
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
         else:
             start = defaults['start']
@@ -417,8 +451,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 )
                 raise PluginError(
                     "Invalid empty 'end' argument in 'include-markdown'"
-                    f' directive at {os.path.relpath(page_src_path, docs_dir)}'
-                    f':{lineno}',
+                    f' directive at'
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
         else:
             end = defaults['end']
@@ -433,8 +467,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 )
                 raise PluginError(
                     "Invalid empty 'encoding' argument in 'include-markdown'"
-                    ' directive at '
-                    f'{os.path.relpath(page_src_path, docs_dir)}:{lineno}',
+                    ' directive at'
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
         else:
             encoding = defaults['encoding']
@@ -453,7 +487,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 raise PluginError(
                     "Invalid empty 'heading-offset' argument in"
                     " 'include-markdown' directive at"
-                    f' {os.path.relpath(page_src_path, docs_dir)}:{lineno}',
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 )
             try:
                 offset = int(offset_raw_value)
@@ -464,8 +498,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 )
                 raise PluginError(
                     f"Invalid 'heading-offset' argument \"{offset_raw_value}\""
-                    " in 'include-markdown' directive at "
-                    f'{os.path.relpath(page_src_path, docs_dir)}:{lineno}',
+                    " in 'include-markdown' directive at"
+                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
                 ) from None
         else:
             offset = defaults['heading-offset']
@@ -523,11 +557,17 @@ def get_file_content(  # noqa: PLR0913, PLR0915
 
             # relative URLs rewriting
             if bool_options['rewrite-relative-urls'].value:
-                new_text_to_include = process.rewrite_relative_urls(
-                    new_text_to_include,
-                    source_path=file_path,
-                    destination_path=page_src_path,
-                )
+                if page_src_path is None:  # pragma: no cover
+                    logger.warning(
+                        'Relative URLs rewriting is not supported in'
+                        ' generated pages.',
+                    )
+                else:
+                    new_text_to_include = process.rewrite_relative_urls(
+                        new_text_to_include,
+                        source_path=file_path,
+                        destination_path=page_src_path,
+                    )
 
             # comments
             if bool_options['comments'].value:
@@ -569,7 +609,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             if expected_but_any_found[i]:
                 delimiter_value = locals()[delimiter_name]
                 readable_files_to_include = ', '.join([
-                    os.path.relpath(fpath, docs_dir)
+                    safe_os_path_relpath(fpath, docs_dir)
                     for fpath in file_paths_to_include
                 ])
                 plural_suffix = 's' if len(file_paths_to_include) > 1 else ''
@@ -577,12 +617,14 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                     markdown,
                     directive_match_start,
                 )
-                relative_path = os.path.relpath(page_src_path, docs_dir)
+                file_lineno = file_lineno_message(
+                    page_src_path, docs_dir, lineno,
+                )
                 logger.warning(
                     (
                         f"Delimiter {delimiter_name} '{delimiter_value}' of"
                         " 'include-markdown' directive at"
-                        f' {relative_path}:{lineno}'
+                        f' {file_lineno}'
                         f' not detected in the file{plural_suffix}'
                         f' {readable_files_to_include}'
                     ),