Skip to content

markdown_api

trestle.core.markdown.markdown_api ¤

A markdown API.

logger ¤

Classes¤

MarkdownAPI ¤

A common API that wraps around the existing markdown functionality.

Source code in trestle/core/markdown/markdown_api.py
class MarkdownAPI:
    """A common API that wraps around the existing markdown functionality."""

    def __init__(self):
        """Initialize markdown API."""
        self.processor = MarkdownProcessor()
        self.validator = None

    def load_validator_with_template(
        self,
        md_template_path: pathlib.Path,
        validate_yaml_header: bool,
        validate_md_body: bool,
        md_header_to_validate: Optional[str] = None
    ) -> None:
        """Load and initialize markdown validator."""
        try:
            self.processor.governed_header = md_header_to_validate
            template_header, template_tree = self.processor.process_markdown(md_template_path)

            if len(template_header) == 0 and validate_yaml_header:
                raise TrestleError(f'Expected yaml header for markdown template where none exists {md_template_path}')

            self.validator = MarkdownValidator(
                md_template_path,
                template_header,
                template_tree,
                validate_yaml_header,
                validate_md_body,
                md_header_to_validate
            )
        except TrestleError as e:
            raise TrestleError(f'Error while loading markdown template {md_template_path}: {e}.')

    def validate_instance(self, md_instance_path: pathlib.Path) -> bool:
        """Validate a given markdown instance against a template."""
        if self.validator is None:
            raise TrestleError('Markdown validator is not initialized, load template first.')
        instance_header, instance_tree = self.processor.process_markdown(md_instance_path)
        return self.validator.is_valid_against_template(md_instance_path, instance_header, instance_tree)

    def write_markdown_with_header(self, path: pathlib.Path, header: Dict[str, str], md_body: str) -> None:
        """Write markdown with the YAML header."""
        try:
            # use encoding to handle character sets as well as possible
            with open(path, 'w', encoding=const.FILE_ENCODING, errors='replace') as md_file:
                md_file.write('---\n')
                yaml.safe_dump(header, md_file, sort_keys=False)
                md_file.write('---\n\n')
                md_file.write(md_body)
        except IOError as e:
            raise TrestleError(f'Error while writing markdown file: {e}')
Methods¤
__init__(self) special ¤

Initialize markdown API.

Source code in trestle/core/markdown/markdown_api.py
def __init__(self):
    """Initialize markdown API."""
    self.processor = MarkdownProcessor()
    self.validator = None
load_validator_with_template(self, md_template_path, validate_yaml_header, validate_md_body, md_header_to_validate=None) ¤

Load and initialize markdown validator.

Source code in trestle/core/markdown/markdown_api.py
def load_validator_with_template(
    self,
    md_template_path: pathlib.Path,
    validate_yaml_header: bool,
    validate_md_body: bool,
    md_header_to_validate: Optional[str] = None
) -> None:
    """Load and initialize markdown validator."""
    try:
        self.processor.governed_header = md_header_to_validate
        template_header, template_tree = self.processor.process_markdown(md_template_path)

        if len(template_header) == 0 and validate_yaml_header:
            raise TrestleError(f'Expected yaml header for markdown template where none exists {md_template_path}')

        self.validator = MarkdownValidator(
            md_template_path,
            template_header,
            template_tree,
            validate_yaml_header,
            validate_md_body,
            md_header_to_validate
        )
    except TrestleError as e:
        raise TrestleError(f'Error while loading markdown template {md_template_path}: {e}.')
validate_instance(self, md_instance_path) ¤

Validate a given markdown instance against a template.

Source code in trestle/core/markdown/markdown_api.py
def validate_instance(self, md_instance_path: pathlib.Path) -> bool:
    """Validate a given markdown instance against a template."""
    if self.validator is None:
        raise TrestleError('Markdown validator is not initialized, load template first.')
    instance_header, instance_tree = self.processor.process_markdown(md_instance_path)
    return self.validator.is_valid_against_template(md_instance_path, instance_header, instance_tree)
write_markdown_with_header(self, path, header, md_body) ¤

Write markdown with the YAML header.

Source code in trestle/core/markdown/markdown_api.py
def write_markdown_with_header(self, path: pathlib.Path, header: Dict[str, str], md_body: str) -> None:
    """Write markdown with the YAML header."""
    try:
        # use encoding to handle character sets as well as possible
        with open(path, 'w', encoding=const.FILE_ENCODING, errors='replace') as md_file:
            md_file.write('---\n')
            yaml.safe_dump(header, md_file, sort_keys=False)
            md_file.write('---\n\n')
            md_file.write(md_body)
    except IOError as e:
        raise TrestleError(f'Error while writing markdown file: {e}')

handler: python