mkdocs-include-markdown-plugin 7.0.1__tar.gz → 7.1.2__tar.gz

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mkdocs-include-markdown-plugin
-Version: 7.0.1
+Version: 7.1.2
 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
@@ -135,14 +135,46 @@ plugins:
       cache: 600
 ```
 
-In order to use this feature, the dependency [platformdirs] must be installed.
-You can include it in the installation of the plugin adding the `cache` extra:
+In order to use this feature, the dependency [platformdirs] must be installed
+or the setting [`cache_dir`](#cache_dir) must be defined. You can include
+[platformdirs] in the installation of the plugin adding the `cache` extra:
 
 ```txt
 # requirements.txt
 mkdocs-include-markdown-plugin[cache]
 ```
 
+<!-- mdpo-disable-next-line -->
+
+#### `cache_dir`
+
+Directory where cached HTTP requests will be stored. If set, [platformdirs] is not
+needed to be installed to use [`cache`](#cache).
+
+```yaml
+plugins:
+  - include-markdown:
+      cache: 600
+      cache_dir: ./mkdocs-include-markdown-cache
+```
+
+A _.gitignore_ file will be added to the cache directory if not exists to avoid
+committing the cache files.
+
+<!-- mdpo-disable-next-line -->
+
+#### `directives`
+
+Customize the names of the directives.
+
+```yaml
+plugins:
+  - include-markdown:
+      directives:
+        include-markdown: include-md
+        include: replace
+```
+
 ### Reference
 
 This plugin provides two directives, one to include Markdown files and another

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/README.md

@@ -101,14 +101,46 @@ plugins:
       cache: 600
 ```
 
