Add **kwargs to all filter functions for better compatibility.

RELEASE.md

@@ -1,3 +1,7 @@
+# Pandoc-Filter 0.2.2
+## Release 0.2.2
+Add `**kwargs` to all filter functions for better compatibility.
+
 # Pandoc-Filter 0.2.1
 ## Release 0.2.1
 Symplify `runtime_status_dict` to `runtime_dict`.

src/pandoc_filter/filters/md2html/centralize_figure.py

@@ -46,7 +46,7 @@
         - replace the original `Caption` element with the new one.
 """
 
-def _centralize_figure(elem:pf.Element,doc:pf.Doc)->None:
+def _centralize_figure(elem:pf.Element,doc:pf.Doc,**kwargs)->None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     An `action` function to centralize the `Figure` element.
     [modify elements in place]
@@ -55,7 +55,8 @@ def _centralize_figure(elem:pf.Element,doc:pf.Doc)->None:
     The `centralize_figure` filter is deprecated. Please use CSS files to define global styles and use them by `--css <css_files>`.
     See https://github.com/Zhaopudark/pandoc-filter/blob/main/src/pandoc_filter/filters/md2html/centralize_figure.py#L13 for more details.
     """)
-    tracing_logger = TracingLogger()
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
     if isinstance(elem, pf.Figure):
         tracing_logger.mark(elem)
         for img in elem.content:
@@ -69,5 +70,5 @@ def _centralize_figure(elem:pf.Element,doc:pf.Doc)->None:
         elem.caption = pf.Caption(centered_div)
         tracing_logger.check_and_log('figure',elem)
 
-def centralize_figure_filter(doc:pf.Doc=None):
-    return pf.run_filters(actions= [_centralize_figure],doc=doc)
+def centralize_figure_filter(doc:pf.Doc=None,**kwargs):
+    return pf.run_filters(actions= [_centralize_figure],doc=doc,tracing_logger=TracingLogger()**kwargs)

src/pandoc_filter/filters/md2html/enhance_link_like.py

@@ -8,19 +8,20 @@
 """
 
 
-def _enhance_link_like(elem:pf.Element,doc:pf.Doc)->pf.Link|None:
+def _enhance_link_like(elem:pf.Element,doc:pf.Doc,**kwargs)->pf.Link|None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     An action to process a string that may be like a link.
     Replace the string with a `Link` element.
     [replace elements]
     """
-    tracing_logger = TracingLogger()
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
     if isinstance(elem, pf.Str) and elem.text.lower().startswith('http'):
         tracing_logger.mark(elem)
         link = pf.Link(elem,url=elem.text)
         tracing_logger.check_and_log('link_like',elem)
         return link
 
-def enhance_link_like_filter(doc:pf.Doc=None)->pf.Doc:
-    return pf.run_filters(actions=[_enhance_link_like],doc=doc)
+def enhance_link_like_filter(doc:pf.Doc=None,**kwargs)->pf.Doc:
+    return pf.run_filters(actions=[_enhance_link_like],doc=doc,tracing_logger=TracingLogger(),**kwargs)
 

src/pandoc_filter/filters/md2html/hash_anchor_and_internal_link.py

@@ -1,4 +1,5 @@
 import re
+import functools
 
 import typeguard
 import panflute as pf
@@ -59,12 +60,14 @@ def _prepare_hash_anchor_and_internal_link(doc:pf.Doc):
          'internal_link_record':[]
          })
 
