@@ -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
112126class 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