pycldf.ext.markdown

This module provides tools to build a CLDF Markdown renderer.

For an example, see FilenameToComponent.

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:

pycldf.orm.Object

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

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:
  • textstr containing the markdown text (with YAML frontmatter removed).

  • metadatadict of document metadata read from YAML frontmatter.

  • dataset_mappingDatasetMapping 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)[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:

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)[source]

A markdown string with CLDF Markdown links replaced.

Parameters:
  • simple_link_detection (bool) –

  • markdown_kw (typing.Optional[dict]) –

Return type:

str

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

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