-def _hash_anchor_id(elem:pf.Element,doc:pf.Doc)->None:
+def _hash_anchor_id(elem:pf.Element,doc:pf.Doc,**kwargs)->None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     An `action` function to normalize any anchor's `id` to its hash.
     [modify elements in place]
     """
-    tracing_logger = TracingLogger()
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
+
     def _text_hash_count(text:str)->str:
         text_hash = get_text_hash(text)
         if text_hash in doc.runtime_dict['anchor_count']: # 按照text_hash值计数, 重复则加1
@@ -86,7 +89,7 @@ def _text_hash_count(text:str)->str:
         tracing_logger.check_and_log('raw-HTML anchor',elem)
 
 
-def _internal_link_recorder(elem:pf.Element,doc:pf.Doc)->None:
+def _internal_link_recorder(elem:pf.Element,doc:pf.Doc,**kwargs)->None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     A action to pre-normalize and record internal links's `url`.
     [modify nothing]
@@ -114,8 +117,10 @@ def _url_hash_guess(text:str)->str:
         url,guessed_url_with_num = _url_hash_guess(old_href)
         doc.runtime_dict['internal_link_record'].append(InternalLink(elem,url=url,guessed_url=guessed_url_with_num))
 
-def _finalize_hash_anchor_and_internal_link(doc:pf.Doc): 
-    tracing_logger = TracingLogger()
+def _finalize_hash_anchor_and_internal_link(doc:pf.Doc,**kwargs): 
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
+
     id_set = set()
     for k,v in doc.runtime_dict['anchor_count'].items():
         for i in range(1,v+1):
@@ -130,9 +135,10 @@ def _finalize_hash_anchor_and_internal_link(doc:pf.Doc):
             tracing_logger.logger.warning(f"{internal_link.elem}")
             tracing_logger.logger.warning(f"The internal link `{internal_link.url}` is invalid and will not be changed because no target header is found.")
 
-def hash_anchor_and_internal_link_filter(doc:pf.Doc=None)->pf.Doc:
+def hash_anchor_and_internal_link_filter(doc:pf.Doc=None,**kwargs)->pf.Doc:
+    __finalize_hash_anchor_and_internal_link = functools.partial(_finalize_hash_anchor_and_internal_link,tracing_logger=TracingLogger(),**kwargs)
     return pf.run_filters(
         actions= [_hash_anchor_id,_internal_link_recorder],
         prepare=_prepare_hash_anchor_and_internal_link,
-        finalize=_finalize_hash_anchor_and_internal_link,
-        doc=doc)
+        finalize=__finalize_hash_anchor_and_internal_link,
+        doc=doc,tracing_logger=TracingLogger(),**kwargs)

src/pandoc_filter/filters/md2md/enhance_equation.py

@@ -19,7 +19,7 @@ def _prepare_enhance_equation(doc:pf.Doc):
         'math':False})
 
 @typeguard.typechecked
-def _enhance_equation(elem:pf.Element,doc:pf.Doc)->None:
+def _enhance_equation(elem:pf.Element,doc:pf.Doc,**kwargs)->None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     An action to enhance math equations.
     [modify elements in place]
@@ -41,7 +41,9 @@ def _enhance_equation(elem:pf.Element,doc:pf.Doc)->None:
     \end{equation}
     ```
     """
-    tracing_logger = TracingLogger()
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
+
     if isinstance(elem, pf.elements.Math):
         doc.runtime_dict['math'] = True
         if elem.format == "DisplayMath":
@@ -71,5 +73,5 @@ def _enhance_equation(elem:pf.Element,doc:pf.Doc)->None:
             elem.text = f"\n{text.strip(" \n")}\n"
             tracing_logger.check_and_log('equation',elem)
 
-def enhance_equation_filter(doc:pf.Doc=None):
-    return pf.run_filters(actions=[_enhance_equation],prepare=_prepare_enhance_equation,doc=doc)
+def enhance_equation_filter(doc:pf.Doc=None,**kwargs):
+    return pf.run_filters(actions=[_enhance_equation],prepare=_prepare_enhance_equation,doc=doc,tracing_logger=TracingLogger(),**kwargs)

src/pandoc_filter/filters/md2md/norm_footnote.py

@@ -8,18 +8,20 @@
 """
 
 
-def _norm_footnote(elem:pf.Element,doc:pf.Doc)->pf.Note|None:
+def _norm_footnote(elem:pf.Element,doc:pf.Doc,**kwargs)->pf.Note|None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     An action to process footnotes.
     Remove unnecessary `\n` in the footnote content.
     [replace elements]
     """
-    tracing_logger = TracingLogger()
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
+
     if isinstance(elem, pf.Note):
         tracing_logger.mark(elem)
         elem = pf.Note(pf.Para(pf.Str(pf.stringify(elem.content).strip(" \n"))))
         tracing_logger.check_and_log('footnote',elem)
         return elem
 
-def norm_footnote_filter(doc:pf.Doc=None):
-    return pf.run_filters(actions=[_norm_footnote],doc=doc)
+def norm_footnote_filter(doc:pf.Doc=None,**kwargs):
+    return pf.run_filters(actions=[_norm_footnote],doc=doc,tracing_logger=TracingLogger(),**kwargs)

src/pandoc_filter/filters/md2md/norm_internal_link.py

@@ -34,12 +34,14 @@ def _decode_internal_link_url(url:str)->str:
     header_mimic = pf.convert_text(f"# {decoded_url}",input_format='markdown',output_format='gfm',standalone=True)
     return f"#{header_mimic.lstrip('# ')}"
 
-def _norm_internal_link(elem:pf.Element, doc:pf.Doc)->None:
+def _norm_internal_link(elem:pf.Element,doc:pf.Doc,**kwargs)->None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     An action to normalize any internal link's url. Decode if it is URL-encoded.
     [modify elements in place]
     """
-    tracing_logger = TracingLogger()
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
+
     if isinstance(elem, pf.Link) and elem.url.startswith('#'):
         tracing_logger.mark(elem)       
         elem.url = _decode_internal_link_url(elem.url)
@@ -49,5 +51,5 @@ def _norm_internal_link(elem:pf.Element, doc:pf.Doc)->None:
         elem.text = sub_html_href(elem.text,_decode_internal_link_url(old_href))
         tracing_logger.check_and_log('raw_anchor_links',elem)
 
-def norm_internal_link_filter(doc:pf.Doc=None):
-    return pf.run_filters(actions=[_norm_internal_link],doc=doc)
+def norm_internal_link_filter(doc:pf.Doc=None,**kwargs):
+    return pf.run_filters(actions=[_norm_internal_link],doc=doc,tracing_logger=TracingLogger(),**kwargs)

src/pandoc_filter/filters/md2md/upload_figure_to_aliyun.py

@@ -20,26 +20,17 @@
     The doc_path should be given in advance.
 """
 
