Details
-
Type:
Improvement
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: pex_config
-
Labels:None
-
Team:Architecture
Description
Alex Drlica-Wagner reports:
I've been trying to access the configurable options for a "nested" config like ProcessCcdConfig (i.e., a config that contains other ConfigurableInstance objects). I would have thought that something like this would work to give me the help string for an IsrTaskConfig object, but instead I get the help for a ConfigurableInstance
from lsst.pipe.tasks.processCcd import ProcessCcdConfig |
config = ProcessCcdConfig() |
help(config.isr) |
and the output:
Help on ConfigurableInstance in module lsst.pex.config.configurableField object:
|
|
|
class ConfigurableInstance(builtins.object)
|
| Methods defined here:
|
...
|
This is continuing off of a Slack conversation with Jonathan Sick Merlin Fisher-Levine Paul Price.
Merlin Fisher-Levine then responded:
I think that the root of this is also what causes help(config.<int_field>)
to return the help for an int, rather than the docstring and options
for that int-field in the config. If it's somehow not, that's something
to fix too...
Attachments
Issue Links
- links to
Activity
I had no idea that help(config.isr.value) would do that, but I can confirm that is indeed exactly what was wanted here.
If this is obvious to others then I don't think it needs fixing as this is exactly the desired functionality. If it's not though then this might still be worth looking into.
My proposal is to add a docstring to ConfigurableInstance (which currently does not have one). This text would then appear at the top of help(config.isr) like so:
Help on ConfigurableInstance in module lsst.pex.config.configurableField object:
|
class ConfigurableInstance(builtins.object)
|
| A retargetable configuration for a configurable object.
|
|
|
| Use the `value` property to access the actual Config instance; use the
|
| `target` property to access the associated configurable object (e.g. a
|
| `Task`).
|
Would this be adequate?
I think so, yes.
Anything you can do to that text to front-load the relevant point so as to avoid people whose eyes tend to cast over boilerplate from missing the salient point would be great. I doubt anyone would ever want to call help() and not want to actually be calling .value, and I imagine I'm not alone in having a strong heuristic which says not to actually read things that look like that.
But yes, other than trying to protect people like me from their own idiocy, I think that would be great.
Looks good. Curious how one of those docstrings was previously outside the definition, but thanks for moving it an as part of this 
Merged in d0f1235.
These are asking for two different things. In the first case, the ConfigurableField requires another level of indirection. help(config.isr.value) gets you to what you want, although I agree that the extra level is undesirable. It looks like there was an attempt to bring the ConfigurableField value's documentation into the ConfigurableInstance instance, but changing an instance's __doc__ value doesn't actually change what help(instance) returns; that appears to always be based on the type, and changing ConfigurableInstance's class documentation would not be appropriate.
In the second case, the request is for help on a variable instead of a type. Python doesn't normally support this; only types and methods get help. To get the options for a field in a Config subclass, you need to run help on that Config type or an instance of it.