Source code for esmvalcore.experimental.recipe_metadata

"""API for recipe metadata."""

from typing import Optional

import pybtex
from pybtex.database.input import bibtex

from esmvalcore.config._diagnostics import DIAGNOSTICS, TAGS




class RenderError(BaseException):
    """Error during rendering of object."""





class Contributor:
    """Contains contributor (author or maintainer) information.

    Parameters
    ----------
    name : str
        Name of the author, i.e. ``'John Doe'``
    institute : str
        Name of the institute
    orcid : str, optional
        ORCID url
    """

    def __init__(self, name: str, institute: str, orcid: Optional[str] = None):
        self.name = name
        self.institute = institute
        self.orcid = orcid

    def __repr__(self) -> str:
        """Return canonical string representation."""
        return (f'{self.__class__.__name__}({self.name!r},'
                f' institute={self.institute!r}, orcid={self.orcid!r})')

    def __str__(self) -> str:
        """Return string representation."""
        string = f'{self.name} ({self.institute}'
        if self.orcid:
            string += f'; {self.orcid}'
        string += ')'
        return string

    def _repr_markdown_(self) -> str:
        """Represent using markdown renderer in a notebook environment."""
        return str(self)



    @classmethod
    def from_tag(cls, tag: str) -> 'Contributor':
        """Return an instance of Contributor from a tag (``TAGS``).

        Parameters
        ----------
        tag : str
            The contributor tags are defined in the authors section in
            ``config-references.yml``.
        """
        mapping = TAGS.get_tag_value(section='authors', tag=tag)

        name = ' '.join(reversed(mapping['name'].split(', ')))
        institute = mapping.get('institute', 'No affiliation')
        orcid = mapping['orcid']

        return cls(name=name, institute=institute, orcid=orcid)




    @classmethod
    def from_dict(cls, attributes):
        """Return an instance of Contributor from a dictionary.

        Parameters
        ----------
        attributes : dict
            Dictionary containing name / institute [/ orcid].
        """
        name = attributes['name']
        institute = attributes['institute']
        orcid = attributes.get('orcid', None)
        return cls(name=name, institute=institute, orcid=orcid)






class Project:
    """Use this class to acknowledge a project associated with the recipe.

    Parameters
    ----------
    project : str
        The project title.
    """

    def __init__(self, project: str):
        self.project = project

    def __repr__(self) -> str:
        """Return canonical string representation."""
        return f'{self.__class__.__name__}({self.project!r})'

    def __str__(self) -> str:
        """Return string representation."""
        string = f'{self.project}'
        return string



    @classmethod
    def from_tag(cls, tag: str) -> 'Project':
        """Return an instance of Project from a tag (``TAGS``).

        Parameters
        ----------
        tag : str
            The project tags are defined in ``config-references.yml``.
        """
        project = TAGS['projects'][tag]
        return cls(project=project)






class Reference:
    """Parse reference information from bibtex entries.

    Parameters
    ----------
    filename : str
        Name of the bibtex file.

    Raises
    ------
    NotImplementedError
        If the bibtex file contains more than 1 entry.
    """

    def __init__(self, filename: str):
        parser = bibtex.Parser(strict=False)
        bib_data = parser.parse_file(filename)

        if len(bib_data.entries) > 1:
            raise NotImplementedError(
                f'{self.__class__.__name__} cannot handle bibtex files '
                'with more than 1 entry.')

        self._bib_data = bib_data
        self._key, self._entry = list(bib_data.entries.items())[0]
        self._filename = filename



    @classmethod
    def from_tag(cls, tag: str) -> 'Reference':
        """Return an instance of Reference from a bibtex tag.

        Parameters
        ----------
        tag : str
            The bibtex tags resolved as ``esmvaltool/references/{tag}.bibtex``
            or the corresponding directory as defined by the diagnostics path.
        """
        filename = DIAGNOSTICS.references / f'{tag}.bibtex'
        return cls(filename)


    def __repr__(self) -> str:
        """Return canonical string representation."""
        return f'{self.__class__.__name__}({self._key!r})'

    def __str__(self) -> str:
        """Return string representation."""
        return self.render(renderer='plaintext')

    def _repr_html_(self) -> str:
        """Represent using markdown renderer in a notebook environment."""
        return self.render(renderer='html')



    def render(self, renderer: str = 'html') -> str:
        """Render the reference.

        Parameters
        ----------
        renderer : str
            Choose the renderer for the string representation.
            Must be one of: 'plaintext', 'markdown', 'html', 'latex'

        Returns
        -------
        str
            Rendered reference
        """
        style = 'plain'  # alpha, plain, unsrt, unsrtalpha
        backend = pybtex.plugin.find_plugin('pybtex.backends', renderer)()
        formatter = pybtex.plugin.find_plugin('pybtex.style.formatting',
                                              style)()

        try:
            formatter = formatter.format_entry(self._key, self._entry)
            rendered = formatter.text.render(backend)
        except Exception as err:
            raise RenderError(
                f'Could not render {self._key!r}: {err}') from None

        return rendered