-@typeguard.typechecked
-def _prepare_upload_figure_to_aliyun(doc:pf.Doc,*,doc_path:pathlib.Path)->None: 
-    assert doc_path.exists(),f"doc_path: {doc_path} does not exist."
-    assert os.environ['OSS_ENDPOINT_NAME'], "OSS_ENDPOINT_NAME is not given in environment variables."
-    assert os.environ['OSS_BUCKET_NAME'], "OSS_BUCKET_NAME is not given in environment variables."
-    assert os.environ['OSS_ACCESS_KEY_ID'], "OSS_ACCESS_KEY_ID is not given in environment variables."
-    assert os.environ['OSS_ACCESS_KEY_SECRET'], "OSS_ACCESS_KEY_SECRET is not given in environment variables."
-    doc.runtime_dict = DocRuntimeDict(
-        {'doc_path':doc_path,
-         'oss_helper':OssHelper(os.environ['OSS_ENDPOINT_NAME'],os.environ['OSS_BUCKET_NAME'])
-         })
-
-def _upload_figure_to_aliyun(elem:pf.Element,doc:pf.Doc)->None:
+def _upload_figure_to_aliyun(elem:pf.Element,doc:pf.Doc,**kwargs)->None:
     r"""Follow the general procedure of [Panflute](http://scorreia.com/software/panflute/)
     An `action` function to upload local pictures to Aliyun OSS. Replace the original src with the new one.
     [modify elements in place]
     """
-    tracing_logger = TracingLogger()
-    oss_helper: OssHelper = doc.runtime_dict['oss_helper']
-    doc_path: pathlib.Path = doc.runtime_dict['doc_path']
+    typeguard.check_type(kwargs['tracing_logger'],TracingLogger)
+    tracing_logger:TracingLogger = kwargs['tracing_logger']
+    typeguard.check_type(kwargs['oss_helper'],OssHelper)
+    oss_helper: OssHelper = kwargs['oss_helper']
+    typeguard.check_type(kwargs['doc_path'],pathlib.Path)
+    doc_path: pathlib.Path = kwargs['doc_path']
     if isinstance(elem, pf.Image) and (old_src:=str(elem.url)).startswith('.'): # reletive path
         new_src = oss_helper.maybe_upload_file_and_get_src(doc_path.parent/old_src)
         tracing_logger.mark(elem)
@@ -52,9 +43,15 @@ def _upload_figure_to_aliyun(elem:pf.Element,doc:pf.Doc)->None:
             tracing_logger.check_and_log('raw_html_img',elem)
 
 @typeguard.typechecked
-def upload_figure_to_aliyun_filter(doc:pf.Doc=None,doc_path:pathlib.Path=None):
-    __prepare_upload_figure_to_aliyun = functools.partial(_prepare_upload_figure_to_aliyun,doc_path=doc_path)
+def upload_figure_to_aliyun_filter(doc:pf.Doc=None,doc_path:pathlib.Path=None,**kwargs):
+    assert doc_path.exists(),f"doc_path: {doc_path} does not exist."
+    assert os.environ['OSS_ENDPOINT_NAME'], "OSS_ENDPOINT_NAME is not given in environment variables."
+    assert os.environ['OSS_BUCKET_NAME'], "OSS_BUCKET_NAME is not given in environment variables."
+    assert os.environ['OSS_ACCESS_KEY_ID'], "OSS_ACCESS_KEY_ID is not given in environment variables."
+    assert os.environ['OSS_ACCESS_KEY_SECRET'], "OSS_ACCESS_KEY_SECRET is not given in environment variables."
     return pf.run_filters(
         actions=[_upload_figure_to_aliyun],
-        prepare=__prepare_upload_figure_to_aliyun,
-        doc=doc)
+        doc=doc,
+        tracing_logger=TracingLogger(),
+        doc_path=doc_path,
+        oss_helper=OssHelper(os.environ['OSS_ENDPOINT_NAME'],os.environ['OSS_BUCKET_NAME']),**kwargs)

src/pandoc_filter/utils/oss_helper.py

@@ -7,7 +7,6 @@
 from oss2.models import BucketReferer
 
 class OssHelper:
-
     def __init__(self,endpoint_name:str,bucket_name:str) -> None:
         self.logger = _logger_factory('logs/oss_log',logging.INFO)
         # self.local_cache_dir = pathlib.Path(local_cache_dir)

src/pandoc_filter/version.py

@@ -4,4 +4,4 @@
 from .utils import check_pandoc_version
 
 check_pandoc_version(required_version='3.1.0')
-__version__ = '0.2.1'
+__version__ = '0.2.2'