11156641638

Committed 03 Oct 2024 05:56AM UTC coverage: 70.895% (-3.2%) from 74.084%

Build # 11156641638

Build Type

push

github

Run Details

2845 of 4013 relevant lines covered (70.89%)

0.71 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

83.78

/pymt/framework/bmi_docstring.py

import jinja2
from landlab.core.messages import format_message
from model_metadata import MetadataNotFoundError, ModelMetadata

# {{ desc|trim|wordwrap(70) if desc }}
_DOCSTRING = """
Basic Model Interface for {{ name }}.

{{ desc|trim if desc }}

{% if author -%}
Author:
{%- for name in author %}
{{"- " + name|trim }}{% endfor %}
{%- endif %}
Version: {{ version }}
License: {{ license }}
DOI: {{ doi }}
URL: {{ url }}

{% if cite_as -%}
Cite as:
{% for citation in cite_as %}
{{ citation|trim|indent(width=4, first=True) }}
{% endfor %}
{%- endif %}
{% if parameters %}
Parameters
----------
{% for param in parameters|sort(attribute='name') -%}
{{param.name}} : {{param.value.type}}, optional
    {{ "%s [default=%s %s]"|format(param.description, param.value.default, param.value.units)|trim|wordwrap(70)|indent(4) }}
{% endfor %}
{% endif -%}

Examples
--------
>>> from pymt.models import {{name}}
>>> model = {{name}}()
>>> (fname, initdir) = model.setup()
>>> model.initialize(fname, dir=initdir)  # doctest: +SKIP
>>> for _ in range(10):  # doctest: +SKIP
...     model.update()
>>> model.finalize()  # doctest: +SKIP
""".strip()


def bmi_docstring(
    plugin,
    author=None,
    version=None,
    license=None,  # pylint: disable=redefined-builtin
    doi=None,
    url=None,
    parameters=None,
    summary=None,
    cite_as=None,
    email=None,
):
    """Build the docstring for a BMI model.

    Parameters
    ----------
    name : str
        Name of a BMI component.
    author : str, optional
        Name of author or authors.
    version : str, optional
        Version string for the component.
    license : str, optional
        Name of the license of the component.
    doi : str, optional
        A DOI for the component.
    url : str, optional
        URL of the component's location on the internet.
    parameters : iterable, optional
        List of input parameters for the component. Each parameter object
        must have attributes for name, type, value, units, and desc.
    cite_as : iterable of str, optional
        List of citations for this component.
    email : str, optional
        Contact email address.

    Returns
    -------
    str
        The docstring.

    Examples
    --------
    >>> from pymt.framework.bmi_docstring import bmi_docstring
    >>> print(bmi_docstring('Model', author='Walt Disney')) #doctest: +ELLIPSIS
    Basic Model Interface for Model.
    ...
    """
    author = author or []
    cite_as = cite_as or []

    try:
        meta = ModelMetadata.from_obj(plugin)
        # meta = PluginMetadata(plugin)
    except MetadataNotFoundError:
        if isinstance(plugin, str):
            info = dict(
                authors=author,
                version=version,
                license=license,
                doi=doi,
                url=url,
                summary=summary,
                cite_as=cite_as,
            )
            defaults = {}
            name = plugin
        else:
            raise
    else:
        info = meta.info
        defaults = meta.parameters
        name = meta.api["class"]

    for param_name, param in defaults.items():
        param["name"] = param_name
    defaults = defaults.values()

    author = author or info["authors"]
    email = email or "-"
    version = version or info["version"]
    license = license or info["license"]
    doi = doi or info["doi"]
    url = url or info["url"]
    summary = summary or info["summary"]
    cite_as = cite_as or info["cite_as"]
    parameters = parameters or defaults

    if isinstance(author, str):
        author = [author]
    if isinstance(cite_as, str):
        cite_as = [cite_as]

    summary = format_message(summary)

    env = jinja2.Environment(  # nosec
        loader=jinja2.DictLoader({"docstring": _DOCSTRING})
    )
    return env.get_template("docstring").render(
        desc=summary,
        name=name,
        parameters=parameters,
        author=author,
        version=version,
        license=license,
        doi=doi,
        url=url,
        cite_as=cite_as,
    )

