15781332075

Committed 20 Jun 2025 02:34PM UTC coverage: 93.094% (+0.02%) from 93.078%

Build # 15781332075

Build Type

Pull #563

github

Committed by

web-flow

Commit Message

Merge c7dcfcfb4 into a59202ce2

Pull Request Pull Request #563: Add parameter deprecation guide

Run Details

2925 of 3142 relevant lines covered (93.09%)

2.79 hits per line

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

95.45

/janus_core/cli/types.py

"""Module containing types used for Janus-Core CLI."""

from __future__ import annotations

import ast
from pathlib import Path
from typing import TYPE_CHECKING, Annotated, get_args

from click import Choice
from typer import Option

from janus_core.cli.utils import deprecated_option
from janus_core.helpers.janus_types import Architectures, Devices

if TYPE_CHECKING:
    from janus_core.helpers.janus_types import ASEReadArgs


def parse_dict_class(value: str | ASEReadArgs) -> TyperDict:
    """
    Convert string input into a dictionary.

    Parameters
    ----------
    value
        String representing dictionary to be parsed.

    Returns
    -------
    TyperDict
        Parsed string as a dictionary.
    """
    if isinstance(value, dict):
        return TyperDict(value)
    return TyperDict(ast.literal_eval(value))


class TyperDict:
    """
    Custom dictionary for typer.

    Parameters
    ----------
    value
        Value of string representing a dictionary.
    """

    def __init__(self, value: str) -> None:
        """
        Initialise class.

        Parameters
        ----------
        value
            Value of string representing a dictionary.
        """
        self.value = value

    def __str__(self) -> str:
        """
        Return string representation of class.

        Returns
        -------
        str
            Class name and value of string representing a dictionary.
        """
        return f"<TyperDict: value={self.value}>"


StructPath = Annotated[
    Path,
    Option(
        help="Path of structure to simulate.",
        show_default=False,
        rich_help_panel="Calculation",
    ),
]

Architecture = Annotated[
    str | None,
    Option(
        click_type=Choice(get_args(Architectures)),
        help="MLIP architecture to use for calculations.",
        rich_help_panel="MLIP calculator",
        show_default=False,
    ),
]
Device = Annotated[
    str | None,
    Option(
        click_type=Choice(get_args(Devices)),
        help="Device to run calculations on.",
        rich_help_panel="MLIP calculator",
    ),
]
Model = Annotated[
    str | None,
    Option(
        help="MLIP model name, or path to model.", rich_help_panel="MLIP calculator"
    ),
]
ModelPath = Annotated[
    str | None,
    Option(
        help="Deprecated. Please use --model",
        rich_help_panel="MLIP calculator",
        callback=deprecated_option,
        hidden=True,
    ),
]

FilePrefix = Annotated[
    Path | None,
    Option(
        help=(
            """
                Prefix for output files, including directories. Default directory is
                ./janus_results, and default filename prefix is inferred from the
                input stucture filename.
                """
        ),
        rich_help_panel="Structure I/O",
    ),
]

ReadKwargsAll = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to ase.io.read. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}". By default,
            read_kwargs['index'] = ':', so all structures are read.
            """
        ),
        metavar="DICT",
        rich_help_panel="Structure I/O",
    ),
]

ReadKwargsLast = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to ase.io.read. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}". By default,
            read_kwargs['index'] = -1, so only the last structure is read.
            """
        ),
        metavar="DICT",
        rich_help_panel="Structure I/O",
    ),
]

CalcKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to selected calculator. Must be passed as a
            dictionary wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="MLIP calculator",
    ),
]

WriteKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to ase.io.write when saving any structures. Must
            be passed as a dictionary wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Structure I/O",
    ),
]

MinimizeKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to optimizer. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

DoSKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to `run_total_dos`. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key' : value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="DOS",
    ),
]

PDoSKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to `run_projected_dos`. Must be passed as a
            dictionary wrapped in quotes, e.g. "{'key' : value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="PDOS",
    ),
]

EnsembleKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to ensemble initialization. Must be passed as a
            dictionary wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Ensemble configuration",
    ),
]

DisplacementKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to generate_displacements. Must be passed as a
            dictionary wrapped in quotes, e.g. "{'key' : value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

PostProcessKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to post-processer. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

NebKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to neb_method. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

NebOptKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to neb_optimizer. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

InterpolationKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to interpolator. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

PostProcessKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to post-processer. Must be passed as a dictionary
            wrapped in quotes, e.g. "{'key': value}".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

CorrelationKwargs = Annotated[
    TyperDict | None,
    Option(
        parser=parse_dict_class,
        help=(
            """
            Keyword arguments to pass to md for on-the-fly correlations. Must be
            passed as a list of dictionaries wrapped in quotes, e.g.
            "[{'key' : values}]".
            """
        ),
        metavar="DICT",
        rich_help_panel="Calculation",
    ),
]

LogPath = Annotated[
    Path | None,
    Option(
        help="Path to save logs to. Default is inferred from `file_prefix`",
        rich_help_panel="Logging/summary",
    ),
]

Tracker = Annotated[
    bool,
    Option(
        help="Whether to save carbon emissions of calculation",
        rich_help_panel="Logging/summary",
    ),
]

Summary = Annotated[
    Path | None,
    Option(
        help=(
            "Path to save summary of inputs, start/end time, and carbon emissions. "
            "Default is inferred from `file_prefix`."
        ),
        rich_help_panel="Logging/summary",
    ),
]

ProgressBar = Annotated[
    bool,
    Option(help="Whether to show progress bar.", rich_help_panel="Logging/summary"),
]

