Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-62

Make config files and command line specifications of configurations consistent

    XMLWordPrintable

Details

    • RFC
    • Status: Implemented
    • Resolution: Done
    • DM
    • None
    • PR

    Description

      There is an irritating inconsistency between how you specify configuration parameters on the command line (config.foo.bar) and in a configuration file (root.foo.bar). This is especially annoying when you use --show config to obtain the name, cut and paste the answer into a file, and are rewarded with:

      error: cannot load config file 'ptfConfig.py': name 'config' is not defined

      This RFC proposes that we adopt a consist naming convention. I prefer config everywhere, but (as ktl points out) that's a slightly more complex change than adopting root everywhere. On the other hand, I think that adopting config is much clearer, and wouldn't tempt us to change the the pipe_base's -show config[=glob] option.

      Attachments

        Issue Links

          Activity

            rowen Russell Owen added a comment -

            My objection to "root" is that it isn't obvious what it refers to. "config" is much clearer. For a user looking at some random bit of .py code there is no particular reason to understand that "root" means "the root level of a config". To my eyes "root" is meaningless jargon (root of WHAT?), which makes our stack harder for new users to understand.

            By comparison I feel that "config" is quite clear. If a user sees a file containing config.foo.bar = value then it's pretty clear that a configuration field is being set.

            rowen Russell Owen added a comment - My objection to "root" is that it isn't obvious what it refers to. "config" is much clearer. For a user looking at some random bit of .py code there is no particular reason to understand that "root" means "the root level of a config". To my eyes "root" is meaningless jargon (root of WHAT?), which makes our stack harder for new users to understand. By comparison I feel that "config" is quite clear. If a user sees a file containing config.foo.bar = value then it's pretty clear that a configuration field is being set.
            price Paul Price added a comment -

            I agree with jbosch that root is clear as the root of the configuration hierarchy (though I have a very mild preference for config). I propose changing the output of --show config to use root. That solves the problem of invalidating existing user code.

            Aside: this has been a known problem for 3 years (https://dev.lsstcorp.org/trac/ticket/2044), and the same proposed solution was made there in the code review:

            I'm a little worried that --show config produces a config that is not loadable without renaming or use of load(root="config"). But, since this ticket is just about finding things in the config and not reloading it, this is OK for now (and a simple fix if needed later).

            price Paul Price added a comment - I agree with jbosch that root is clear as the root of the configuration hierarchy (though I have a very mild preference for config ). I propose changing the output of --show config to use root . That solves the problem of invalidating existing user code. Aside: this has been a known problem for 3 years ( https://dev.lsstcorp.org/trac/ticket/2044 ), and the same proposed solution was made there in the code review: I'm a little worried that --show config produces a config that is not loadable without renaming or use of load(root="config") . But, since this ticket is just about finding things in the config and not reloading it, this is OK for now (and a simple fix if needed later).
            rowen Russell Owen added a comment -

            If we switch to root in the task output then the output of --show config will show root.foo.bar = x instead of config.foo.bar = x for every config item. This output appears among many other messages unrelated to the config, making the data hard enough to spot already. I think it will be much, much harder to spot and more confusing if the word config changes to root.

            I disagree with Jim (which is a bad sign, since he's usually right) when he says it should be obvious in context that a .py file is a config override file. I have not found that to be true. I admit that many config override files are in a directory named "config", but that's just for obs-package-specific override files, not files in test directories or private directories where a user is messing about. And even if it were always true, a user may not know where a file is located when trying to understand that file.

            It is even worse for the "--show config" option when running a task. There is no context in that situation. The user sees a lot more output when using that flag, but which are the lines the user is looking for? Why should the user expect them to start with root? Wouldn't "config" be easier to spot? I certainly felt so, which was why I took the bold and possibly obnoxious stance of forcing "config" even when config files used "root" instead.

            I understand the argument for "the root of the config", but we're calling it "root" not "configRoot", so the result is a conceptual purity that I feel obscures the underlying reality that we are setting an attribute of an instance of a Config. I think we all agree that configRoot is too wordy, so we must abbreviate it, thus losing information. The two obvious abbreviations are "config" and "root" and I feel the former is much clearer. If we use "config" everywhere then the user sees "config" and should mentally add "root" to get "the root of the configuration". As it stands, the user sees "root", but where is the clue that tells them this is a configuration object?

            rowen Russell Owen added a comment - If we switch to root in the task output then the output of --show config will show root.foo.bar = x instead of config.foo.bar = x for every config item. This output appears among many other messages unrelated to the config, making the data hard enough to spot already. I think it will be much, much harder to spot and more confusing if the word config changes to root. I disagree with Jim (which is a bad sign, since he's usually right) when he says it should be obvious in context that a .py file is a config override file. I have not found that to be true. I admit that many config override files are in a directory named "config", but that's just for obs-package-specific override files, not files in test directories or private directories where a user is messing about. And even if it were always true, a user may not know where a file is located when trying to understand that file. It is even worse for the "--show config" option when running a task. There is no context in that situation. The user sees a lot more output when using that flag, but which are the lines the user is looking for? Why should the user expect them to start with root? Wouldn't "config" be easier to spot? I certainly felt so, which was why I took the bold and possibly obnoxious stance of forcing "config" even when config files used "root" instead. I understand the argument for "the root of the config", but we're calling it "root" not "configRoot", so the result is a conceptual purity that I feel obscures the underlying reality that we are setting an attribute of an instance of a Config. I think we all agree that configRoot is too wordy, so we must abbreviate it, thus losing information. The two obvious abbreviations are "config" and "root" and I feel the former is much clearer. If we use "config" everywhere then the user sees "config" and should mentally add "root" to get "the root of the configuration". As it stands, the user sees "root", but where is the clue that tells them this is a configuration object?

            config shall be the common root.

            ktl Kian-Tat Lim added a comment - config shall be the common root.

            I will implement this.

            rowen Russell Owen added a comment - I will implement this.

            People

              rhl Robert Lupton
              rhl Robert Lupton
              Gregory Dubois-Felsmann, Jim Bosch, John Swinbank, Kian-Tat Lim, Paul Price, Robert Lupton, Russell Owen
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                Planned End:

                Jenkins

                  No builds found.