Implement a help() method for the configuration system - #13499

I haven't looked at the code in detail but this is an awesome idea. 💯

I like the idea too, but wonder if a simpler solution to the problem is not to define a __repr__ which essentially includes your help text for all names.

Actually, just because I (EDIT: thought wouldn't it be nice if one could just do "help(something)" and) wondered what would happen, help(conf) is quite good...

from astropy.utils.iers import conf

help(conf)

Help on Conf in module astropy.utils.iers.iers object:

class Conf(astropy.config.configuration.ConfigNamespace)
 |  Configuration parameters for `astropy.utils.iers`.
 |  
 |  Method resolution order:
 |      Conf
 |      astropy.config.configuration.ConfigNamespace
 |      builtins.object
 |  
 |  Data descriptors defined here:
 |  
 |  auto_download
 |      Enable auto-downloading of the latest IERS data.  If set to False then the local IERS-B file will be used by default (even if the full IERS file with predictions was already downloaded and cached). This parameter also controls whether internet resources will be queried to update the leap second table if the installed version is out of date. Default is True.
 |  
 |  auto_max_age
 |      Maximum age (days) of predictive data before auto-downloading. See "Auto refresh behavior" in astropy.utils.iers documentation for details. Default is 30.
 |  
 |  iers_auto_url
 |      URL for auto-downloading IERS file data.
 |  
 |  iers_auto_url_mirror
 |      Mirror URL for auto-downloading IERS file data.
 |  
 |  iers_degraded_accuracy
 |      IERS behavior if the range of available IERS data does not cover the times when converting time scales, potentially leading to degraded accuracy.
 |  
 |  iers_leap_second_auto_url
 |      URL for auto-downloading leap seconds.
 |  
 |  ietf_leap_second_auto_url
 |      Alternate URL for auto-downloading leap seconds.
 |  
 |  remote_timeout
 |      Remote timeout downloading IERS file data (seconds).
 |  
 |  system_leap_second_file
 |      System file with leap seconds.
 |  

Actually, just because I (EDIT: thought wouldn't it be nice if one could just do "help(something)" and) wondered what would happen, help(conf) is quite good...

Python's builtin help() function prints quite a lot for the ConfigNamespace, but if help is wanted for a single item then this could be overwhelming. The ConfigNamespace.help() method I am proposing would allow for printing an overview of a single configuration item, and it shows more information per item than the builtin help() does. In particular, if a configuration item accepts only a finite set of values then ConfigNamespace.help() lists all of them.

I like the idea too, but wonder if a simpler solution to the problem is not to define a __repr__

ConfigItem.__str__() already produces an informative string:

However, thanks to ConfigItem.__get__() accessing the configuration items normally (as attributes of the ConfigNamespace instance) retrieves their value, not the ConfigItem instance, so the ConfigItem.__str__() method is quite difficult to access.

I have updated the pull request so that if help is printed for multiple configuration items then the entries are separated with empty lines, and there is now an example in the docstring.

I guess we should separate the two concerns, but right now, while the configitems may have a nice __str__ method, the configuration entity does not: print(conf) and repr(conf) are both essentially useless! I think this is partially a question of what users are most likely to discover; I think that starts with just giving something useful for the repr -- most confs do not have that many entries, so generally it will not be overwhelming.

Note that in ipython, conf? is also not very helpful (conf?? is better but less good than help(conf).

All that said, I definitely see your point that just from tab-completion, it is nearly impossible to get useful information; e.g., conf.auto_download? gives information on bools... My main worry is just that it is unlikely any user would guess there would be a .help() method (though presumably they might find it through tab completion); for the somewhat related Table.read.help, the main trick was to put the existence of the .help method high up in the docstring (though I still worry I only know about it because I saw the PR!).

I've implemented ConfigNamespace.__str__(). The string representation of a ConfigNamespace contains the string representations of the configuration items within it, and is used in ConfigNamespace.help(). Although calling print(conf) now results in the same message as calling conf.help() without arguments, having the help() method is still useful because it also allows printing the string representation of a single configuration item.

I have converted this pull request to a draft so that we could discuss if the ConfigItem.__str__() should be changed or if we are happy with the way the string representation of a configuration item is currently formatted.

@mhvk, does the proposed implementation address your remarks?

@mhvk, could you have a look at this? I converted this pull request to a draft in case we want to also change ConfigItem.__str__(), but if we don't then this should be good to merge as is.

I'm so sorry that this keeps slipping by. The problem is mostly that really all I remember is a feeling of disquiet at this, but I know that I actually have to look at things again, for which I don't really have time right now. It may be more logical is some of the people who wrote the configuration system had a look, so let's ping @eteq, @saimn and @WilliamJamieson .

The pull request now matches my branch, so this is ready for review.

A short summary of this pull request is that it implements ConfigNamespace.__str__() and ConfigNamespace.help(), both of which make it simple to learn about configuration items from within Python. However, both implemented methods make use of ConfigItem.__str__(), which I haven't edited, but perhaps it should be updated so that the output of ConfigNamespace.help() would be more convenient.

I have updated the example outputs of the code, both in the tests and in the documentation. As they are written now they are closer to the actual outputs users would see. The cost of doing this are a few overlong lines, but I think not having artificial line breaks in the examples is a good enough excuse.

I rebased this once more as requested by https://groups.google.com/g/astropy-dev/c/9DO4YkoU44g

codecov upload failed, so we can ignore the coverage complain.

Despite using a .help() method, unlike typical Python str or repr, I still think this is an improvement based on the doc updates. Just have a small comment on the example that was removed.

I think this also works for downstream packages that uses the config system (e.g., synphot), so that is nice. 👏