summaryrefslogtreecommitdiffstats
path: root/ipalib/config.py
blob: 39c4238cf6be59da98070bbfaef05bf6368f159d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
# Authors:
#   Martin Nagy <mnagy@redhat.com>
#   Jason Gerard DeRose <jderose@redhat.com>
#
# Copyright (C) 2008  Red Hat
# see file 'COPYING' for use and warranty information
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation; version 2 only
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

"""
Process-wide static configuration and environment.

The standard run-time instance of the `Env` class is initialized early in the
`ipalib` process and is then locked into a read-only state, after which no
further changes can be made to the environment throughout the remaining life
of the process.

For the per-request thread-local information, see `ipalib.request`.
"""

from ConfigParser import RawConfigParser, ParsingError
from types import NoneType
import os
from os import path
import sys
from socket import gethostname

from base import check_name
from constants import CONFIG_SECTION
from constants import TYPE_ERROR, OVERRIDE_ERROR, SET_ERROR, DEL_ERROR


class Env(object):
    """
    Store and retrieve environment variables.

    First an foremost, the `Env` class provides a handy container for
    environment variables.  These variables can be both set *and* retrieved
    either as attributes *or* as dictionary items.

    For example, you can set a variable as an attribute:

    >>> env = Env()
    >>> env.attr = 'I was set as an attribute.'
    >>> env.attr
    'I was set as an attribute.'
    >>> env['attr']  # Also retrieve as a dictionary item
    'I was set as an attribute.'

    Or you can set a variable as a dictionary item:

    >>> env['item'] = 'I was set as a dictionary item.'
    >>> env['item']
    'I was set as a dictionary item.'
    >>> env.item  # Also retrieve as an attribute
    'I was set as a dictionary item.'

    The variable names must be valid lower-case Python identifiers that neither
    start nor end with an underscore.  If your variable name doesn't meet these
    criteria, a ``ValueError`` will be raised when you try to set the variable
    (compliments of the `base.check_name()` function).  For example:

    >>> env.BadName = 'Wont work as an attribute'
    Traceback (most recent call last):
      ...
    ValueError: name must match '^[a-z][_a-z0-9]*[a-z0-9]$'; got 'BadName'
    >>> env['BadName'] = 'Also wont work as a dictionary item'
    Traceback (most recent call last):
      ...
    ValueError: name must match '^[a-z][_a-z0-9]*[a-z0-9]$'; got 'BadName'

    The variable values can be ``str``, ``int``, or ``float`` instances, or the
    ``True``, ``False``, or ``None`` constants.  When the value provided is an
    ``str`` instance, some limited automatic type conversion is performed, which
    allows values of specific types to be set easily from configuration files or
    command-line options.

    So in addition to their actual values, the ``True``, ``False``, and ``None``
    constants can be specified with an ``str`` equal to what ``repr()`` would
    return.  For example:

    >>> env.true = True
    >>> env.also_true = 'True'  # Equal to repr(True)
    >>> env.true
    True
    >>> env.also_true
    True

    Note that the automatic type conversion is case sensitive.  For example:

    >>> env.not_false = 'false'  # Not equal to repr(False)!
    >>> env.not_false
    'false'

    If an ``str`` value looks like an integer, it's automatically converted to
    the ``int`` type.  Likewise, if an ``str`` value looks like a floating-point
    number, it's automatically converted to the ``float`` type.  For example:

    >>> env.lucky = '7'
    >>> env.lucky
    7
    >>> env.three_halves = '1.5'
    >>> env.three_halves
    1.5

    Leading and trailing white-space is automatically stripped from ``str``
    values.  For example:

    >>> env.message = '  Hello!  '  # Surrounded by double spaces
    >>> env.message
    'Hello!'
    >>> env.number = ' 42 '  # Still converted to an int
    >>> env.number
    42
    >>> env.false = ' False '  # Still equal to repr(False)
    >>> env.false
    False

    Also, empty ``str`` instances are converted to ``None``.  For example:

    >>> env.empty = ''
    >>> env.empty is None
    True

    `Env` variables are all set-once (first-one-wins).  Once a variable has been
    set, trying to override it will raise an ``AttributeError``.  For example:

    >>> env.date = 'First'
    >>> env.date = 'Second'
    Traceback (most recent call last):
      ...
    AttributeError: cannot override Env.date value 'First' with 'Second'

    An `Env` instance can be *locked*, after which no further variables can be
    set.  Trying to set variables on a locked `Env` instance will also raise
    an ``AttributeError``.  For example:

    >>> env = Env()
    >>> env.okay = 'This will work.'
    >>> env.__lock__()
    >>> env.nope = 'This wont work!'
    Traceback (most recent call last):
      ...
    AttributeError: locked: cannot set Env.nope to 'This wont work!'

    `Env` instances also provide standard container emulation for membership
    testing, counting, and iteration.  For example:

    >>> env = Env()
    >>> 'key1' in env  # Has key1 been set?
    False
    >>> env.key1 = 'value 1'
    >>> 'key1' in env
    True
    >>> env.key2 = 'value 2'
    >>> len(env)  # How many variables have been set?
    2
    >>> list(env)  # What variables have been set?
    ['key1', 'key2']

    Lastly, in addition to all the handy container functionality, the `Env`
    class provides high-level methods for bootstraping a fresh `Env` instance
    into one containing all the run-time and configuration information needed
    by the built-in freeIPA plugins.

    These are the `Env` bootstraping methods, in the order they must be called:

        1. `Env._bootstrap()` - initialize the run-time variables and then
           merge-in variables specified on the command-line.

        2. `Env._finalize_core()` - merge-in variables from the configuration
           files and then merge-in variables from the internal defaults, after
           which at least all the standard variables will be set.  After this
           method is called, the plugins will be loaded, during which
           third-party plugins can merge-in defaults for additional variables
           they use (likely using the `Env._merge()` method).

        3. `Env._finalize()` - one last chance to merge-in variables and then
           the instance is locked.  After this method is called, no more
           environment variables can be set during the remaining life of the
           process.

    However, normally none of these three bootstraping methods are called
    directly and instead only `plugable.API.bootstrap()` is called, which itself
    takes care of correctly calling the `Env` bootstrapping methods.
    """

    __locked = False

    def __init__(self):
        object.__setattr__(self, '_Env__d', {})
        object.__setattr__(self, '_Env__done', set())

    def __lock__(self):
        """
        Prevent further changes to environment.
        """
        if self.__locked is True:
            raise StandardError(
                '%s.__lock__() already called' % self.__class__.__name__
            )
        object.__setattr__(self, '_Env__locked', True)

    def __islocked__(self):
        """
        Return ``True`` if locked.
        """
        return self.__locked

    def __setattr__(self, name, value):
        """
        Set the attribute named ``name`` to ``value``.

        This just calls `Env.__setitem__()`.
        """
        self[name] = value

    def __setitem__(self, key, value):
        """
        Set ``key`` to ``value``.
        """
        if self.__locked:
            raise AttributeError(
                SET_ERROR % (self.__class__.__name__, key, value)
            )
        check_name(key)
        if key in self.__d:
            raise AttributeError(OVERRIDE_ERROR %
                (self.__class__.__name__, key, self.__d[key], value)
            )
        assert not hasattr(self, key)
        if isinstance(value, basestring):
            value = str(value.strip())
            m = {
                'True': True,
                'False': False,
                'None': None,
                '': None,
            }
            if value in m:
                value = m[value]
            elif value.isdigit():
                value = int(value)
            else:
                try:
                    value = float(value)
                except (TypeError, ValueError):
                    pass
        assert type(value) in (str, int, float, bool, NoneType)
        object.__setattr__(self, key, value)
        self.__d[key] = value

    def __getitem__(self, key):
        """
        Return the value corresponding to ``key``.
        """
        return self.__d[key]

    def __delattr__(self, name):
        """
        Raise an ``AttributeError`` (deletion is never allowed).

        For example:

        >>> env = Env()
        >>> env.name = 'A value'
        >>> del env.name
        Traceback (most recent call last):
          ...
        AttributeError: locked: cannot delete Env.name
        """
        raise AttributeError(
            DEL_ERROR % (self.__class__.__name__, name)
        )

    def __contains__(self, key):
        """
        Return True if instance contains ``key``; otherwise return False.
        """
        return key in self.__d

    def __len__(self):
        """
        Return number of variables currently set.
        """
        return len(self.__d)

    def __iter__(self):
        """
        Iterate through keys in ascending order.
        """
        for key in sorted(self.__d):
            yield key

    def _merge(self, **kw):
        """
        Merge variables from ``kw`` into the environment.

        Any variables in ``kw`` that have already been set will be ignored
        (meaning this method will *not* try to override them, which would raise
        an exception).

        This method returns a ``(num_set, num_total)`` tuple containing first
        the number of variables that were actually set, and second the total
        number of variables that were provided.

        For example:

        >>> env = Env()
        >>> env._merge(one=1, two=2)
        (2, 2)
        >>> env._merge(one=1, three=3)
        (1, 2)
        >>> env._merge(one=1, two=2, three=3)
        (0, 3)

        Also see `Env._merge_from_file()`.

        :param kw: Variables provides as keyword arguments.
        """
        i = 0
        for (key, value) in kw.iteritems():
            if key not in self:
                self[key] = value
                i += 1
        return (i, len(kw))

    def _merge_from_file(self, config_file):
        """
        Merge variables from ``config_file`` into the environment.

        Any variables in ``config_file`` that have already been set will be
        ignored (meaning this method will *not* try to override them, which
        would raise an exception).

        If ``config_file`` does not exist or is not a regular file, or if there
        is an error parsing ``config_file``, ``None`` is returned.

        Otherwise this method returns a ``(num_set, num_total)`` tuple
        containing first the number of variables that were actually set, and
        second the total number of variables found in ``config_file``.

        This method will raise a ``ValueError`` if ``config_file`` is not an
        absolute path.  For example:

        >>> env = Env()
        >>> env._merge_from_file('my/config.conf')
        Traceback (most recent call last):
          ...
        ValueError: config_file must be an absolute path; got 'my/config.conf'

        Also see `Env._merge()`.

        :param config_file: Absolute path of the configuration file to load.
        """
        if path.abspath(config_file) != config_file:
            raise ValueError(
                'config_file must be an absolute path; got %r' % config_file
            )
        if not path.isfile(config_file):
            return
        parser = RawConfigParser()
        try:
            parser.read(config_file)
        except ParsingError:
            return
        if not parser.has_section(CONFIG_SECTION):
            parser.add_section(CONFIG_SECTION)
        items = parser.items(CONFIG_SECTION)
        if len(items) == 0:
            return (0, 0)
        i = 0
        for (key, value) in items:
            if key not in self:
                self[key] = value
                i += 1
        return (i, len(items))

    def __doing(self, name):
        if name in self.__done:
            raise StandardError(
                '%s.%s() already called' % (self.__class__.__name__, name)
            )
        self.__done.add(name)

    def __do_if_not_done(self, name):
        if name not in self.__done:
            getattr(self, name)()

    def _isdone(self, name):
        return name in self.__done

    def _bootstrap(self, **overrides):
        """
        Initialize basic environment.

        This method will perform the following steps:

            1. Initialize certain run-time variables.  These run-time variables
               are strictly determined by the external environment the process
               is running in; they cannot be specified on the command-line nor
               in the configuration files.

            2. Merge-in the variables in ``overrides`` by calling
               `Env._merge()`.  The intended use of ``overrides`` is to merge-in
               variables specified on the command-line.

            3. Intelligently fill-in the *in_tree*, *context*, *conf*, and
               *conf_default* variables if they haven't been set already.

        Also see `Env._finalize_core()`, the next method in the bootstrap
        sequence.

        :param overrides: Variables specified via command-line options.
        """
        self.__doing('_bootstrap')

        # Set run-time variables:
        self.host = gethostname()
        self.ipalib = path.dirname(path.abspath(__file__))
        self.site_packages = path.dirname(self.ipalib)
        self.script = path.abspath(sys.argv[0])
        self.bin = path.dirname(self.script)
        self.home = os.environ.get('HOME', None)
        self.dot_ipa = self._join('home', '.ipa')
        self._merge(**overrides)
        if 'in_tree' not in self:
            if self.bin == self.site_packages and \
                    path.isfile(path.join(self.bin, 'setup.py')):
                self.in_tree = True
            else:
                self.in_tree = False
        if 'context' not in self:
            self.context = 'default'
        if self.in_tree:
            base = self.dot_ipa
        else:
            base = path.join('/', 'etc', 'ipa')
        if 'conf' not in self:
            self.conf = path.join(base, '%s.conf' % self.context)
        if 'conf_default' not in self:
            self.conf_default = path.join(base, 'default.conf')
        if 'conf_dir' not in self:
            self.conf_dir = base

    def _join(self, key, *parts):
        if key in self and self[key] is not None:
            return path.join(self[key], *parts)

    def _finalize_core(self, **defaults):
        """
        Complete initialization of standard IPA environment.

        This method will perform the following steps:

            1. Call `Env._bootstrap()` if it hasn't already been called.

            2. Merge-in variables from the configuration file ``self.conf``
               (if it exists) by calling `Env._merge_from_file()`.

            3. Merge-in variables from the defaults configuration file
               ``self.conf_default`` (if it exists) by calling
               `Env._merge_from_file()`.

            4. Intelligently fill-in the *in_server* and *log* variables
               if they haven't already been set.

            5. Merge-in the variables in ``defaults`` by calling `Env._merge()`.
               In normal circumstances ``defaults`` will simply be those
               specified in `constants.DEFAULT_CONFIG`.

        After this method is called, all the environment variables used by all
        the built-in plugins will be available.  As such, this method should be
        called *before* any plugins are loaded.

        After this method has finished, the `Env` instance is still writable
        so that 3rd-party plugins can set variables they may require as the
        plugins are registered.

        Also see `Env._finalize()`, the final method in the bootstrap sequence.

        :param defaults: Internal defaults for all built-in variables.
        """
        self.__doing('_finalize_core')
        self.__do_if_not_done('_bootstrap')
        if self.__d.get('mode', None) != 'dummy':
            self._merge_from_file(self.conf)
            self._merge_from_file(self.conf_default)
        if 'in_server' not in self:
            self.in_server = (self.context == 'server')
        if 'log' not in self:
            name = '%s.log' % self.context
            if self.in_tree or self.context == 'cli':
                self.log = path.join(self.dot_ipa, 'log', name)
            else:
                self.log = path.join('/', 'var', 'log', 'ipa', name)
        if 'ca_host' not in self:
            self.ca_host = self.host
        self._merge(**defaults)

    def _finalize(self, **lastchance):
        """
        Finalize and lock environment.

        This method will perform the following steps:

            1. Call `Env._finalize_core()` if it hasn't already been called.

            2. Merge-in the variables in ``lastchance`` by calling
               `Env._merge()`.

            3. Lock this `Env` instance, after which no more environment
               variables can be set on this instance.  Aside from unit-tests
               and example code, normally only one `Env` instance is created,
               which means that after this step, no more variables can be set
               during the remaining life of the process.

        This method should be called after all plugins have been loaded and
        after `plugable.API.finalize()` has been called.

        :param lastchance: Any final variables to merge-in before locking.
        """
        self.__doing('_finalize')
        self.__do_if_not_done('_finalize_core')
        self._merge(**lastchance)
        self.__lock__()