clld-markdown-plugin 0.4.0__tar.gz → 1.0.0__tar.gz

{clld_markdown_plugin-0.4.0 → clld_markdown_plugin-1.0.0}/PKG-INFO

@@ -1,29 +1,43 @@
 Metadata-Version: 2.1
 Name: clld_markdown_plugin
-Version: 0.4.0
+Version: 1.0.0
 Summary: Render CLDF markdown in clld apps.
 Home-page: https://github.com/clld/clld-markdown-plugin
 Author: Robert Forkel, Florian Matter
 Author-email: robert_forkel@eva.mpg.de, florianmatter@gmail.com
 Project-URL: Bug Tracker, https://github.com/clld/clld-markdown-plugin/issues
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: frontmatter<1.2; python_version < "3.10"
+Requires-Dist: clldutils
+Requires-Dist: pycldf
+Requires-Dist: clld
+Requires-Dist: markdown
 Provides-Extra: dev
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: build; extra == "dev"
 Provides-Extra: test
-License-File: LICENSE
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: tox; extra == "test"
 
 # clld-markdown-plugin
 
-Render CLDF markdown in clld apps
+Render [CLDF markdown](https://github.com/cldf/cldf/blob/master/extensions/markdown.md) in clld apps
 
 ## Usage
 
@@ -47,8 +61,25 @@ Then you can use `clld_markdown_plugin.markup` as follows in your templates:
 ${markdown(req, '[x](LanguageTable#cldf:abad1241)')|n}
 ```
 
+By default, links to objects in the CLDF dataset will be rendered as HTML links to the corresponding
+object's details page in the clld app.
+
+
+### Configuration
+
+The plugin can be configured via the following four configuration options:
+
+- `model_map`: A `dict` mapping CLDF component names to DB model classes defined for the app. This
+  allows for a flexible mapping between CLDF components and the clld DB classes.
+- `renderer_map`: See below for details.
+- `extensions`: A list of [markdown extensions](https://python-markdown.github.io/extensions/#officially-supported-extensions)
+  in dot notation, to be activated when calling the `markdown` function.
+- `keep_link_labels`: A `boolean` indicating whether to keep link labels as they appear in the
+  CLDF Markdown text. By default (`False`), labels will be substituted using the linked object's
+  name.
+
 
-### Renderer callables
+#### Renderer callables
 
 The `renderer_map` configuration option for `clld_markdown_plugin` accepts a `dict` mapping
 CLDF component names to Python callables with the following signature:

{clld_markdown_plugin-0.4.0 → clld_markdown_plugin-1.0.0}/README.md

@@ -1,6 +1,6 @@
 # clld-markdown-plugin
 
-Render CLDF markdown in clld apps
+Render [CLDF markdown](https://github.com/cldf/cldf/blob/master/extensions/markdown.md) in clld apps
 
 ## Usage
 
@@ -24,8 +24,25 @@ Then you can use `clld_markdown_plugin.markup` as follows in your templates:
 ${markdown(req, '[x](LanguageTable#cldf:abad1241)')|n}
 ```
 
+By default, links to objects in the CLDF dataset will be rendered as HTML links to the corresponding
+object's details page in the clld app.
 
-### Renderer callables
+
+### Configuration
+
+The plugin can be configured via the following four configuration options:
+
+- `model_map`: A `dict` mapping CLDF component names to DB model classes defined for the app. This
+  allows for a flexible mapping between CLDF components and the clld DB classes.
+- `renderer_map`: See below for details.
+- `extensions`: A list of [markdown extensions](https://python-markdown.github.io/extensions/#officially-supported-extensions)
+  in dot notation, to be activated when calling the `markdown` function.
+- `keep_link_labels`: A `boolean` indicating whether to keep link labels as they appear in the
+  CLDF Markdown text. By default (`False`), labels will be substituted using the linked object's
+  name.
+
+
+#### Renderer callables
 
 The `renderer_map` configuration option for `clld_markdown_plugin` accepts a `dict` mapping
 CLDF component names to Python callables with the following signature:

{clld_markdown_plugin-0.4.0 → clld_markdown_plugin-1.0.0}/setup.cfg

@@ -1,18 +1,19 @@
 [metadata]
-version = 0.4.0
+version = 1.0.0
 author = Robert Forkel, Florian Matter
 author_email = robert_forkel@eva.mpg.de, florianmatter@gmail.com
 classifiers = 
-	Development Status :: 2 - Pre-Alpha
+	Development Status :: 5 - Production/Stable
 	Intended Audience :: Science/Research
 	License :: OSI Approved :: Apache Software License
 	Natural Language :: English
 	Programming Language :: Python :: 3
-	Programming Language :: Python :: 3.8
 	Programming Language :: Python :: 3.9
 	Programming Language :: Python :: 3.10
 	Programming Language :: Python :: 3.11
 	Programming Language :: Python :: 3.12
+	Programming Language :: Python :: 3.13
+	Programming Language :: Python :: 3.14
 description = Render CLDF markdown in clld apps.
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -28,6 +29,7 @@ packages = find:
 package_dir = 
 	=src
 install_requires = 
+	frontmatter<1.2;python_version<"3.10"
 	clldutils
 	pycldf
 	clld
@@ -67,7 +69,7 @@ source =
 show_missing = true
 
 [tox:tox]
-envlist = py38, py39, py310, py311, py312
+envlist = py39, py310, py311, py312, py313, py314
 isolated_build = true
 skip_missing_interpreter = true
 

{clld_markdown_plugin-0.4.0 → clld_markdown_plugin-1.0.0}/src/clld_markdown_plugin/__init__.py

@@ -1,10 +1,12 @@
 """Top-level package for clld-markdown-plugin."""
-import typing
 import logging
+from collections.abc import Sequence
+from typing import Optional, Callable, Any
 
 from markdown import Markdown
 from markdown import markdown as base_markdown
 from pycldf.ext.markdown import CLDFMarkdownLink
+from clld.web.app import ClldRequest
 from clld.db.meta import DBSession
 from clld.db.models import common
 from clld.web.util.helpers import rendered_sentence
@@ -16,11 +18,12 @@ log = logging.getLogger(__name__)
 
 __author__ = "Robert Forkel, Florian Matter"
 __email__ = "robert_forkel@eva.mpg.de, florianmatter@gmail.com"
-__version__ = "0.4.0"
+__version__ = "1.0.0"
 __all__ = ['markdown', 'includeme']
 
 
-def settings(custom: typing.Optional[dict] = None) -> dict:
+def settings(custom: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+    """Settings relevant for rendering CLDF Markdown."""
     def full_spec(spec):
         return spec if isinstance(spec, dict) else {
             'route': spec.__name__.split('.')[-1].lower() if spec else '', 'model': spec}
@@ -43,10 +46,11 @@ def settings(custom: typing.Optional[dict] = None) -> dict:
         "extensions": [
             "markdown.extensions.fenced_code",
             "markdown.extensions.tables",
-        ]
+        ],
+        "keep_link_labels": False,
     }
     custom = custom or {}
-    for key in res:
+    for key in res:  # pylint: disable=consider-using-dict-items
         if key == 'model_map':
             for k, v in custom.get(key, {}).items():
                 res[key][k] = full_spec(v)
@@ -54,6 +58,8 @@ def settings(custom: typing.Optional[dict] = None) -> dict:
             res[key].update(custom.get(key, {}))
         elif key == "extensions":
             res[key].extend(custom.get(key, []))
+        elif key in custom:
+            res[key] = custom[key]
     return res
 
 
@@ -75,41 +81,48 @@ def includeme(config):
     return config
 
 
-def comma_and_list(entries, sep1=", ", sep2=" and "):
+def _comma_and_list(entries: Sequence[str], sep1: str = ", ", sep2: str = " and ") -> str:
     output = entries[0]
     for entry in entries[1:-1]:
         output += sep1 + entry
     return output + sep2 + entries[-1]
 
 
-def link_entity(req, objid, route, model, session, decorate=None, ids=None, **kwargs):
+def link_entity(  # pylint: disable=R0913,R0917
+        req: ClldRequest,
+        objid: str,
+        route: str,
+        model: type,
+        session,
+        decorate: Optional[Callable[[str], str]] = None,
+        ids: Optional[Sequence[str]] = None,
+        **kwargs,
+) -> str:
+    """Render a CLDF Markdown link as HTML."""
     if objid == "__all__":
         if ids:
-            md_strs = [
+            return _comma_and_list([
                 link_entity(req, mid, route, model, session, decorate=decorate, **kwargs)
                 for mid in ids[0].split(",")
-            ]
-            return comma_and_list(md_strs)
+            ])
         raise NotImplementedError("Table not yet implemented")  # pragma: no cover
-    else:
-        try:
-            entity = session.query(model).filter(model.id == objid)[0]
-        except IndexError:
-            raise ValueError(objid)  # pragma: no cover
-        label = kwargs.pop("label", [None])[0]
-        anchor = kwargs.pop("_anchor", [None])[0]
-        url = req.route_url(route, id=objid, _anchor=anchor, **kwargs)
-        md_str = '<a class="{}" href="{}">{}</a>'.format(
-            model.__tablename__.capitalize(), url, label or entity.name)
-        return decorate(md_str) if decorate else md_str
-
-
-def render_ex(req, objid, table, session, ids=None, **kw):
+    try:
+        entity = session.query(model).filter(model.id == objid)[0]
+    except IndexError as e:
+        raise ValueError(objid) from e  # pragma: no cover
+    label = kwargs.pop("label", [None])[0] or entity.name
+    anchor = kwargs.pop("_anchor", [None])[0]
+    url = req.route_url(route, id=objid, _anchor=anchor, **kwargs)
+    md_str = f'<a class="{model.__tablename__.capitalize()}" href="{url}">{label}</a>'
+    return decorate(md_str) if decorate else md_str
+
+
+def render_ex(req: ClldRequest, objid: str, table: str, session, ids=None, **_) -> str:
+    """Render an IGT example."""
     if objid == "__all__":
         if ids:
             ex_strs = [
-                render_ex(req, mid, table, session, subexample=True) for mid in ids[0].split(",")
-            ]
+                render_ex(req, mid, table, session, subexample=True) for mid in ids[0].split(",")]
             return '\n\n'.join(ex_strs)
     return rendered_sentence(session.query(common.Sentence).filter(common.Sentence.id == objid)[0])
 