1	"""Module containing types used for Janus-Core CLI."""
2
3	from __future__ import annotations	3✔
4
5	import ast	3✔
6	from pathlib import Path	3✔
7	from typing import TYPE_CHECKING, Annotated, get_args	3✔
8
9	from click import Choice	3✔
10	from typer import Option	3✔
11
12	from janus_core.cli.utils import deprecated_option	3✔
13	from janus_core.helpers.janus_types import Architectures, Devices	3✔
14
15	if TYPE_CHECKING:	3✔
16	from janus_core.helpers.janus_types import ASEReadArgs	×
17
18
19	def parse_dict_class(value: str \| ASEReadArgs) -> TyperDict:	3✔
20	"""
21	Convert string input into a dictionary.
22
23	Parameters
24	----------
25	value
26	String representing dictionary to be parsed.
27
28	Returns
29	-------
30	TyperDict
31	Parsed string as a dictionary.
32	"""
33	if isinstance(value, dict):	3✔
34	return TyperDict(value)	3✔
35	return TyperDict(ast.literal_eval(value))	3✔
36
37
38	class TyperDict:	3✔
39	"""
40	Custom dictionary for typer.
41
42	Parameters
43	----------
44	value
45	Value of string representing a dictionary.
46	"""
47
48	def __init__(self, value: str) -> None:	3✔
49	"""
50	Initialise class.
51
52	Parameters
53	----------
54	value
55	Value of string representing a dictionary.
56	"""
57	self.value = value	3✔
58
59	def __str__(self) -> str:	3✔
60	"""
61	Return string representation of class.
62
63	Returns
64	-------
65	str
66	Class name and value of string representing a dictionary.
67	"""
68	return f"<TyperDict: value={self.value}>"	×
69
70
71	StructPath = Annotated[	3✔
72	Path,
73	Option(
74	help="Path of structure to simulate.",
75	show_default=False,
76	rich_help_panel="Calculation",
77	),
78	]
79
80	Architecture = Annotated[	3✔
81	str \| None,
82	Option(
83	click_type=Choice(get_args(Architectures)),
84	help="MLIP architecture to use for calculations.",
85	rich_help_panel="MLIP calculator",
86	show_default=False,
87	),
88	]
89	Device = Annotated[	3✔
90	str \| None,
91	Option(
92	click_type=Choice(get_args(Devices)),
93	help="Device to run calculations on.",
94	rich_help_panel="MLIP calculator",
95	),
96	]
97	Model = Annotated[	3✔
98	str \| None,
99	Option(
100	help="MLIP model name, or path to model.", rich_help_panel="MLIP calculator"
101	),
102	]
103	ModelPath = Annotated[	3✔
104	str \| None,
105	Option(
106	help="Deprecated. Please use --model",
107	rich_help_panel="MLIP calculator",
108	callback=deprecated_option,
109	hidden=True,
110	),
111	]
112
113	FilePrefix = Annotated[	3✔
114	Path \| None,
115	Option(
116	help=(
117	"""
118	Prefix for output files, including directories. Default directory is
119	./janus_results, and default filename prefix is inferred from the
120	input stucture filename.
121	"""
122	),
123	rich_help_panel="Structure I/O",
124	),
125	]
126
127	ReadKwargsAll = Annotated[	3✔
128	TyperDict \| None,
129	Option(
130	parser=parse_dict_class,
131	help=(
132	"""
133	Keyword arguments to pass to ase.io.read. Must be passed as a dictionary
134	wrapped in quotes, e.g. "{'key': value}". By default,
135	read_kwargs['index'] = ':', so all structures are read.
136	"""
137	),
138	metavar="DICT",
139	rich_help_panel="Structure I/O",
140	),
141	]
142
143	ReadKwargsLast = Annotated[	3✔
144	TyperDict \| None,
145	Option(
146	parser=parse_dict_class,
147	help=(
148	"""
149	Keyword arguments to pass to ase.io.read. Must be passed as a dictionary
150	wrapped in quotes, e.g. "{'key': value}". By default,
151	read_kwargs['index'] = -1, so only the last structure is read.
152	"""
153	),
154	metavar="DICT",
155	rich_help_panel="Structure I/O",
156	),
157	]
158
159	CalcKwargs = Annotated[	3✔
160	TyperDict \| None,
161	Option(
162	parser=parse_dict_class,
163	help=(
164	"""
165	Keyword arguments to pass to selected calculator. Must be passed as a
166	dictionary wrapped in quotes, e.g. "{'key': value}".
167	"""
168	),
169	metavar="DICT",
170	rich_help_panel="MLIP calculator",
171	),
172	]
173
174	WriteKwargs = Annotated[	3✔
175	TyperDict \| None,
176	Option(
177	parser=parse_dict_class,
178	help=(
179	"""
180	Keyword arguments to pass to ase.io.write when saving any structures. Must
181	be passed as a dictionary wrapped in quotes, e.g. "{'key': value}".
182	"""
183	),
184	metavar="DICT",
185	rich_help_panel="Structure I/O",
186	),
187	]
188
189	MinimizeKwargs = Annotated[	3✔
190	TyperDict \| None,
191	Option(
192	parser=parse_dict_class,
193	help=(
194	"""
195	Keyword arguments to pass to optimizer. Must be passed as a dictionary
196	wrapped in quotes, e.g. "{'key': value}".
197	"""
198	),
199	metavar="DICT",
200	rich_help_panel="Calculation",
201	),
202	]
203
204	DoSKwargs = Annotated[	3✔
205	TyperDict \| None,
206	Option(
207	parser=parse_dict_class,
208	help=(
209	"""
210	Keyword arguments to pass to `run_total_dos`. Must be passed as a dictionary
211	wrapped in quotes, e.g. "{'key' : value}".
212	"""
213	),
214	metavar="DICT",
215	rich_help_panel="DOS",
216	),
217	]
218
219	PDoSKwargs = Annotated[	3✔
220	TyperDict \| None,
221	Option(
222	parser=parse_dict_class,
223	help=(
224	"""
225	Keyword arguments to pass to `run_projected_dos`. Must be passed as a
226	dictionary wrapped in quotes, e.g. "{'key' : value}".
227	"""
228	),
229	metavar="DICT",
230	rich_help_panel="PDOS",
231	),
232	]
233
234	EnsembleKwargs = Annotated[	3✔
235	TyperDict \| None,
236	Option(
237	parser=parse_dict_class,
238	help=(
239	"""
240	Keyword arguments to pass to ensemble initialization. Must be passed as a
241	dictionary wrapped in quotes, e.g. "{'key': value}".
242	"""
243	),
244	metavar="DICT",
245	rich_help_panel="Ensemble configuration",
246	),
247	]
248
249	DisplacementKwargs = Annotated[	3✔
250	TyperDict \| None,
251	Option(
252	parser=parse_dict_class,
253	help=(
254	"""
255	Keyword arguments to pass to generate_displacements. Must be passed as a
256	dictionary wrapped in quotes, e.g. "{'key' : value}".
257	"""
258	),
259	metavar="DICT",
260	rich_help_panel="Calculation",
261	),
262	]
263
264	PostProcessKwargs = Annotated[	3✔
265	TyperDict \| None,
266	Option(
267	parser=parse_dict_class,
268	help=(
269	"""
270	Keyword arguments to pass to post-processer. Must be passed as a dictionary
271	wrapped in quotes, e.g. "{'key': value}".
272	"""
273	),
274	metavar="DICT",
275	rich_help_panel="Calculation",
276	),
277	]
278
279	NebKwargs = Annotated[	3✔
280	TyperDict \| None,
281	Option(
282	parser=parse_dict_class,
283	help=(
284	"""
285	Keyword arguments to pass to neb_method. Must be passed as a dictionary
286	wrapped in quotes, e.g. "{'key': value}".
287	"""
288	),
289	metavar="DICT",
290	rich_help_panel="Calculation",
291	),
292	]
293
294	NebOptKwargs = Annotated[	3✔
295	TyperDict \| None,
296	Option(
297	parser=parse_dict_class,
298	help=(
299	"""
300	Keyword arguments to pass to neb_optimizer. Must be passed as a dictionary
301	wrapped in quotes, e.g. "{'key': value}".
302	"""
303	),
304	metavar="DICT",
305	rich_help_panel="Calculation",
306	),
307	]
308
309	InterpolationKwargs = Annotated[	3✔
310	TyperDict \| None,
311	Option(
312	parser=parse_dict_class,
313	help=(
314	"""
315	Keyword arguments to pass to interpolator. Must be passed as a dictionary
316	wrapped in quotes, e.g. "{'key': value}".
317	"""
318	),
319	metavar="DICT",
320	rich_help_panel="Calculation",
321	),
322	]
323
324	PostProcessKwargs = Annotated[	3✔
325	TyperDict \| None,
326	Option(
327	parser=parse_dict_class,
328	help=(
329	"""
330	Keyword arguments to pass to post-processer. Must be passed as a dictionary
331	wrapped in quotes, e.g. "{'key': value}".
332	"""
333	),
334	metavar="DICT",
335	rich_help_panel="Calculation",
336	),
337	]
338
339	CorrelationKwargs = Annotated[	3✔
340	TyperDict \| None,
341	Option(
342	parser=parse_dict_class,
343	help=(
344	"""
345	Keyword arguments to pass to md for on-the-fly correlations. Must be
346	passed as a list of dictionaries wrapped in quotes, e.g.
347	"[{'key' : values}]".
348	"""
349	),
350	metavar="DICT",
351	rich_help_panel="Calculation",
352	),
353	]
354
355	LogPath = Annotated[	3✔
356	Path \| None,
357	Option(
358	help="Path to save logs to. Default is inferred from `file_prefix`",
359	rich_help_panel="Logging/summary",
360	),
361	]
362
363	Tracker = Annotated[	3✔
364	bool,
365	Option(
366	help="Whether to save carbon emissions of calculation",
367	rich_help_panel="Logging/summary",
368	),
369	]
370
371	Summary = Annotated[	3✔
372	Path \| None,
373	Option(
374	help=(
375	"Path to save summary of inputs, start/end time, and carbon emissions. "
376	"Default is inferred from `file_prefix`."
377	),
378	rich_help_panel="Logging/summary",
379	),
380	]
381
382	ProgressBar = Annotated[	3✔
383	bool,
384	Option(help="Whether to show progress bar.", rich_help_panel="Logging/summary"),
385	]

stfc / janus-core / 15781332075

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