1# Licensed under the Apache License, Version 2.0 (the "License"); you may
2# not use this file except in compliance with the License. You may obtain
3# a copy of the License at
4#
5#      http://www.apache.org/licenses/LICENSE-2.0
6#
7# Unless required by applicable law or agreed to in writing, software
8# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
9# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
10# License for the specific language governing permissions and limitations
11# under the License.
12
13import itertools
14import os
15
16from keystoneauth1.loading import _utils
17
18
19__all__ = ('Opt',)
20
21
22class Opt(object):
23    """An option required by an authentication plugin.
24
25    Opts provide a means for authentication plugins that are going to be
26    dynamically loaded to specify the parameters that are to be passed to the
27    plugin on initialization.
28
29    The Opt specifies information about the way the plugin parameter is to be
30    represented in different loading mechanisms.
31
32    When defining an Opt with a - the - should be present in the name
33    parameter. This will automatically be converted to an _ when passing to the
34    plugin initialization. For example, you should specify::
35
36        Opt('user-domain-id')
37
38    which will pass the value as `user_domain_id` to the plugin's
39    initialization.
40
41    :param str name: The name of the option.
42    :param callable type: The type of the option. This is a callable which is
43        passed the raw option that was loaded (often a string) and is required
44        to return the parameter in the type expected by __init__.
45    :param str help: The help text that is shown along with the option.
46    :param bool secret: If the parameter is secret it should not be printed or
47        logged in debug output.
48    :param str dest: the name of the argument that will be passed to __init__.
49        This allows you to have a different name in loading than is used by the
50        __init__ function. Defaults to the value of name.
51    :param keystoneauth1.loading.Opt: A list of other options that are
52        deprecated in favour of this one. This ensures the old options are
53        still registered.
54    :type opt: list(Opt)
55    :param default: A default value that can be used if one is not provided.
56    :param str metavar: The <metavar> that should be printed in CLI help text.
57    :param bool required: If the option is required to load the plugin. If a
58        required option is not present loading should fail.
59    :param str prompt: If the option can be requested via a prompt (where
60        appropriate) set the string that should be used to prompt with.
61    """
62
63    def __init__(self,
64                 name,
65                 type=str,
66                 help=None,
67                 secret=False,
68                 dest=None,
69                 deprecated=None,
70                 default=None,
71                 metavar=None,
72                 required=False,
73                 prompt=None):
74        if not callable(type):
75            raise TypeError('type must be callable')
76
77        if dest is None:
78            dest = name.replace('-', '_')
79
80        self.name = name
81        self.type = type
82        self.help = help
83        self.secret = secret
84        self.required = required
85        self.dest = dest
86        self.deprecated = [] if deprecated is None else deprecated
87        self.default = default
88        self.metavar = metavar
89        self.prompt = prompt
90        # These are for oslo.config compat
91        self.deprecated_opts = self.deprecated
92        self.deprecated_for_removal = []
93        self.sample_default = None
94        self.group = None
95
96    def __repr__(self):
97        """Return string representation of option name."""
98        return '<Opt: %s>' % self.name
99
100    def _to_oslo_opt(self):
101        cfg = _utils.get_oslo_config()
102        deprecated_opts = [cfg.DeprecatedOpt(o.name) for o in self.deprecated]
103
104        return cfg.Opt(name=self.name,
105                       type=self.type,
106                       help=self.help,
107                       secret=self.secret,
108                       required=self.required,
109                       dest=self.dest,
110                       deprecated_opts=deprecated_opts,
111                       metavar=self.metavar)
112
113    def __eq__(self, other):
114        """Define equality operator on option parameters."""
115        return (type(self) == type(other) and
116                self.name == other.name and
117                self.type == other.type and
118                self.help == other.help and
119                self.secret == other.secret and
120                self.required == other.required and
121                self.dest == other.dest and
122                self.deprecated == other.deprecated and
123                self.default == other.default and
124                self.metavar == other.metavar)
125
126    # NOTE: This function is only needed by Python 2. If we get to point where
127    # we don't support Python 2 anymore, this function should be removed.
128    def __ne__(self, other):
129        """Define inequality operator on option parameters."""
130        return not self.__eq__(other)
131
132    @property
133    def _all_opts(self):
134        return itertools.chain([self], self.deprecated)
135
136    @property
137    def argparse_args(self):
138        return ['--os-%s' % o.name for o in self._all_opts]
139
140    @property
141    def argparse_default(self):
142        # select the first ENV that is not false-y or return None
143        for o in self._all_opts:
144            v = os.environ.get('OS_%s' % o.name.replace('-', '_').upper())
145            if v:
146                return v
147
148        return self.default
149