@@ -124,9 +137,8 @@ def markdown(req, s: str, session=None) -> str:
     """
     if __name__ not in req.registry.settings:  # pragma: no cover
         raise KeyError(
-            '{} must be included in the app config to use the "markdown" function.'.format(
-                __name__))
-    settings = req.registry.settings[__name__]
+            f'{__name__} must be included in the app config to use the "markdown" function.')
+    settings_ = req.registry.settings[__name__]
     source_ids = set()
 
     def repl(ml):
@@ -138,17 +150,19 @@ def markdown(req, s: str, session=None) -> str:
         if ml.is_cldf_link:
             try:
                 table = ml.table_or_fname
-                if table in settings['renderer_map'] and "as_link" not in ml.parsed_url_query:
-                    return settings['renderer_map'][table](
+                if table in settings_['renderer_map'] and "as_link" not in ml.parsed_url_query:
+                    return settings_['renderer_map'][table](
                         req, ml.objid, table, session or DBSession, **ml.parsed_url_query)
-                elif table in settings['model_map']:
-                    decorate = settings['model_map'][table].get("decorate", None)
-                    kw = {k: v for k, v in ml.parsed_url_query.items()}
+                if table in settings_['model_map']:
+                    decorate = settings_['model_map'][table].get("decorate", None)
+                    kw = dict(ml.parsed_url_query.items())
+                    if ml.label and settings_['keep_link_labels']:
+                        kw.setdefault('label', [ml.label])
                     if table == 'Source':
                         if ml.objid != '__all__':
                             source_ids.add(ml.objid)
                         elif 'cited_only' in ml.parsed_url.query:
-                            model = settings['model_map'][table]["model"]
+                            model = settings_['model_map'][table]["model"]
                             return HTML.ul(*[
                                 HTML.li(literal(ref(
                                     (session or DBSession).query(model).filter(model.id == sid)[0]
@@ -157,16 +171,16 @@ def markdown(req, s: str, session=None) -> str:
                     return link_entity(
                         req,
                         ml.objid,
-                        settings['model_map'][table]["route"],
-                        settings['model_map'][table]["model"],
+                        settings_['model_map'][table]["route"],
+                        settings_['model_map'][table]["model"],
                         session or DBSession,
                         decorate=decorate,
                         **kw,
                     )
-                log.error(f"Can't handle [{ml.objid}] ({table}).")
+                log.error("Can't handle [%s] (%s).", ml.objid, table)
                 return f"{table}:{ml.objid}"
-            except:  # noqa: E722
+            except:  # noqa: E722  # pylint: disable=W0702
                 return ml.label
         return ml
 
-    return Markdown(extensions=settings["extensions"]).convert(CLDFMarkdownLink.replace(s, repl))
+    return Markdown(extensions=settings_["extensions"]).convert(CLDFMarkdownLink.replace(s, repl))

{clld_markdown_plugin-0.4.0 → clld_markdown_plugin-1.0.0}/src/clld_markdown_plugin.egg-info/PKG-INFO

@@ -1,29 +1,43 @@
 Metadata-Version: 2.1
-Name: clld-markdown-plugin
-Version: 0.4.0
+Name: clld_markdown_plugin
+Version: 1.0.0
 Summary: Render CLDF markdown in clld apps.
 Home-page: https://github.com/clld/clld-markdown-plugin
 Author: Robert Forkel, Florian Matter
 Author-email: robert_forkel@eva.mpg.de, florianmatter@gmail.com
 Project-URL: Bug Tracker, https://github.com/clld/clld-markdown-plugin/issues
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: frontmatter<1.2; python_version < "3.10"
+Requires-Dist: clldutils
+Requires-Dist: pycldf
+Requires-Dist: clld
+Requires-Dist: markdown
 Provides-Extra: dev
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: build; extra == "dev"
 Provides-Extra: test
-License-File: LICENSE
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: tox; extra == "test"
 
 # clld-markdown-plugin
 
-Render CLDF markdown in clld apps
+Render [CLDF markdown](https://github.com/cldf/cldf/blob/master/extensions/markdown.md) in clld apps
 
 ## Usage
 
@@ -47,8 +61,25 @@ Then you can use `clld_markdown_plugin.markup` as follows in your templates:
 ${markdown(req, '[x](LanguageTable#cldf:abad1241)')|n}
 ```
 
+By default, links to objects in the CLDF dataset will be rendered as HTML links to the corresponding
+object's details page in the clld app.
+
+
+### Configuration
+
+The plugin can be configured via the following four configuration options:
+
+- `model_map`: A `dict` mapping CLDF component names to DB model classes defined for the app. This
+  allows for a flexible mapping between CLDF components and the clld DB classes.
+- `renderer_map`: See below for details.
+- `extensions`: A list of [markdown extensions](https://python-markdown.github.io/extensions/#officially-supported-extensions)
+  in dot notation, to be activated when calling the `markdown` function.
+- `keep_link_labels`: A `boolean` indicating whether to keep link labels as they appear in the
+  CLDF Markdown text. By default (`False`), labels will be substituted using the linked object's
+  name.
+
 
-### Renderer callables
+#### Renderer callables
 
 The `renderer_map` configuration option for `clld_markdown_plugin` accepts a `dict` mapping
 CLDF component names to Python callables with the following signature:

{clld_markdown_plugin-0.4.0 → clld_markdown_plugin-1.0.0}/src/clld_markdown_plugin.egg-info/requires.txt

@@ -3,6 +3,9 @@ pycldf
 clld
 markdown
 
+[:python_version < "3.10"]
+frontmatter<1.2
+
 [dev]
 flake8
 twine

{clld_markdown_plugin-0.4.0 → clld_markdown_plugin-1.0.0}/tests/test_unit.py

@@ -29,3 +29,10 @@ def test_markdown(model_map, renderer_map, md, substring, notsubstring, dbsessio
     assert substring in res
     if notsubstring:
         assert notsubstring not in res
+
+
+def test_markdown_keep_labels(dbsession, req_factory):
+    res = markdown(req_factory(), '[xyz](LanguageTable#cldf:l1)')
+    assert 'xyz' not in res
+    res = markdown(req_factory(dict(keep_link_labels=True)), '[xyz](LanguageTable#cldf:l1)')
+    assert 'xyz' in res