Skip to content

Commit b898478

Browse files
committed
docstrings
1 parent a88a677 commit b898478

5 files changed

Lines changed: 169 additions & 28 deletions

File tree

‎paths_cli/tests/wizard/test_plugin_classes.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -280,7 +280,7 @@ def test_set_context(self, input_type):
280280
}[input_type]
281281
wrapper = WrapCategory("foo", "ask foo", set_context=set_context)
282282
wizard = mock_wizard([])
283-
context = wrapper.set_context(wizard, old_context, selected=None)
283+
context = wrapper._set_context(wizard, old_context, selected=None)
284284
assert context == expected
285285
if input_type == 'None':
286286
assert context is expected
@@ -308,7 +308,7 @@ def test_get_ask(self, input_type):
308308
context = {'bar': 10}
309309
wrapper = WrapCategory("foo", ask)
310310
wizard = mock_wizard([])
311-
ask_string = wrapper.get_ask(wizard, context)
311+
ask_string = wrapper._get_ask(wizard, context)
312312
assert ask_string == "Bar is 10"
313313

314314
@pytest.mark.parametrize('context_type', ['None', 'dict'])

‎paths_cli/wizard/plugin_classes.py‎

Lines changed: 107 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,13 @@
55
from paths_cli.wizard.parameters import WizardParameter
66
from paths_cli.wizard.helper import Helper
77

