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, pattern=re.compile('(?<!!)(?<!\\\\\\\\)\\\\[(?P<label>.*?)(?<!\\\\\\\\)](\\\\((?P<url>[^)]+)\\\\))?'), html_link=('a', 'href'))

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 .

Parameters:

• label (str) –

• url (str) –

• pattern (re.Pattern) –

• html_link (tuple[str, str]) –

property all: bool

Flag signaling whether the link is referencing the special __all__ identifier.

component(cldf=None)

Parameters:

cldf (typing.Union[pycldf.dataset.Dataset, 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.

static format_url(path, objid, prefix=None)

Format the HREF value for a CLDF Markdown link.

Return type:

str

classmethod from_component(comp, objid='__all__', label=None, prefix=None)

Create a CLDF Markdown link for an object in a component.

Return type:

pycldf.ext.markdown.CLDFMarkdownLink

get_object(cldf)

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:

pycldf.orm.Object

get_row(cldf)

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: str | None

The identifier of the object referenced by a CLDF Markdown link.

property prefix: str | None

The dataset prefix associated with a CLDF Markdown link.

property table_or_fname: str | None

The last path component of the URL of a CLDF Markdown link.

property url_without_fragment: str

Return the HREF value of the link without the fragment.

class pycldf.ext.markdown.CLDFMarkdownText(text, dataset_mapping=None, download_dir=None)

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 to pycldf.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)

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:

ml (pycldf.ext.markdown.CLDFMarkdownLink) –

Return type:

typing.Union[list, pycldf.orm.Object, pycldf.sources.Source, dict]

render(simple_link_detection=True, markdown_kw=None)

A markdown string with CLDF Markdown links replaced.

Parameters:

• simple_link_detection (bool) –

• markdown_kw (typing.Optional[dict[str, typing.Any]]) –

Return type:

str

render_link(cldf_link)

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)

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]) –

render_link(cldf_link)

Rewrites to URL of CLDF Markdown links, using the component name as path component.

Parameters:

cldf_link (pycldf.ext.markdown.CLDFMarkdownLink) –

Return type:

pycldf.ext.markdown.CLDFMarkdownLink