Skip to content

Commit 1ffebb2

Browse files
mondejamondeja
authored
Allow to configure HTTP cache directory (#244)
1 parent 6922478 commit 1ffebb2

File tree

17 files changed

+240
-76
lines changed

17 files changed

+240
-76
lines changed

‎.markdownlint-cli2.yaml

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
config:
22
no-duplicate-heading: false
33
no-inline-html: false
4+
emphasis-style:
5+
style: underscore

‎README.md

+20-2
Original file line numberDiff line numberDiff line change
@@ -101,8 +101,9 @@ plugins:
101101
cache: 600
102102
```
103103

104-
In order to use this feature, the dependency [platformdirs] must be installed.
105-
You can include it in the installation of the plugin adding the `cache` extra:
104+
In order to use this feature, the dependency [platformdirs] must be installed
105+
or the setting [`cache_dir`](#cache_dir) must be defined. You can include
106+
[platformdirs] in the installation of the plugin adding the `cache` extra:
106107

107108
```txt
108109
# requirements.txt
@@ -111,6 +112,23 @@ mkdocs-include-markdown-plugin[cache]
111112

112113
<!-- mdpo-disable-next-line -->
113114

115+
#### `cache_dir`
116+
117+
Directory where cached HTTP requests will be stored. If set, [platformdirs] is not
118+
needed to be installed to use [`cache`](#cache).
119+
120+
```yaml
121+
plugins:
122+
- include-markdown:
123+
cache: 600
124+
cache_dir: ./mkdocs-include-markdown-cache
125+
```
126+
127+
A _.gitignore_ file will be added to the cache directory if not exists to avoid
128+
committing the cache files.
129+
130+
<!-- mdpo-disable-next-line -->
131+
114132
#### `directives`
115133

116134
Customize the names of the directives.

‎examples/http-cache-dir/docs/README.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Header
2+
3+
{%
4+
include-markdown "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/examples/basic/docs/included.md"
5+
start="<--start-->"
6+
%}
7+
8+
## mkdocs.yml
9+
10+
```
11+
{%
12+
include "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/examples/basic/mkdocs.yml"
13+
%}
14+
```
15+
16+
## From cache
17+
18+
{%
19+
include-markdown "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/examples/basic/docs/included.md"
20+
start="<--start-->"
21+
%}

‎examples/http-cache-dir/mkdocs.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
site_name: Foo
2+
plugins:
3+
- include-markdown:
4+
cache: 600
5+
cache_dir: .mkdocs-include-markdown-cache

‎examples/http-cache/docs/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
{%
66
include-markdown "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/examples/basic/docs/included.md"
7+
start="<--start-->"
78
%}
89

910
## mkdocs.yml
@@ -18,4 +19,5 @@
1819

1920
{%
2021
include-markdown "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/examples/basic/docs/included.md"
22+
start="<--start-->"
2123
%}

‎locale/es/README.md

+18-2
Original file line numberDiff line numberDiff line change
@@ -88,14 +88,30 @@ plugins:
8888
cache: 600
8989
```
9090

91-
Para usar esta funcionalidad, la dependencia [platformdirs] debe ser instalada.
92-
Puedes incluirla en la instalación del plugin añadiendo el extra `cache`:
91+
Para poder utilizar esta función, se debe instalar la dependencia [platformdirs]
92+
o definir la configuración [`cache_dir`](#cache_dir). Puedes incluir
93+
[platformdirs] en la instalación del plugin agregando el extra `cache`:
9394

9495
```txt
9596
# requirements.txt
9697
mkdocs-include-markdown-plugin[cache]
9798
```
9899

100+
#### `cache_dir`
101+
102+
Directorio donde se almacenarán las solicitudes HTTP en caché. Si se configura,
103+
no es necesario instalar [platformdirs] para usar [`cache`](#cache).
104+
105+
```yaml
106+
plugins:
107+
- include-markdown:
108+
cache: 600
109+
cache_dir: ./mkdocs-include-markdown-cache
110+
```
111+
112+
Se agregará un archivo *.gitignore* al directorio de caché si no existe para
113+
evitar confirmar los archivos de caché.
114+
99115
#### `directives`
100116

101117
Personaliza los nombres de las directivas.

‎locale/es/README.md.po

+26-9
Original file line numberDiff line numberDiff line change
@@ -349,15 +349,6 @@ msgid ""
349349
msgstr ""
350350
"Relativas desde el archivo que las incluye (empezando por `./` o `../`)."
351351

352-
msgid ""
353-
"In order to use this feature, the dependency [platformdirs] must be "
354-
"installed. You can include it in the installation of the plugin adding the "
355-
"`cache` extra:"
356-
msgstr ""
357-
"Para usar esta funcionalidad, la dependencia [platformdirs] debe ser "
358-
"instalada. Puedes incluirla en la instalación del plugin añadiendo el extra "
359-
"`cache`:"
360-
361352
msgid "`opening_tag` and `closing_tag`"
362353
msgstr "`opening_tag` y `closing_tag`"
363354

@@ -454,3 +445,29 @@ msgstr ""
454445

455446
msgid "Customize the names of the directives."
456447
msgstr "Personaliza los nombres de las directivas."
448+
449+
msgid ""
450+
"In order to use this feature, the dependency [platformdirs] must be "
451+
"installed or the setting [`cache_dir`](#cache_dir) must be defined. You can "
452+
"include [platformdirs] in the installation of the plugin adding the `cache` "
453+
"extra:"
454+
msgstr ""
455+
"Para poder utilizar esta función, se debe instalar la dependencia "
456+
"[platformdirs] o definir la configuración [`cache_dir`](#cache_dir). Puedes "
457+
"incluir [platformdirs] en la instalación del plugin agregando el extra "
458+
"`cache`:"
459+
460+
msgid ""
461+
"Directory where cached HTTP requests will be stored. If set, [platformdirs] "
462+
"is not needed to be installed to use [`cache`](#cache)."
463+
msgstr ""
464+
"Directorio donde se almacenarán las solicitudes HTTP en caché. Si se "
465+
"configura, no es necesario instalar [platformdirs] para usar "
466+
"[`cache`](#cache)."
467+
468+
msgid ""
469+
"A *.gitignore* file will be added to the cache directory if not exists to "
470+
"avoid committing the cache files."
471+
msgstr ""
472+
"Se agregará un archivo *.gitignore* al directorio de caché si no existe para"
473+
" evitar confirmar los archivos de caché."

‎locale/fr/README.md

+19-2
Original file line numberDiff line numberDiff line change
@@ -88,14 +88,31 @@ plugins:
8888
```
8989

9090
Pour utiliser cette fonctionnalité, la dépendance [platformdirs] doit être
91-
installée. Vous pouvez l'inclure dans l'installation du plugin en ajoutant le
92-
supplément `cache`:
91+
installée ou le paramètre [`cache_dir`](#cache_dir) doit être défini. Vous
92+
pouvez inclure [platformdirs] dans l'installation du plugin en ajoutant le
93+
supplément `cache` :
9394

9495
```txt
9596
# requirements.txt
9697
mkdocs-include-markdown-plugin[cache]
9798
```
9899

100+
#### `cache_dir`
101+
102+
Répertoire dans lequel les requêtes HTTP mises en cache seront stockées. Si
103+
défini, [platformdirs] n'a pas besoin d'être installé pour utiliser
104+
[`cache`](#cache).
105+
106+
```yaml
107+
plugins:
108+
- include-markdown:
109+
cache: 600
110+
cache_dir: ./mkdocs-include-markdown-cache
111+
```
112+
113+
Un fichier *.gitignore* sera ajouté au répertoire de cache s'il n'existe pas pour
114+
éviter de valider les fichiers de cache.
115+
99116
#### `directives`
100117

101118
Personnaliser les noms des directives.

‎locale/fr/README.md.po

+26-9
Original file line numberDiff line numberDiff line change
@@ -348,15 +348,6 @@ msgid ""
348348
"Relative from the file that includes them (starting with `./` or `../`)."
349349
msgstr "Relatifs du fichiers qui les inclut (commençant par `./` ou `../`)."
350350

351-
msgid ""
352-
"In order to use this feature, the dependency [platformdirs] must be "
353-
"installed. You can include it in the installation of the plugin adding the "
354-
"`cache` extra:"
355-
msgstr ""
356-
"Pour utiliser cette fonctionnalité, la dépendance [platformdirs] doit être "
357-
"installée. Vous pouvez l'inclure dans l'installation du plugin en ajoutant "
358-
"le supplément `cache`:"
359-
360351
msgid "`opening_tag` and `closing_tag`"
361352
msgstr "`opening_tag` et `closing_tag`"
362353

@@ -453,3 +444,29 @@ msgstr ""
453444

454445
msgid "Customize the names of the directives."
455446
msgstr "Personnaliser les noms des directives."
447+
448+
msgid ""
449+
"In order to use this feature, the dependency [platformdirs] must be "
450+
"installed or the setting [`cache_dir`](#cache_dir) must be defined. You can "
451+
"include [platformdirs] in the installation of the plugin adding the `cache` "
452+
"extra:"
453+
msgstr ""
454+
"Pour utiliser cette fonctionnalité, la dépendance [platformdirs] doit être "
455+
"installée ou le paramètre [`cache_dir`](#cache_dir) doit être défini. Vous "
456+
"pouvez inclure [platformdirs] dans l'installation du plugin en ajoutant le "
457+
"supplément `cache` :"
458+
459+
msgid ""
460+
"Directory where cached HTTP requests will be stored. If set, [platformdirs] "
461+
"is not needed to be installed to use [`cache`](#cache)."
462+
msgstr ""
463+
"Répertoire dans lequel les requêtes HTTP mises en cache seront stockées. Si "
464+
"défini, [platformdirs] n'a pas besoin d'être installé pour utiliser "
465+
"[`cache`](#cache)."
466+
467+
msgid ""
468+
"A *.gitignore* file will be added to the cache directory if not exists to "
469+
"avoid committing the cache files."
470+
msgstr ""
471+
"Un fichier *.gitignore* sera ajouté au répertoire de cache s'il n'existe pas"
472+
" pour éviter de valider les fichiers de cache."

‎pyproject.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "mkdocs-include-markdown-plugin"
3-
version = "7.1.1"
3+
version = "7.1.2"
44
description = "Mkdocs Markdown includer plugin."
55
readme = "README.md"
66
license = "Apache-2.0"

‎src/mkdocs_include_markdown_plugin/cache.py

+33-15
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,6 @@
99
from importlib.util import find_spec
1010

1111

12-
CACHE_AVAILABLE = find_spec('platformdirs') is not None
13-
14-
1512
class Cache:
1613
"""Cache for arbitrary content, one file per entry."""
1714

@@ -64,31 +61,52 @@ def set_(self, url: str, value: str, encoding: str = 'utf-8') -> None: # noqa:
6461
def clean(self) -> None:
6562
"""Clean expired entries from the cache."""
6663
for fname in os.listdir(self.cache_dir):
64+
if fname == '.gitignore':
65+
continue
6766
fpath = os.path.join(self.cache_dir, fname)
6867
creation_time = self.get_creation_time_from_fpath(fpath)
6968
if time.time() > creation_time + self.expiration_seconds:
7069
os.remove(fpath)
7170

7271

73-
def get_cache_directory() -> str | None:
74-
"""Get the cache directory."""
75-
if not CACHE_AVAILABLE:
72+
def get_cache_directory(cache_dir: str) -> str | None:
73+
"""Get cache directory."""
74+
if cache_dir:
75+
return cache_dir
76+
77+
if not is_platformdirs_installed():
7678
return None
7779

7880
try:
7981
from platformdirs import user_data_dir
8082
except ImportError:
8183
return None
84+
else:
85+
return user_data_dir('mkdocs-include-markdown-plugin')
86+
87+
88+
def initialize_cache(expiration_seconds: int, cache_dir: str) -> Cache | None:
89+
"""Initialize a cache instance."""
90+
cache_directory = get_cache_directory(cache_dir)
91+
92+
if cache_directory is None:
93+
return None
8294

83-
cache_dir = user_data_dir('mkdocs-include-markdown-plugin')
84-
os.makedirs(cache_dir, exist_ok=True)
95+
os.makedirs(cache_directory, exist_ok=True)
8596

86-
return cache_dir
97+
# Add a `.gitignore` file to prevent the cache directory from being
98+
# included in the repository. This is needed because the cache directory
99+
# can be configured as a relative path with `cache_dir` setting.
100+
gitignore = os.path.join(cache_directory, '.gitignore')
101+
if not os.path.exists(gitignore):
102+
with open(gitignore, 'wb') as f:
103+
f.write(b'*\n')
87104

105+
cache = Cache(cache_directory, expiration_seconds)
106+
cache.clean()
107+
return cache
88108

89-
def initialize_cache(expiration_seconds: int) -> Cache | None:
90-
"""Initialize a cache instance."""
91-
cache_dir = get_cache_directory()
92-
return None if cache_dir is None else Cache(
93-
cache_dir, expiration_seconds,
94-
)
109+
110+
def is_platformdirs_installed() -> bool:
111+
"""Check if `platformdirs` package is installed without importing it."""
112+
return find_spec('platformdirs') is not None

‎src/mkdocs_include_markdown_plugin/config.py

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ class PluginConfig(Config): # noqa: D101
2424
end = Optional(MkType(str))
2525
exclude = ListOfItems(MkType(str), default=[])
2626
cache = MkType(int, default=0)
27+
cache_dir = MkType(str, default='')
2728
recursive = MkType(bool, default=True)
2829
directives = MkType(
2930
dict,

‎src/mkdocs_include_markdown_plugin/plugin.py

+6-9
Original file line numberDiff line numberDiff line change
@@ -31,22 +31,19 @@ class IncludeMarkdownPlugin(BasePlugin[PluginConfig]):
3131

3232
def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
3333
if self.config.cache > 0:
34-
cache = initialize_cache(self.config.cache)
34+
cache = initialize_cache(self.config.cache, self.config.cache_dir)
3535
if cache is None:
3636
raise PluginError(
37-
'The "platformdirs" package is required to use the'
38-
' "cache" option. Install'
39-
' mkdocs-include-markdown-plugin with the "cache"'
40-
' extra to install it.',
37+
'Either `cache_dir` global setting must be configured or'
38+
' `platformdirs` package is required to use the'
39+
' `cache` option. Install mkdocs-include-markdown-plugin'
40+
" with the 'cache' extra to install `platformdirs`.",
4141
)
42-
cache.clean()
4342
self._cache = cache
4443

4544
if '__default' not in self.config.directives: # pragma: no cover
4645
for directive in self.config.directives:
47-
if directive not in {
48-
'include', 'include-markdown',
49-
}:
46+
if directive not in ('include', 'include-markdown'):
5047
raise PluginError(
5148
f"Invalid directive name '{directive}' at 'directives'"
5249
' global setting. Valid values are "include" and'

‎src/mkdocs_include_markdown_plugin/process.py

+3-6
Original file line numberDiff line numberDiff line change
@@ -244,12 +244,9 @@ def rewrite_relative_urls(
244244
``source_path`` will still work when inserted into a file at
245245
``destination_path``.
246246
"""
247-
def rewrite_url(url: str) -> str:
248-
from urllib.parse import urlparse, urlunparse
249-
250-
if is_relative_path(url):
251-
return url
247+
from urllib.parse import urlparse, urlunparse
252248

249+
def rewrite_url(url: str) -> str:
253250
scheme, netloc, path, params, query, fragment = urlparse(url)
254251

255252
# absolute or mail
@@ -425,7 +422,7 @@ def increase_headings_offset(markdown: str, offset: int = 0) -> str:
425422

426423
def rstrip_trailing_newlines(content: str) -> str:
427424
"""Removes trailing newlines from a string."""
428-
while content.endswith('\n') or content.endswith('\r'):
425+
while content.endswith(('\n', '\r')):
429426
content = content.rstrip('\r\n')
430427
return content
431428

0 commit comments

Comments
 (0)