markdown_api

trestle.core.markdown.markdown_api

A markdown API.

Attributes

logger = logging.getLogger(__name__) module-attribute

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) -> None:
        """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,
        governed_section: Optional[str] = None,
        validate_template: bool = False
    ) -> None:
        """Load and initialize markdown validator."""
        try:
            self.processor.governed_header = governed_section
            if validate_template:
                template_header, template_tree = self.processor.process_markdown(md_template_path, validate_yaml_header,
                                                                                 validate_md_body or governed_section is
                                                                                 not None)
            else:
                template_header, template_tree = self.processor.process_markdown(md_template_path)

            if not template_header 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,
                governed_section
            )
        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}')

Attributes

processor = MarkdownProcessor() instance-attribute

validator = None instance-attribute

Functions

__init__()

Initialize markdown API.

Source code in trestle/core/markdown/markdown_api.py

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

load_validator_with_template(md_template_path, validate_yaml_header, validate_md_body, governed_section=None, validate_template=False)

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,
    governed_section: Optional[str] = None,
    validate_template: bool = False
) -> None:
    """Load and initialize markdown validator."""
    try:
        self.processor.governed_header = governed_section
        if validate_template:
            template_header, template_tree = self.processor.process_markdown(md_template_path, validate_yaml_header,
                                                                             validate_md_body or governed_section is
                                                                             not None)
        else:
            template_header, template_tree = self.processor.process_markdown(md_template_path)

        if not template_header 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,
            governed_section
        )
    except TrestleError as e:
        raise TrestleError(f'Error while loading markdown template {md_template_path}: {e}.')

validate_instance(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(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