-In order to use this feature, the dependency [platformdirs] must be installed.
-You can include it in the installation of the plugin adding the `cache` extra:
+In order to use this feature, the dependency [platformdirs] must be installed
+or the setting [`cache_dir`](#cache_dir) must be defined. You can include
+[platformdirs] in the installation of the plugin adding the `cache` extra:
 
 ```txt
 # requirements.txt
 mkdocs-include-markdown-plugin[cache]
 ```
 
+<!-- mdpo-disable-next-line -->
+
+#### `cache_dir`
+
+Directory where cached HTTP requests will be stored. If set, [platformdirs] is not
+needed to be installed to use [`cache`](#cache).
+
+```yaml
+plugins:
+  - include-markdown:
+      cache: 600
+      cache_dir: ./mkdocs-include-markdown-cache
+```
+
+A _.gitignore_ file will be added to the cache directory if not exists to avoid
+committing the cache files.
+
+<!-- mdpo-disable-next-line -->
+
+#### `directives`
+
+Customize the names of the directives.
+
+```yaml
+plugins:
+  - include-markdown:
+      directives:
+        include-markdown: include-md
+        include: replace
+```
+
 ### Reference
 
 This plugin provides two directives, one to include Markdown files and another

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "7.0.1"
+version = "7.1.2"
 description = "Mkdocs Markdown includer plugin."
 readme = "README.md"
 license = "Apache-2.0"

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/src/mkdocs_include_markdown_plugin/cache.py

@@ -4,15 +4,9 @@ from __future__ import annotations
 
 import hashlib
 import os
+import stat
 import time
-
-
-try:
-    from platformdirs import user_data_dir
-except ImportError:  # pragma: no cover
-    CACHE_AVAILABLE = False
-else:
-    CACHE_AVAILABLE = True
+from importlib.util import find_spec
 
 
 class Cache:
@@ -37,13 +31,19 @@ class Cache:
         return hashlib.blake2b(url.encode(), digest_size=16).digest().hex()
 
     def read_file(self, fpath: str, encoding: str = 'utf-8') -> str:  # noqa: D102
-        with open(fpath, encoding=encoding) as f:
-            return f.read().split('\n', 1)[1]
+        f = open(fpath, encoding=encoding)  # noqa: SIM115
+        content = f.read().split('\n', 1)[1]
+        f.close()
+        return content
 
     def get_(self, url: str, encoding: str = 'utf-8') -> str | None:  # noqa: D102
         key = self.generate_unique_key_from_url(url)
         fpath = os.path.join(self.cache_dir, key)
-        if os.path.isfile(fpath):
+        try:
+            is_file = stat.S_ISREG(os.stat(fpath).st_mode)
+        except (FileNotFoundError, OSError):  # pragma: no cover
+            return None
+        if is_file:
             creation_time = self.get_creation_time_from_fpath(fpath)
             if time.time() < creation_time + self.expiration_seconds:
                 return self.read_file(fpath, encoding=encoding)
@@ -61,27 +61,52 @@ class Cache:
     def clean(self) -> None:
         """Clean expired entries from the cache."""
         for fname in os.listdir(self.cache_dir):
+            if fname == '.gitignore':
+                continue
             fpath = os.path.join(self.cache_dir, fname)
             creation_time = self.get_creation_time_from_fpath(fpath)
             if time.time() > creation_time + self.expiration_seconds:
                 os.remove(fpath)
 
 
-def get_cache_directory() -> str | None:
-    """Get the cache directory."""
-    if not CACHE_AVAILABLE:
-        return None
+def get_cache_directory(cache_dir: str) -> str | None:
+    """Get cache directory."""
+    if cache_dir:
+        return cache_dir
 
-    cache_dir = user_data_dir('mkdocs-include-markdown-plugin')
-    if not os.path.isdir(cache_dir):
-        os.makedirs(cache_dir)
+    if not is_platformdirs_installed():
+        return None
 
-    return cache_dir
+    try:
+        from platformdirs import user_data_dir
+    except ImportError:
+        return None
+    else:
+        return user_data_dir('mkdocs-include-markdown-plugin')
 
 
-def initialize_cache(expiration_seconds: int) -> Cache | None:
+def initialize_cache(expiration_seconds: int, cache_dir: str) -> Cache | None:
     """Initialize a cache instance."""
-    cache_dir = get_cache_directory()
-    return None if cache_dir is None else Cache(
-        cache_dir, expiration_seconds,
-    )
+    cache_directory = get_cache_directory(cache_dir)
+
+    if cache_directory is None:
+        return None
+
+    os.makedirs(cache_directory, exist_ok=True)
+
+    # Add a `.gitignore` file to prevent the cache directory from being
+    # included in the repository. This is needed because the cache directory
+    # can be configured as a relative path with `cache_dir` setting.
+    gitignore = os.path.join(cache_directory, '.gitignore')
+    if not os.path.exists(gitignore):
+        with open(gitignore, 'wb') as f:
+            f.write(b'*\n')
+
+    cache = Cache(cache_directory, expiration_seconds)
+    cache.clean()
+    return cache
+
+
+def is_platformdirs_installed() -> bool:
+    """Check if `platformdirs` package is installed without importing it."""
+    return find_spec('platformdirs') is not None

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/src/mkdocs_include_markdown_plugin/config.py

@@ -24,4 +24,13 @@ class PluginConfig(Config):  # noqa: D101
     end = Optional(MkType(str))
     exclude = ListOfItems(MkType(str), default=[])
     cache = MkType(int, default=0)
+    cache_dir = MkType(str, default='')
     recursive = MkType(bool, default=True)
+    directives = MkType(
+        dict,
+        default={
+            '__default': '',
+            'include': 'include',
+            'include-markdown': 'include-markdown',
+        },
+    )

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/src/mkdocs_include_markdown_plugin/directive.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import functools
 import os
 import re
+import stat
 import string
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
@@ -22,7 +24,7 @@ class DirectiveBoolArgument:  # noqa: D101
 
 
 if TYPE_CHECKING:  # pragma: no cover
-    from typing import Literal, TypedDict
+    from typing import Callable, Literal, TypedDict
 
     DirectiveBoolArgumentsDict = dict[str, DirectiveBoolArgument]
 
@@ -73,11 +75,13 @@ TRUE_FALSE_BOOL_STR = {
 }
 
 
+@functools.lru_cache
 def arg(arg: str) -> re.Pattern[str]:
     """Return a compiled regexp to match a boolean argument."""
     return re.compile(rf'{arg}=([{RE_ESCAPED_PUNCTUATION}\w]*)')
 
 
+@functools.lru_cache
 def str_arg(arg: str) -> re.Pattern[str]:
     """Return a compiled regexp to match a string argument."""
     return re.compile(
@@ -87,21 +91,23 @@ def str_arg(arg: str) -> re.Pattern[str]:
 
 
 ARGUMENT_REGEXES = {
-    'start': str_arg('start'),
-    'end': str_arg('end'),
-    'exclude': str_arg('exclude'),
-    'encoding': str_arg('encoding'),
+    'start': functools.partial(str_arg, 'start'),
+    'end': functools.partial(str_arg, 'end'),
+    'exclude': functools.partial(str_arg, 'exclude'),
+    'encoding': functools.partial(str_arg, 'encoding'),
 
     # bool
-    'comments': arg('comments'),
-    'preserve-includer-indent': arg('preserve-includer-indent'),
-    'dedent': arg('dedent'),
-    'trailing-newlines': arg('trailing-newlines'),
-    'rewrite-relative-urls': arg('rewrite-relative-urls'),
-    'recursive': arg('recursive'),
+    'comments': functools.partial(arg, 'comments'),
+    'preserve-includer-indent': functools.partial(
+        arg, 'preserve-includer-indent',
+    ),
+    'dedent': functools.partial(arg, 'dedent'),
+    'trailing-newlines': functools.partial(arg, 'trailing-newlines'),
+    'rewrite-relative-urls': functools.partial(arg, 'rewrite-relative-urls'),
+    'recursive': functools.partial(arg, 'recursive'),
 
     # int
-    'heading-offset': arg('heading-offset'),
+    'heading-offset': functools.partial(arg, 'heading-offset'),
 }
 
 INCLUDE_DIRECTIVE_ARGS = {
@@ -110,8 +116,6 @@ INCLUDE_DIRECTIVE_ARGS = {
     )
 }
 
-INCLUDE_MARKDOWN_DIRECTIVE_ARGS = set(ARGUMENT_REGEXES)
-
 WARN_INVALID_DIRECTIVE_ARGS_REGEX = re.compile(
     rf'[\w-]*=[{RE_ESCAPED_PUNCTUATION}\w]*',
 )
@@ -119,7 +123,7 @@ WARN_INVALID_DIRECTIVE_ARGS_REGEX = re.compile(
 
 def warn_invalid_directive_arguments(
     arguments_string: str,
-    directive_lineno: int,
+    directive_lineno: Callable[[], int],
     directive: Literal['include', 'include-markdown'],
     page_src_path: str | None,
     docs_dir: str,
@@ -127,15 +131,14 @@ def warn_invalid_directive_arguments(
     """Warns about the invalid arguments passed to a directive."""
     valid_args = (
         INCLUDE_DIRECTIVE_ARGS if directive == 'include'
-        else INCLUDE_MARKDOWN_DIRECTIVE_ARGS
+        else set(ARGUMENT_REGEXES)
     )
-    for arg_value in re.findall(
-        WARN_INVALID_DIRECTIVE_ARGS_REGEX,
+    for arg_value in WARN_INVALID_DIRECTIVE_ARGS_REGEX.findall(
         arguments_string,
     ):
         if arg_value.split('=', 1)[0] not in valid_args:
             location = process.file_lineno_message(
-                page_src_path, docs_dir, directive_lineno,
+                page_src_path, docs_dir, directive_lineno(),
             )
             logger.warning(
                 f"Invalid argument '{arg_value}' in"
@@ -172,7 +175,7 @@ def parse_string_argument(match: re.Match[str]) -> str | None:
 
 
 def create_include_tag(
-        opening_tag: str, closing_tag: str, tag: str = 'include',
+        opening_tag: str, closing_tag: str, tag: str,
 ) -> re.Pattern[str]:
     """Create a regex pattern to match an inclusion tag directive.
 
@@ -199,7 +202,7 @@ def parse_bool_options(
     for option_name in option_names:
         bool_options[option_name] = DirectiveBoolArgument(
             value=defaults[option_name],  # type: ignore
-            regex=ARGUMENT_REGEXES[option_name],
+            regex=ARGUMENT_REGEXES[option_name](),
         )
 
     for arg_name, arg in bool_options.items():
@@ -226,19 +229,28 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
         return [include_string], True
 
     if process.is_absolute_path(include_string):
-        if os.name == 'nt':  # pragma: nt cover
+        if os.name == 'nt':  # pragma: no cover
             # Windows
             fpath = os.path.normpath(include_string)
-            if not os.path.isfile(fpath):
+            try:
+                is_file = stat.S_ISREG(os.stat(fpath).st_mode)
+            except (FileNotFoundError, OSError):
+                is_file = False
+            if not is_file:
                 return [], False
 
             return process.filter_paths(
                 [fpath], ignore_paths,
             ), False
 
+        try:
+            is_file = stat.S_ISREG(os.stat(include_string).st_mode)
+        except (FileNotFoundError, OSError):
+            is_file = False
         return process.filter_paths(
-            [include_string] if os.path.isfile(include_string)
-            else glob.iglob(include_string, flags=GLOB_FLAGS),
+            [include_string] if is_file else glob.iglob(
+                include_string, flags=GLOB_FLAGS,
+            ),
             ignore_paths), False
 
     if process.is_relative_path(include_string):
@@ -253,7 +265,11 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
         )
         paths = []
         include_path = os.path.join(root_dir, include_string)
-        if os.path.isfile(include_path):
+        try:
+            is_file = stat.S_ISREG(os.stat(include_path).st_mode)
+        except (FileNotFoundError, OSError):
+            is_file = False
+        if is_file:
             paths.append(include_path)
         else:
             for fp in glob.iglob(
@@ -268,7 +284,11 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
     paths = []
     root_dir = docs_dir
     include_path = os.path.join(root_dir, include_string)
-    if os.path.isfile(include_path):
+    try:
+        is_file = stat.S_ISREG(os.stat(include_path).st_mode)
+    except (FileNotFoundError, OSError):
+        is_file = False
+    if is_file:
         paths.append(include_path)
     else:
         for fp in glob.iglob(

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/src/mkdocs_include_markdown_plugin/event.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import functools
 import html
 import os
 import re
@@ -17,6 +18,7 @@ from mkdocs_include_markdown_plugin.cache import Cache
 from mkdocs_include_markdown_plugin.directive import (
     ARGUMENT_REGEXES,
     GLOB_FLAGS,
+    create_include_tag,
     parse_bool_options,
     parse_filename_argument,
     parse_string_argument,
@@ -104,7 +106,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             match: re.Match[str],
     ) -> str:
         directive_match_start = match.start()
-        directive_lineno = process.lineno_from_content_start(
+        directive_lineno = functools.partial(
+            process.lineno_from_content_start,
             markdown,
             directive_match_start,
         )
@@ -114,7 +117,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         filename, raw_filename = parse_filename_argument(match)
         if filename is None:
             location = process.file_lineno_message(
-                page_src_path, docs_dir, directive_lineno,
+                page_src_path, docs_dir, directive_lineno(),
             )
             raise PluginError(
                 "Found no path passed including with 'include'"
@@ -131,13 +134,13 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             docs_dir,
         )
 
-        exclude_match = ARGUMENT_REGEXES['exclude'].search(arguments_string)
+        exclude_match = ARGUMENT_REGEXES['exclude']().search(arguments_string)
         ignore_paths = [*settings_ignore_paths]
         if exclude_match is not None:
             exclude_string = parse_string_argument(exclude_match)
             if exclude_string is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'exclude' argument in 'include'"
@@ -159,7 +162,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
 
         if not file_paths_to_include:
             location = process.file_lineno_message(
-                page_src_path, docs_dir, directive_lineno,
+                page_src_path, docs_dir, directive_lineno(),
             )
             raise PluginError(
                 f"No files found including '{raw_filename}' at {location}",
@@ -176,7 +179,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         )
         if invalid_bool_args:
             location = process.file_lineno_message(
-                page_src_path, docs_dir, directive_lineno,
+                page_src_path, docs_dir, directive_lineno(),
             )
             raise PluginError(
                 f"Invalid value for '{invalid_bool_args[0]}' argument of"
@@ -184,12 +187,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 f' Possible values are true or false.',
             )
 
-        start_match = ARGUMENT_REGEXES['start'].search(arguments_string)
+        start_match = ARGUMENT_REGEXES['start']().search(arguments_string)
         if start_match:
             start = parse_string_argument(start_match)
             if start is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'start' argument in 'include' directive at"
@@ -198,12 +201,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         else:
             start = defaults['start']
 
-        end_match = ARGUMENT_REGEXES['end'].search(arguments_string)
+        end_match = ARGUMENT_REGEXES['end']().search(arguments_string)
         if end_match:
             end = parse_string_argument(end_match)
             if end is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'end' argument in 'include' directive at"
@@ -212,12 +215,13 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         else:
             end = defaults['end']
 
-        encoding_match = ARGUMENT_REGEXES['encoding'].search(arguments_string)
+        encoding_match = ARGUMENT_REGEXES['encoding']().search(
+            arguments_string)
         if encoding_match:
             encoding = parse_string_argument(encoding_match)
             if encoding is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'encoding' argument in 'include'"
@@ -294,7 +298,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 ])
                 plural_suffix = 's' if len(file_paths_to_include) > 1 else ''
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 logger.warning(
                     f"Delimiter {delimiter_name} '{delimiter_value}'"
@@ -313,7 +317,8 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             match: re.Match[str],
     ) -> str:
         directive_match_start = match.start()
-        directive_lineno = process.lineno_from_content_start(
+        directive_lineno = functools.partial(
+            process.lineno_from_content_start,
             markdown,
             directive_match_start,
         )
@@ -324,7 +329,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         filename, raw_filename = parse_filename_argument(match)
         if filename is None:
             location = process.file_lineno_message(
-                page_src_path, docs_dir, directive_lineno,
+                page_src_path, docs_dir, directive_lineno(),
             )
             raise PluginError(
                 "Found no path passed including with 'include-markdown'"
@@ -341,13 +346,13 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             docs_dir,
         )
 
-        exclude_match = ARGUMENT_REGEXES['exclude'].search(arguments_string)
+        exclude_match = ARGUMENT_REGEXES['exclude']().search(arguments_string)
         ignore_paths = [*settings_ignore_paths]
         if exclude_match is not None:
             exclude_string = parse_string_argument(exclude_match)
             if exclude_string is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'exclude' argument in 'include-markdown'"
@@ -368,7 +373,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
 
         if not file_paths_to_include:
             location = process.file_lineno_message(
-                page_src_path, docs_dir, directive_lineno,
+                page_src_path, docs_dir, directive_lineno(),
             )
             raise PluginError(
                 f"No files found including '{raw_filename}' at {location}",
@@ -388,7 +393,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         )
         if invalid_bool_args:
             location = process.file_lineno_message(
-                page_src_path, docs_dir, directive_lineno,
+                page_src_path, docs_dir, directive_lineno(),
             )
             raise PluginError(
                 f"Invalid value for '{invalid_bool_args[0]}' argument of"
@@ -397,12 +402,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             )
 
         # start and end arguments
-        start_match = ARGUMENT_REGEXES['start'].search(arguments_string)
+        start_match = ARGUMENT_REGEXES['start']().search(arguments_string)
         if start_match:
             start = parse_string_argument(start_match)
             if start is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'start' argument in 'include-markdown'"
@@ -411,12 +416,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         else:
             start = defaults['start']
 
-        end_match = ARGUMENT_REGEXES['end'].search(arguments_string)
+        end_match = ARGUMENT_REGEXES['end']().search(arguments_string)
         if end_match:
             end = parse_string_argument(end_match)
             if end is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'end' argument in 'include-markdown'"
@@ -425,12 +430,13 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         else:
             end = defaults['end']
 
-        encoding_match = ARGUMENT_REGEXES['encoding'].search(arguments_string)
+        encoding_match = ARGUMENT_REGEXES['encoding']().search(
+            arguments_string)
         if encoding_match:
             encoding = parse_string_argument(encoding_match)
             if encoding is None:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'encoding' argument in 'include-markdown'"
@@ -440,14 +446,14 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             encoding = defaults['encoding']
 
         # heading offset
-        offset_match = ARGUMENT_REGEXES['heading-offset'].search(
+        offset_match = ARGUMENT_REGEXES['heading-offset']().search(
             arguments_string,
         )
         if offset_match:
             offset_raw_value = offset_match[1]
             if offset_raw_value == '':
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     "Invalid empty 'heading-offset' argument in"
@@ -457,7 +463,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 offset = int(offset_raw_value)
             except ValueError:
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 raise PluginError(
                     f"Invalid 'heading-offset' argument \"{offset_raw_value}\""
@@ -579,7 +585,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 ])
                 plural_suffix = 's' if len(file_paths_to_include) > 1 else ''
                 location = process.file_lineno_message(
-                    page_src_path, docs_dir, directive_lineno,
+                    page_src_path, docs_dir, directive_lineno(),
                 )
                 logger.warning(
                     f"Delimiter {delimiter_name} '{delimiter_value}' of"
@@ -630,8 +636,16 @@ def on_page_markdown(
         page.file.abs_src_path,
         docs_dir,
         {
-            'include': plugin._include_tag(),
-            'include-markdown': plugin._include_markdown_tag(),
+            'include': create_include_tag(
+                config.opening_tag,
+                config.closing_tag,
+                config.directives.get('include', 'include'),
+            ),
+            'include-markdown': create_include_tag(
+                config.opening_tag,
+                config.closing_tag,
+                config.directives.get('include-markdown', 'include-markdown'),
+            ),
         },
         {
             'encoding': config.encoding,

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/src/mkdocs_include_markdown_plugin/plugin.py

@@ -7,20 +7,18 @@ from functools import cached_property
 from typing import TYPE_CHECKING
 
 from mkdocs.exceptions import PluginError
-from mkdocs.livereload import LiveReloadServer
 from mkdocs.plugins import BasePlugin, event_priority
 
 
 if TYPE_CHECKING:  # pragma: no cover
-    import re
 
     from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.livereload import LiveReloadServer
     from mkdocs.structure.files import Files
     from mkdocs.structure.pages import Page
 
 from mkdocs_include_markdown_plugin.cache import Cache, initialize_cache
 from mkdocs_include_markdown_plugin.config import PluginConfig
-from mkdocs_include_markdown_plugin.directive import create_include_tag
 from mkdocs_include_markdown_plugin.event import (
     on_page_markdown as _on_page_markdown,
 )
@@ -33,31 +31,26 @@ class IncludeMarkdownPlugin(BasePlugin[PluginConfig]):
 
     def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
         if self.config.cache > 0:
-            cache = initialize_cache(self.config.cache)
+            cache = initialize_cache(self.config.cache, self.config.cache_dir)
             if cache is None:
                 raise PluginError(
-                    'The "platformdirs" package is required to use the'
-                    ' "cache" option. Install'
-                    ' mkdocs-include-markdown-plugin with the "cache"'
-                    ' extra to install it.',
+                    'Either `cache_dir` global setting must be configured or'
+                    ' `platformdirs` package is required to use the'
+                    ' `cache` option. Install mkdocs-include-markdown-plugin'
+                    " with the 'cache' extra to install `platformdirs`.",
                 )
-            cache.clean()
             self._cache = cache
 
-        return config
-
-    def _include_tag(self) -> re.Pattern[str]:
-        return create_include_tag(
-            self.config.opening_tag,
-            self.config.closing_tag,
-        )
+        if '__default' not in self.config.directives:  # pragma: no cover
+            for directive in self.config.directives:
+                if directive not in ('include', 'include-markdown'):
+                    raise PluginError(
+                        f"Invalid directive name '{directive}' at 'directives'"
+                        ' global setting. Valid values are "include" and'
+                        ' "include-markdown".',
+                    )
 
-    def _include_markdown_tag(self) -> re.Pattern[str]:
-        return create_include_tag(
-            self.config.opening_tag,
-            self.config.closing_tag,
-            tag='include-markdown',
-        )
+        return config
 
     @cached_property
     def _files_watcher(self) -> FilesWatcher:

{mkdocs_include_markdown_plugin-7.0.1 → mkdocs_include_markdown_plugin-7.1.2}/src/mkdocs_include_markdown_plugin/process.py

@@ -6,10 +6,9 @@ import functools
 import io
 import os
 import re
+import stat
 from collections.abc import Callable, Iterator
-from typing import TYPE_CHECKING, Any
-from urllib.parse import urlparse, urlunparse
-from urllib.request import Request, urlopen
+from typing import TYPE_CHECKING
 
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -245,11 +244,13 @@ def rewrite_relative_urls(
     ``source_path`` will still work when inserted into a file at
     ``destination_path``.
     """
+    from urllib.parse import urlparse, urlunparse
+
     def rewrite_url(url: str) -> str:
         scheme, netloc, path, params, query, fragment = urlparse(url)
 
         # absolute or mail
-        if is_relative_path(url) or path.startswith('/') or scheme == 'mailto':
+        if path.startswith('/') or scheme == 'mailto':
             return url
 
         new_path = os.path.relpath(
@@ -260,10 +261,13 @@ def rewrite_relative_urls(
         # ensure forward slashes are used, on Windows
         new_path = new_path.replace('\\', '/').replace('//', '/')
 
-        if path.endswith('/'):
-            # the above operation removes a trailing slash. Add it back if it
-            # was present in the input
-            new_path = new_path + '/'
+        try:
+            if path[-1] == '/':
+                # the above operation removes a trailing slash,
+                # so add it back if it was present in the input
+                new_path += '/'
+        except IndexError:  # pragma: no cover
+            pass
 
         return urlunparse((scheme, netloc, new_path, params, query, fragment))
 
@@ -351,9 +355,10 @@ def filter_inclusions(  # noqa: PLR0912
         if end not in text_to_include:
             expected_end_not_found = True
 
+        start_split = text_to_include.split(start)
         text_parts = (
-            text_to_include.split(start)[1:]
-            if start in text_to_include else [text_to_include]
+            start_split[1:]
+            if len(start_split) > 1 else [text_to_include]
         )
 
         for start_text in text_parts:
@@ -374,20 +379,34 @@ def _transform_negative_offset_func_factory(
         offset: int,
 ) -> Callable[[str], str]:
     heading_prefix = '#' * abs(offset)
-    return lambda line: line if not line.startswith('#') else (
-        heading_prefix + line.lstrip('#')
-        if line.startswith(heading_prefix)
-        else '#' + line.lstrip('#')
-    )
+
+    def transform(line: str) -> str:
+        try:
+            if line[0] != '#':
+                return line
+        except IndexError:  # pragma: no cover
+            return line
+        if line.startswith(heading_prefix):
+            return heading_prefix + line.lstrip('#')
+        return '#' + line.lstrip('#')
+
+    return transform
 
 
 def _transform_positive_offset_func_factory(
         offset: int,
 ) -> Callable[[str], str]:
     heading_prefix = '#' * offset
-    return lambda line: (
-        heading_prefix + line if line.startswith('#') else line
-    )
+
+    def transform(line: str) -> str:
+        try:
+            prefix = line[0]
+        except IndexError:  # pragma: no cover
+            return line
+        else:
+            return heading_prefix + line if prefix == '#' else line
+
+    return transform
 
 
 def increase_headings_offset(markdown: str, offset: int = 0) -> str:
@@ -403,7 +422,7 @@ def increase_headings_offset(markdown: str, offset: int = 0) -> str:
 
 def rstrip_trailing_newlines(content: str) -> str:
     """Removes trailing newlines from a string."""
-    while content.endswith('\n') or content.endswith('\r'):
+    while content.endswith(('\n', '\r')):
         content = content.rstrip('\r\n')
     return content
 
@@ -442,8 +461,11 @@ def filter_paths(
             continue
 
         # ignore if is a directory
-        if not os.path.isdir(filepath):
-            response.append(filepath)
+        try:
+            if not stat.S_ISDIR(os.stat(filepath).st_mode):
+                response.append(filepath)
+        except (FileNotFoundError, OSError):  # pragma: no cover
+            continue
     response.sort()
     return response
 
@@ -452,6 +474,8 @@ def is_url(string: str) -> bool:
     """Determine if a string is an URL."""
     if ':' not in string:  # fast path
         return False
+    from urllib.parse import urlparse
+
     try:
         result = urlparse(string)
         return all([result.scheme, result.netloc])
@@ -471,8 +495,10 @@ def is_absolute_path(string: str) -> bool:
 
 def read_file(file_path: str, encoding: str) -> str:
     """Read a file and return its content."""
-    with open(file_path, encoding=encoding) as f:
-        return f.read()
+    f = open(file_path, encoding=encoding)  # noqa: SIM115
+    content = f.read()
+    f.close()
+    return content
 
 
 def read_url(
@@ -481,6 +507,8 @@ def read_url(
         encoding: str = 'utf-8',
 ) -> Any:
     """Read an HTTP location and return its content."""
+    from urllib.request import Request, urlopen
+
     if http_cache is not None:
         cached_content = http_cache.get_(url, encoding)
         if cached_content is not None: