Skip to content

Commit a88a677

Browse files
committed
some docstrings
1 parent 934040a commit a88a677

3 files changed

Lines changed: 163 additions & 23 deletions

File tree

‎paths_cli/tests/wizard/test_parameters.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ def test_create_new(self):
142142
# wizard as a side-effect. The say_create should appear in logs.
143143
wiz = mock_wizard(["1", "name1"])
144144
wiz.store = {}
145-
obj = self.prereq.create_new(wiz)
145+
obj = self.prereq._create_new(wiz)
146146
assert obj == 11
147147
assert len(wiz.store) == 1
148148
assert wiz.store['name1'].val == "11"
@@ -155,7 +155,7 @@ def test_get_existing(self):
155155
wiz = mock_wizard([])
156156
wiz.store = {'bar': self.Wrapper("11"),
157157
'baz': self.Wrapper("22")}
158-
obj = self.prereq.get_existing(wiz)
158+
obj = self.prereq._get_existing(wiz)
159159
assert obj == [11, 22]
160160
assert wiz.console.log_text == ""
161161

@@ -167,7 +167,7 @@ def test_select_existing(self):
167167
wiz.store = {'bar': self.Wrapper("11"),
168168
'baz': self.Wrapper("22"),
169169
'qux': self.Wrapper("33")}
170-
obj = self.prereq.select_single_existing(wiz)
170+
obj = self.prereq._select_single_existing(wiz)
171171
assert obj == 11
172172
assert "Which obj_name would you" in wiz.console.log_text
173173

‎paths_cli/wizard/helper.py‎

Lines changed: 39 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
class QuitWizard(BaseException):
44
pass
55

6+
7+
# the following command functions take cmd and ctx -- future commands might
8+
# use the full command text or the context internally.
9+
610
def raise_quit(cmd, ctx):
711
raise QuitWizard()
812

@@ -42,11 +46,24 @@ def force_exit(cmd, ctx):
4246
}
4347

4448
class Helper:
49+
"""Manage help and command passing on command line.
50+
51+
Any user input beginning with "?" or "!" is passed to the helper. Input
52+
beginning with "!" is used to call commands, which allow the user to
53+
interact with the system or to force control flow that isn't built into
54+
the wizard. Input beginning with "?" is interpreted as a request for
55+
help, and the text after "?" is passed from the Helper to its help_func
56+
(or to the tools for help about commands.)
57+
58+
Parameters
59+
----------
60+
help_func : str or Callable[str, dict] -> str
61+
If a Callable, it must take the user-provided string and the context
62+
dict. If a string, the help will always return that string for any
63+
user-provided arguments.
64+
"""
4565
def __init__(self, help_func):
4666
# TODO: generalize to get help on specific aspects?
47-
if help_func is None:
48-
help_func = "Sorry, no help available."
49-
5067
if isinstance(help_func, str):
5168
text = str(help_func)
5269
help_func = lambda args, ctx: text
@@ -56,7 +73,11 @@ def __init__(self, help_func):
5673
self.command_help_str = COMMAND_HELP_STR.copy()
5774
self.listed_commands = ['quit', '!quit', 'restart']
5875

59-
def command_help(self, help_args, context):
76+
def _command_help(self, help_args, context):
77+
"""Handle help for commands.
78+
79+
Invoked if user input begins with "?!"
80+
"""
6081
if help_args == "":
6182
result = "The following commands can be used:\n"
6283
result += "\n".join([f"* !{cmd}"
@@ -70,13 +91,17 @@ def command_help(self, help_args, context):
7091
return result
7192

7293

73-
def run_command(self, command, context):
94+
def _run_command(self, command, context):
95+
"""Runs a the given command.
96+
97+
Invoked if user input begins with "!"
98+
"""
7499
cmd_split = command.split()
75100
try:
76101
key = cmd_split[0]
77102
except IndexError:
78103
return ("Please provide a command. "
79-
+ self.command_help("", context))
104+
+ self._command_help("", context))
80105

81106
args = " ".join(cmd_split[1:])
82107
try:
@@ -86,10 +111,13 @@ def run_command(self, command, context):
86111

87112
return cmd(args, context)
88113

89-
def get_help(self, help_args, context):
90-
# TODO: add default help (for ?!, etc)
114+
def _get_help(self, help_args, context):
115+
"""Get help from either command help or user-provided help.
116+
117+
Invoked if user input begins with "?"
118+
"""
91119
if help_args != "" and help_args[0] == '!':
92-
return self.command_help(help_args[1:], context)
120+
return self._command_help(help_args[1:], context)
93121

94122
if self.helper is None:
95123
return "Sorry, no help available here."
@@ -99,6 +127,6 @@ def get_help(self, help_args, context):
99127
def __call__(self, user_input, context=None):
100128
starter = user_input[0]
101129
args = user_input[1:]
102-
func = {'?': self.get_help,
103-
'!': self.run_command}[starter]
130+
func = {'?': self._get_help,
131+
'!': self._run_command}[starter]
104132
return func(args, context)

‎paths_cli/wizard/parameters.py‎

Lines changed: 121 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -71,12 +71,26 @@ def from_proxy(cls, proxy, compiler_plugin):
7171
dct['loader'] = get_category_wizard(category)
7272
dct['ask'] = get_category_info(category).singular
7373
dct['store_name'] = get_category_info(category).storage
74-
cls = ExistingObjectParameter
74+
cls = _ExistingObjectParameter
7575
else:
7676
dct['loader'] = loader
7777
return cls(**dct)
7878

7979
def __call__(self, wizard, context):
80+
"""Load the parameter.
81+
82+
Parameters
83+
----------
84+
wizard : :class:`.Wizard`
85+
wizard for interacting with the user
86+
context : dict
87+
context dic
88+
89+
Returns
90+
-------
91+
Any :
92+
the result of converting user string input to a parsed parameter
93+
"""
8094
obj = NO_PARAMETER_LOADED
8195
ask = self.ask.format(**context)
8296
while obj is NO_PARAMETER_LOADED:
@@ -85,7 +99,7 @@ def __call__(self, wizard, context):
8599
return obj
86100

87101

88-
class ExistingObjectParameter(WizardParameter):
102+
class _ExistingObjectParameter(WizardParameter):
89103
"""Special parameter type for parameters created by wizards.
90104
91105
This should only be created as part of the
@@ -111,6 +125,37 @@ def __call__(self, wizard, context):
111125

112126
class FromWizardPrerequisite:
113127
"""Load prerequisites from the wizard.
128+
129+
WARNING: This should be considered very experimental and may be removed
130+
or substantially changed in future versions.
131+
132+
Parameters
133+
----------
134+
name : str
135+
the name of this prerequisite
136+
create_func : Callable[:class:`.Wizard] -> Any
137+
method to create a relevant object, using the given wizard for user
138+
interaction. Note that the specific return object can be extracted
139+
from the results of this method by using load_func
140+
category : str
141+
category of object this creates
142+
n_required : int
143+
number of instances that must be created
144+
obj_name : str
145+
singular version of object name in order to refer to it in user
146+
interactions
147+
store_name : str
148+
name of the store in which this object would be found if it has
149+
already been created for this Wizard
150+
say_create : List[str]
151+
user interaction statement prior to creating this object. Each
152+
element in the list makes a separate statement from the wizard.
153+
say_finish : List[str]
154+
user interaction statment upon completing this object. Each element
155+
in the list makes a separate statment from the wizard.
156+
load_func : Callable
157+
method to extract specific return object from the create_func.
158+
Default is to return the result of create_func.
114159
"""
115160
def __init__(self, name, create_func, category, n_required, *,
116161
obj_name=None, store_name=None, say_create=None,
@@ -133,37 +178,104 @@ def __init__(self, name, create_func, category, n_required, *,
133178

134179
self.load_func = load_func
135180

136-
def create_new(self, wizard):
181+
def _create_new(self, wizard):
182+
"""Create a new instance of this prereq.
183+
184+
Invoked if more objects of this type are needed than have already
185+
been created for the wizard.
186+
187+
Parameters
188+
----------
189+
wizard : :class:`.Wizard`
190+
the wizard to use for user interaction
191+
192+
Returns
193+
-------
194+
Any :
195+
single instance of the required class
196+
"""
137197
if self.say_create:
138198
wizard.say(self.say_create)
139199
obj = self.create_func(wizard)
140200
wizard.register(obj, self.obj_name, self.store_name)
141201
result = self.load_func(obj)
142202
return result
143203

144-
def get_existing(self, wizard):
204+
def _get_existing(self, wizard):
205+
"""Get existing instances of the desired object.
206+
207+
This is invoked either when there are the exact right number of
208+
objects already created, or to get the initial objects when there
209+
aren't enough objects created yet.
210+
211+
Parameters
212+
----------
213+
wizard : :class:`.Wizard`
214+
the wizard to use for user interaction
215+
216+
Returns
217+
-------
218+
List[Any] :
219+
list of existing instances
220+
"""
145221
all_objs = list(getattr(wizard, self.store_name).values())
146222
results = [self.load_func(obj) for obj in all_objs]
147223
return results
148224

149-
def select_single_existing(self, wizard):
225+
def _select_single_existing(self, wizard):
226+
"""Ask the user to select an instance from the saved instances.
227+
228+
This is invoked if there are more instances already created than are
229+
required. This is called once for each instance required.
230+
231+
Parameters
232+
----------
233+
wizard : :class:`.Wizard`
234+
the wizard to use for user interaction
235+
236+
Returns
237+
-------
238+
Any :
239+
single instance of the required class
240+
"""
150241
obj = wizard.obj_selector(self.store_name, self.obj_name,
151242
self.create_func)
152243
return self.load_func(obj)
153244

154245
def __call__(self, wizard, context=None):
246+
"""Obtain the correct number of instances of the desired type.
247+
248+
This will either take the existing object(s) in the wizard (if the
249+
exact correct number have been created in the wizard), create new
250+
objects (if there are not enough) or ask the user to select the
251+
existing instances (if there are more than enough).
252+
253+
Parameters
254+
----------
255+
wizard : :class:`.Wizard`
256+
the wizard to use for user interaction
257+
context : dict
258+
context dictionary
259+
260+
Returns
261+
-------
262+
Dict[str, List[Any]] :
263+
mapping ``self.name`` to a list of objects of the correct type.
264+
Note that this always maps to a list; receiving code may need to
265+
handle that fact.
266+
"""
155267
n_existing = len(getattr(wizard, self.store_name))
156268
if n_existing == self.n_required:
157269
# early return in this case (return silently)
158-
return {self.name: self.get_existing(wizard)}
270+
return {self.name: self._get_existing(wizard)}
159271
elif n_existing > self.n_required:
160-
sel = [self.select_single_existing(wizard)
272+
sel = [self._select_single_existing(wizard)
161273
for _ in range(self.n_required)]
162274
dct = {self.name: sel}
163275
else:
164-
objs = self.get_existing(wizard)
276+
objs = self._get_existing(wizard)
165277
while len(getattr(wizard, self.store_name)) < self.n_required:
166-
objs.append(self.create_new(wizard))
278+
objs.append(self._create_new(wizard))
167279
dct = {self.name: objs}
168280

169281
if self.say_finish:

0 commit comments

Comments
 (0)