8+
_PLUGIN_DOCSTRING = """
9+
requires_ops : Tuple[int, int]
10+
version of OpenPathSampling required for this plugin
11+
requires_cli : Tuple[int, int]
12+
version of the OpenPathSampling CLI required for this plugin
13+
"""
14+
815
_WIZARD_KWONLY = """
916
prerequisite : Callable
1017
method to use to create any objects required for the target object
@@ -16,14 +23,22 @@
1623
summary : Callable
1724
method to create the summary string describing the object that is
1825
created
19-
requires_ops : Tuple[int, int]
20-
version of OpenPathSampling required for this plugin
21-
requires_cli : Tuple[int, int]
22-
version of the OpenPathSampling CLI required for this plugin
23-
"""
26+
""" + _PLUGIN_DOCSTRING
2427

2528
class LoadFromOPS(OPSPlugin):
26-
def __init__(self, category, obj_name=None, store_name=None,
29+
"""Wizard plugin type to load from an existing OPS file.
30+
31+
Parameters
32+
----------
33+
category : str
34+
the plugin category associated with this plugin
35+
obj_name : str
36+
name of the object (singular) for use in user interaction
37+
store_name : str
38+
nanme of the store within the OPS file where objects of this type
39+
can be found
40+
""" + _PLUGIN_DOCSTRING
41+
def __init__(self, category, *, obj_name=None, store_name=None,
2742
requires_ops=(1,0), requires_cli=(0,3)):
2843
super().__init__(requires_ops, requires_cli)
2944
self.category = category
@@ -36,8 +51,10 @@ def __init__(self, category, obj_name=None, store_name=None,
3651

3752
self.obj_name = obj_name
3853
self.store_name = store_name
54+
self.description = (f"Load the {self.obj_name} from an OPS .db "
55+
"file.")
3956

40-
def __call__(self, wizard):
57+
def __call__(self, wizard, context=None):
4158
return load_from_ops(wizard, self.store_name, self.obj_name)
4259

4360
def get_text_from_context(name, instance, default, wizard, context, *args,
@@ -56,7 +73,7 @@ def get_text_from_context(name, instance, default, wizard, context, *args,
5673
default :
5774
default value to use if neither context nor user-given values exist
5875
wizard : :class:`.Wizard`
59-
the wizard
76+
the wizard to use for user interaction
6077
context : dict
6178
the context dict
6279
"""
@@ -188,7 +205,7 @@ def __init__(self, name, category, parameters, builder, *,
188205
self.proxy_parameters = [] # non-empty if created from proxies
189206

190207
@classmethod
191-
def from_proxies(cls, name, category, parameters, compiler_plugin,
208+
def from_proxies(cls, name, category, parameters, compiler_plugin, *,
192209
prerequisite=None, intro=None, description=None,
193210
summary=None, requires_ops=(1,0), requires_cli=(0,3)):
194211
"""
@@ -234,13 +251,39 @@ def _build(self, wizard, prereqs):
234251

235252

236253
class CategoryHelpFunc:
254+
"""Help function for wizard category wrappers.
255+
256+
An instance of this is used as input to :class:`.Helper`.
257+
258+
Parameters
259+
----------
260+
category : :class:`.WrapCategory`
261+
the category wrapper for which this is the help function.
262+
basic_help : str
263+
help statement for the category as a whole
264+
"""
237265
def __init__(self, category, basic_help=None):
238266
self.category = category
239267
if basic_help is None:
240268
basic_help = f"Sorry, no help available for {category.name}."
241269
self.basic_help = basic_help
242270

243271
def __call__(self, help_args, context):
272+
"""Get help based on user input ``help_args`` and context.
273+
274+
Parameters
275+
----------
276+
help_args : str
277+
use input arguments to help function
278+
context : dict
279+
context dict
280+
281+
Returns
282+
-------
283+
str :
284+
help statement based on user input. Returns ``None`` if there
285+
was an error in the user input.
286+
"""
244287
if not help_args:
245288
return self.basic_help
246289
help_dict = {}
@@ -263,15 +306,35 @@ def __call__(self, help_args, context):
263306

264307

265308
class WrapCategory(OPSPlugin):
266-
def __init__(self, name, ask, helper=None, intro=None, set_context=None,
267-
requires_ops=(1,0), requires_cli=(0,3)):
309+
"""Container for plugins to organize them by "category."
310+
311+
A category here is a specific role within OPS. For example, engines make
312+
one category, volumes make another. Objects within a category are (in
313+
principle) interchangeable from a software standardpoint.
314+
315+
This is the Wizard equivalent of the CategoryCompiler in the compiling
316+
subpackage.
317+
318+
Parameters
319+
----------
320+
name : str
321+
Name of this category. This should be in the singular.
322+
ask : str or Callable[:class:`.Wizard`, dict] -> str
323+
string or callable to create string that for the question asked of
324+
the user when creating an object of this type
325+
helper : :class:`.Helper` or str
326+
helper tool
327+
328+
"""
329+
def __init__(self, name, ask, helper=None, *, intro=None,
330+
set_context=None, requires_ops=(1,0), requires_cli=(0,3)):
268331
super().__init__(requires_ops, requires_cli)
269332
self.name = name
270333
if isinstance(intro, str):
271334
intro = [intro]
272335
self.intro = intro
273336
self.ask = ask
274-
self._set_context = set_context
337+
self._user_set_context = set_context
275338
if helper is None:
276339
helper = Helper(CategoryHelpFunc(self))
277340
if isinstance(helper, str):
@@ -283,16 +346,25 @@ def __init__(self, name, ask, helper=None, intro=None, set_context=None,
283346
def __repr__(self):
284347
return f"{self.__class__.__name__}({self.name})"
285348

286-
def set_context(self, wizard, context, selected):
287-
if self._set_context:
288-
return self._set_context(wizard, context, selected)
349+
def _set_context(self, wizard, context, selected):
350+
"""If user has provided a funtion to create context, use it."""
351+
if self._user_set_context:
352+
return self._user_set_context(wizard, context, selected)
289353
else:
290354
return context
291355

292356
def register_plugin(self, plugin):
357+
"""Register a :class:`.WizardObjectPlugin` with this category.
358+
359+
Parameters
360+
----------
361+
plugin : :class:`.WizardObjectPlugin`
362+
the plugin to register
363+
"""
293364
self.choices[plugin.name] = plugin
294365

295-
def get_intro(self, wizard, context):
366+
def _get_intro(self, wizard, context):
367+
"""get the intro test to be said by the wizard"""
296368
return get_text_from_context(
297369
name='intro',
298370
instance=self.intro,
@@ -301,27 +373,42 @@ def get_intro(self, wizard, context):
301373
context=context
302374
)
303375

304-
def get_ask(self, wizard, context):
376+
def _get_ask(self, wizard, context):
377+
"""get the ask text to be said by the wizard"""
305378
try:
306379
ask = self.ask(wizard, context)
307380
except TypeError:
308381
ask = self.ask.format(**context)
309382
return ask
310383

311384
def __call__(self, wizard, context=None):
385+
"""Create an instance for this category.
386+
387+
Parameters
388+
----------
389+
wizard : :class:`.Wizard`
390+
the wizard to use for user interaction
391+
context : dict
392+
the context dict
393+
394+
Returns
395+
-------
396+
Any :
397+
instance of the type created by this category
398+
"""
312399
if context is None:
313400
context = {}
314401

315-
intro = self.get_intro(wizard, context)
402+
intro = self._get_intro(wizard, context)
316403

317404
for line in intro:
318405
wizard.say(line)
319406

320-
ask = self.get_ask(wizard, context)
407+
ask = self._get_ask(wizard, context)
321408

322409
selected = wizard.ask_enumerate_dict(ask, self.choices,
323410
self.helper)
324411

325-
new_context = self.set_context(wizard, context, selected)
412+
new_context = self._set_context(wizard, context, selected)
326413
obj = selected(wizard, new_context)
327414
return obj

‎paths_cli/wizard/plugin_registration.py‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
from collections import defaultdict
2-
31
from paths_cli.wizard.plugin_classes import (
42
LoadFromOPS, WizardObjectPlugin, WrapCategory
53
)
@@ -13,18 +11,34 @@ class CategoryWizardPluginRegistrationError(Exception):
1311
_CATEGORY_PLUGINS = {}
1412

1513
def get_category_wizard(category):
14+
"""Get the wizard category object of the given name.
15+
16+
This is the user-facing way to load the wizard category plugins after
17+
they have been registered.
18+
19+
Parameters
20+
----------
21+
category : str
22+
name of the category to load
23+
24+
Returns
25+
-------
26+
:class:`.WrapCategory` :
27+
wizard category plugin for the specified category
28+
"""
1629
def inner(wizard, context=None):
1730
try:
1831
plugin = _CATEGORY_PLUGINS[category]
19-
except KeyError:
32+
except KeyError as exc:
2033
raise CategoryWizardPluginRegistrationError(
2134
f"No wizard plugin for '{category}'"
22-
)
35+
) from exc
2336
return plugin(wizard, context)
2437
return inner
2538

2639

2740
def _register_category_plugin(plugin):
41+
"""convenience to register plugin or error if already registered"""
2842
if plugin.name in _CATEGORY_PLUGINS:
2943
raise CategoryWizardPluginRegistrationError(
3044
f"The category '{plugin.name}' has already been reserved "
@@ -34,6 +48,14 @@ def _register_category_plugin(plugin):
3448

3549

3650
def register_plugins(plugins):
51+
"""Register the given plugins for use with the wizard.
52+
53+
Parameters
54+
----------
55+
plugins : List[:class:`.OPSPlugin`]
56+
wizard plugins to register (including category plugins and object
57+
plugins)
58+
"""
3759
categories = []
3860
object_plugins = []
3961
for plugin in plugins:
@@ -53,6 +75,12 @@ def register_plugins(plugins):
5375
category.register_plugin(plugin)
5476

5577
def register_installed_plugins():
78+
"""Register all Wizard plugins found in standard locations.
79+
80+
This is a convenience to avoid repeating identification of wizard
81+
plugins. If something external needs to load all plugins (e.g., for
82+
testing or for a custom script), this is the method to use.
83+
"""
5684
plugin_types = (WrapCategory, WizardObjectPlugin)
5785
plugins = get_installed_plugins(
5886
default_loader=NamespacePluginLoader('paths_cli.wizard',
@@ -67,5 +95,3 @@ def register_installed_plugins():
6795
plugin_types=LoadFromOPS
6896
)
6997
register_plugins(file_loader_plugins)
70-
71-

‎paths_cli/wizard/run_module.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,16 @@
88
# If that functionality is retained, it might be good to find a way to test
99
# this.
1010
def run_category(category, requirements=None): # -no-cov-
11+
"""Run a wizard for the given category.
12+
13+
Parameters
14+
----------
15+
category : str
16+
name of the category wizard to run
17+
requirements : dict
18+
requirements for the :class:`.Wizard`. See :class:`.Wizard` for
19+
details on the format.
20+
"""
1121
# TODO: if we keep this, fix it up so that it also saves the resulting
1222
# objects
1323
register_installed_plugins()

‎paths_cli/wizard/standard_categories.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,24 @@
2424
CATEGORIES = {cat.name: cat for cat in _CATEGORY_LIST}
2525

2626
def get_category_info(category):
27+
"""Obtain info for a stanard (or registered) category.
28+
29+
This provides a convenience for mapping various string names, which is
30+
especially useful in user interactions. Each ``Category`` consists of:
31+
32+
* ``name``: the name used by the plugin infrastructure
33+
* ``singular``: the singular name of the type as it should appear in
34+
user interaction
35+
* ``plural``: the plural name of the type as it should appear in user
36+
interactions
37+
* ``storage``: the (pseudo)store name in OPS; used for loading object of
38+
this category type by name.
39+
40+
Parameters
41+
----------
42+
category : str
43+
the name of the category to load
44+
"""
2745
try:
2846
return CATEGORIES[category]
2947
except KeyError:

0 commit comments

Comments
 (0)