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

{mkdocs_include_markdown_plugin-7.1.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.1.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,8 +135,9 @@ 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
@@ -145,6 +146,23 @@ 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.

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

@@ -101,8 +101,9 @@ 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
@@ -111,6 +112,23 @@ 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.

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

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

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

@@ -9,9 +9,6 @@ import time
 from importlib.util import find_spec
 
 
-CACHE_AVAILABLE = find_spec('platformdirs') is not None
-
-
 class Cache:
     """Cache for arbitrary content, one file per entry."""
 
@@ -64,31 +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:
+def get_cache_directory(cache_dir: str) -> str | None:
+    """Get cache directory."""
+    if cache_dir:
+        return cache_dir
+
+    if not is_platformdirs_installed():
         return None
 
     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_dir: str) -> Cache | None:
+    """Initialize a cache instance."""
+    cache_directory = get_cache_directory(cache_dir)
+
+    if cache_directory is None:
+        return None
 
-    cache_dir = user_data_dir('mkdocs-include-markdown-plugin')
-    os.makedirs(cache_dir, exist_ok=True)
+    os.makedirs(cache_directory, exist_ok=True)
 
-    return cache_dir
+    # 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 initialize_cache(expiration_seconds: int) -> Cache | None:
-    """Initialize a cache instance."""
-    cache_dir = get_cache_directory()
-    return None if cache_dir is None else Cache(
-        cache_dir, expiration_seconds,
-    )
+
+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.1.1 → mkdocs_include_markdown_plugin-7.1.2}/src/mkdocs_include_markdown_plugin/config.py

@@ -24,6 +24,7 @@ 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,

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

@@ -31,22 +31,19 @@ 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
 
         if '__default' not in self.config.directives:  # pragma: no cover
             for directive in self.config.directives:
-                if directive not in {
-                    'include', 'include-markdown',
-                }:
+                if directive not in ('include', 'include-markdown'):
                     raise PluginError(
                         f"Invalid directive name '{directive}' at 'directives'"
                         ' global setting. Valid values are "include" and'

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

@@ -244,12 +244,9 @@ def rewrite_relative_urls(
     ``source_path`` will still work when inserted into a file at
     ``destination_path``.
     """
-    def rewrite_url(url: str) -> str:
-        from urllib.parse import urlparse, urlunparse
-
-        if is_relative_path(url):
-            return url
+    from urllib.parse import urlparse, urlunparse
 
+    def rewrite_url(url: str) -> str:
         scheme, netloc, path, params, query, fragment = urlparse(url)
 
         # absolute or mail
@@ -425,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