pycldf.ext.markdown
This module provides tools to build a CLDF Markdown renderer.
For an example, see FilenameToComponent
.
- class pycldf.ext.markdown.CLDFMarkdownLink(label, url)[source]
CLDF Markdown links are specified using URLs of a particular format.
Instances of CLDFMarkdownLink are supplied as sole argument when calling the replacement function passed to CLDFMarkdownLink.replace .
- property all: bool
Flag signaling whether the link is referencing the special __all__ identifier.
- component(cldf=None)[source]
- Parameters:
cldf (
typing.Union
[pycldf.dataset.Dataset
,typing.Dict
[str
,pycldf.dataset.Dataset
],pycldf.ext.markdown.DatasetMapping
,None
]) – pycldf.Dataset instance to which the link refers.- Return type:
typing.Optional
[str
]- Returns:
Name of the CLDF component the link pertains to or None.
- get_object(cldf)[source]
Resolve the reference in a CLDF Markdown link to an ORM object in the CLDF Dataset.
- Parameters:
cldf (
typing.Union
[pycldf.dataset.Dataset
,pycldf.ext.markdown.DatasetMapping
]) –- Return type:
- get_row(cldf)[source]
Resolve the reference in a CLDF Markdown link to a row (dict) in the CLDF Dataset.
- Parameters:
cldf (
typing.Union
[pycldf.dataset.Dataset
,pycldf.ext.markdown.DatasetMapping
]) –- Return type:
dict
- property is_cldf_link: bool
Flag signaling whether the markdown link is indeed referencing a CLDF object.
- property objid: None | str
The identifier of the object referenced by a CLDF Markdown link.
- property prefix: None | str
The dataset prefix associated with a CLDF Markdown link.
- property table_or_fname: None | str
The last path component of the URL of a CLDF Markdown link.
- class pycldf.ext.markdown.CLDFMarkdownText(text, dataset_mapping=None, download_dir=None)[source]
A CLDF Markdown document.
Basic CLDF Markdown rendering can be implemented by overwriting the render_link method. Then, calling the render method will return a markdown string with CLDF Markdown links replaced.
A trivial renderer, replacing each CLDF Markdown link with the link label, would look as follows:
from pycldf.ext.markdown import CLDFMarkdownText class Renderer(CLDFMarkdownText): def render_link(self, link): return str(link.label) assert Renderer('[Example 1](ExampleTable#cldf:ex1)').render() == 'Example 1'
- Variables:
text – str containing the markdown text (with YAML frontmatter removed).
metadata – dict of document metadata read from YAML frontmatter.
dataset_mapping –
DatasetMapping
instance, linking prefixes used in CLDF Markdown links topycldf.Dataset
instances.source_component – Name of the special “Source” component.
metadata_component – Name of the special “Metadata” component.
- Parameters:
text (
typing.Union
[pathlib.Path
,str
]) –dataset_mapping (
typing.Union
[str
,pycldf.dataset.Dataset
,dict
,None
]) –download_dir (
typing.Optional
[pathlib.Path
]) –
- property frontmatter: str
The markdown documents metadata formatted as YAML frontmatter.
- get_object(ml)[source]
Resolve the reference in a CLDF Markdown link to the matching object from a mapped dataset.
The returned object is
an
pycldf.orm.Object
instance for items in ORM mapped components,a row dict for items in custom tables,
a
pycldf.sources.Source
instance for source references,a list of the above for the special __all__ identifier.
a jmespath.search result for referenced items in the Metadata component,
This method can be used within
render_link()
implementations.- Parameters:
- Return type:
typing.Union
[list
,pycldf.orm.Object
,pycldf.sources.Source
,dict
]
- render(simple_link_detection=True, markdown_kw=None)[source]
A markdown string with CLDF Markdown links replaced.
- Parameters:
simple_link_detection (
bool
) –markdown_kw (
typing.Optional
[dict
]) –
- Return type:
str
- render_link(cldf_link)[source]
CLDF Markdown renderers must implement this method.
- Parameters:
cldf_link (
pycldf.ext.markdown.CLDFMarkdownLink
) –- Return type:
typing.Union
[str
,pycldf.ext.markdown.CLDFMarkdownLink
]
- class pycldf.ext.markdown.FilenameToComponent(text, dataset_mapping=None, download_dir=None)[source]
Renderer to replace filenames in CLDF Markdown links with CLDF component names.
- Parameters:
text (
typing.Union
[pathlib.Path
,str
]) –dataset_mapping (
typing.Union
[str
,pycldf.dataset.Dataset
,dict
,None
]) –download_dir (
typing.Optional
[pathlib.Path
]) –