55from paths_cli .wizard .parameters import WizardParameter
66from 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
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
2528class 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
4360def 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
236253class 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
265308class 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
0 commit comments