1	import jinja2	1✔
2	from landlab.core.messages import format_message	1✔
3	from model_metadata import MetadataNotFoundError, ModelMetadata	1✔
4
5	# {{ desc\|trim\|wordwrap(70) if desc }}
6	_DOCSTRING = """	1✔
7	Basic Model Interface for {{ name }}.
8
9	{{ desc\|trim if desc }}
10
11	{% if author -%}
12	Author:
13	{%- for name in author %}
14	{{"- " + name\|trim }}{% endfor %}
15	{%- endif %}
16	Version: {{ version }}
17	License: {{ license }}
18	DOI: {{ doi }}
19	URL: {{ url }}
20
21	{% if cite_as -%}
22	Cite as:
23	{% for citation in cite_as %}
24	{{ citation\|trim\|indent(width=4, first=True) }}
25	{% endfor %}
26	{%- endif %}
27	{% if parameters %}
28	Parameters
29	----------
30	{% for param in parameters\|sort(attribute='name') -%}
31	{{param.name}} : {{param.value.type}}, optional
32	{{ "%s [default=%s %s]"\|format(param.description, param.value.default, param.value.units)\|trim\|wordwrap(70)\|indent(4) }}
33	{% endfor %}
34	{% endif -%}
35
36	Examples
37	--------
38	>>> from pymt.models import {{name}}
39	>>> model = {{name}}()
40	>>> (fname, initdir) = model.setup()
41	>>> model.initialize(fname, dir=initdir) # doctest: +SKIP
42	>>> for _ in range(10): # doctest: +SKIP
43	... model.update()
44	>>> model.finalize() # doctest: +SKIP
45	""".strip()
46
47
48	def bmi_docstring(	1✔
49	plugin,
50	author=None,
51	version=None,
52	license=None, # pylint: disable=redefined-builtin
53	doi=None,
54	url=None,
55	parameters=None,
56	summary=None,
57	cite_as=None,
58	email=None,
59	):
60	"""Build the docstring for a BMI model.
61
62	Parameters
63	----------
64	name : str
65	Name of a BMI component.
66	author : str, optional
67	Name of author or authors.
68	version : str, optional
69	Version string for the component.
70	license : str, optional
71	Name of the license of the component.
72	doi : str, optional
73	A DOI for the component.
74	url : str, optional
75	URL of the component's location on the internet.
76	parameters : iterable, optional
77	List of input parameters for the component. Each parameter object
78	must have attributes for name, type, value, units, and desc.
79	cite_as : iterable of str, optional
80	List of citations for this component.
81	email : str, optional
82	Contact email address.
83
84	Returns
85	-------
86	str
87	The docstring.
88
89	Examples
90	--------
91	>>> from pymt.framework.bmi_docstring import bmi_docstring
92	>>> print(bmi_docstring('Model', author='Walt Disney')) #doctest: +ELLIPSIS
93	Basic Model Interface for Model.
94	...
95	"""
96	author = author or []	1✔
97	cite_as = cite_as or []	1✔
98
99	try:	1✔
100	meta = ModelMetadata.from_obj(plugin)	1✔
101	# meta = PluginMetadata(plugin)
102	except MetadataNotFoundError:	1✔
103	if isinstance(plugin, str):	1✔
104	info = dict(	1✔
105	authors=author,
106	version=version,
107	license=license,
108	doi=doi,
109	url=url,
110	summary=summary,
111	cite_as=cite_as,
112	)
113	defaults = {}	1✔
114	name = plugin	1✔
115	else:
116	raise	×
117	else:
118	info = meta.info	×
119	defaults = meta.parameters	×
120	name = meta.api["class"]	×
121
122	for param_name, param in defaults.items():	1✔
123	param["name"] = param_name	×
124	defaults = defaults.values()	1✔
125
126	author = author or info["authors"]	1✔
127	email = email or "-"	1✔
128	version = version or info["version"]	1✔
129	license = license or info["license"]	1✔
130	doi = doi or info["doi"]	1✔
131	url = url or info["url"]	1✔
132	summary = summary or info["summary"]	1✔
133	cite_as = cite_as or info["cite_as"]	1✔
134	parameters = parameters or defaults	1✔
135
136	if isinstance(author, str):	1✔
137	author = [author]	1✔
138	if isinstance(cite_as, str):	1✔
139	cite_as = [cite_as]	×
140
141	summary = format_message(summary)	1✔
142
143	env = jinja2.Environment( # nosec	1✔
144	loader=jinja2.DictLoader({"docstring": _DOCSTRING})
145	)
146	return env.get_template("docstring").render(	1✔
147	desc=summary,
148	name=name,
149	parameters=parameters,
150	author=author,
151	version=version,
152	license=license,
153	doi=doi,
154	url=url,
155	cite_as=cite_as,
156	)

csdms / pymt / 11156641638

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous