aboutsummaryrefslogtreecommitdiffstats
path: root/libbe/storage/util/settings_object.py
blob: be119dd9ec3e381165a27a29cf32384fc6f21125 (plain) (blame)
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
# Bugs Everywhere - a distributed bugtracker
# Copyright (C) 2008-2009 Gianluca Montecchi <gian@grys.it>
#                         W. Trevor King <wking@drexel.edu>
#
# 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; either version 2 of the License, or
# (at your option) any later version.
#
# 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.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

"""
This module provides a base class implementing settings-dict based
property storage useful for BE objects with saved properties
(e.g. BugDir, Bug, Comment).  For example usage, consider the
unittests at the end of the module.
"""

import libbe
from properties import Property, doc_property, local_property, \
    defaulting_property, checked_property, fn_checked_property, \
    cached_property, primed_property, change_hook_property, \
    settings_property
if libbe.TESTING == True:
    import doctest
    import unittest

class _Token (object):
    """
    `Control' value class for properties.  We want values that only
    mean something to the settings_object module.
    """
    pass

class UNPRIMED (_Token):
    "Property has not been primed."
    pass

class EMPTY (_Token):
    """
    Property has been primed but has no user-set value, so use
    default/generator value.
    """
    pass


def prop_save_settings(self, old, new):
    """
    The default action undertaken when a property changes.
    """
    if self.storage != None and self.storage.is_writeable():
        self.save_settings()

def prop_load_settings(self):
    """
    The default action undertaken when an UNPRIMED property is accessed.
    """
    if self.storage != None and self.storage.is_readable() \
            and self._settings_loaded==False:
        self.load_settings()
    else:
        self._setup_saved_settings(flag_as_loaded=False)

# Some name-mangling routines for pretty printing setting names
def setting_name_to_attr_name(self, name):
    """
    Convert keys to the .settings dict into their associated
    SavedSettingsObject attribute names.
    >>> print setting_name_to_attr_name(None,"User-id")
    user_id
    """
    return name.lower().replace('-', '_')

def attr_name_to_setting_name(self, name):
    """
    The inverse of setting_name_to_attr_name.
    >>> print attr_name_to_setting_name(None, "user_id")
    User-id
    """
    return name.capitalize().replace('_', '-')


def versioned_property(name, doc,
                       default=None, generator=None,
                       change_hook=prop_save_settings,
                       mutable=False,
                       primer=prop_load_settings,
                       allowed=None, check_fn=None,
                       settings_properties=[],
                       required_saved_properties=[],
                       require_save=False):
    """
    Combine the common decorators in a single function.

    Use zero or one (but not both) of default or generator, since a
    working default will keep the generator from functioning.  Use the
    default if you know what you want the default value to be at
    'coding time'.  Use the generator if you can write a function to
    determine a valid default at run time.  If both default and
    generator are None, then the property will be a defaulting
    property which defaults to None.

    allowed and check_fn have a similar relationship, although you can
    use both of these if you want.  allowed compares the proposed
    value against a list determined at 'coding time' and check_fn
    allows more flexible comparisons to take place at run time.

    Set require_save to True if you want to save the default/generated
    value for a property, to protect against future changes.  E.g., we
    currently expect all comments to be 'text/plain' but in the future
    we may want to default to 'text/html'.  If we don't want the old
    comments to be interpreted as 'text/html', we would require that
    the content type be saved.

    change_hook, primer, settings_properties, and
    required_saved_properties are only options to get their defaults
    into our local scope.  Don't mess with them.

    Set mutable=True if:
      * default is a mutable
      * your generator function may return mutables
      * you set change_hook and might have mutable property values
    See the docstrings in libbe.properties for details on how each of
    these cases are handled.
    """
    settings_properties.append(name)
    if require_save == True:
        required_saved_properties.append(name)
    def decorator(funcs):
        fulldoc = doc
        if default != None or generator == None:
            defaulting  = defaulting_property(default=default, null=EMPTY,
                                              mutable_default=mutable)
            fulldoc += "\n\nThis property defaults to %s." % default
        if generator != None:
            cached = cached_property(generator=generator, initVal=EMPTY,
                                     mutable=mutable)
            fulldoc += "\n\nThis property is generated with %s." % generator
        if check_fn != None:
            fn_checked = fn_checked_property(value_allowed_fn=check_fn)
            fulldoc += "\n\nThis property is checked with %s." % check_fn
        if allowed != None:
            checked = checked_property(allowed=allowed)
            fulldoc += "\n\nThe allowed values for this property are: %s." \
                       % (', '.join(allowed))
        hooked      = change_hook_property(hook=change_hook, mutable=mutable,
                                           default=EMPTY)
        primed      = primed_property(primer=primer, initVal=UNPRIMED)
        settings    = settings_property(name=name, null=UNPRIMED)
        docp        = doc_property(doc=fulldoc)
        deco = hooked(primed(settings(docp(funcs))))
        if default != None or generator == None:
            deco = defaulting(deco)
        if generator != None:
            deco = cached(deco)
        if check_fn != None:
            deco = fn_checked(deco)
        if allowed != None:
            deco = checked(deco)
        return Property(deco)
    return decorator

class SavedSettingsObject(object):

    # Keep a list of properties that may be stored in the .settings dict.
    #settings_properties = []

    # A list of properties that we save to disk, even if they were
    # never set (in which case we save the default value).  This
    # protects against future changes in default values.
    #required_saved_properties = []

    _setting_name_to_attr_name = setting_name_to_attr_name
    _attr_name_to_setting_name = attr_name_to_setting_name

    def __init__(self):
        self._settings_loaded = False
        self.storage = None
        self.settings = {}

    def load_settings(self):
        """Load the settings from disk."""
        # Override.  Must call ._setup_saved_settings() after loading.
        self.settings = {}
        self._setup_saved_settings()

    def _setup_saved_settings(self, flag_as_loaded=True):
        """
        To be run after setting self.settings up from disk.  Marks all
        settings as primed.
        """
        for property in self.settings_properties:
            if property not in self.settings:
                self.settings[property] = EMPTY
            elif self.settings[property] == UNPRIMED:
                self.settings[property] = EMPTY
        if flag_as_loaded == True:
            self._settings_loaded = True

    def save_settings(self):
        """Load the settings from disk."""
        # Override.  Should save the dict output of ._get_saved_settings()
        settings = self._get_saved_settings()
        pass # write settings to disk....

    def _get_saved_settings(self):
        settings = {}
        for k,v in self.settings.items():
            if v != None and v != EMPTY:
                settings[k] = v
        for k in self.required_saved_properties:
            settings[k] = getattr(self, self._setting_name_to_attr_name(k))
        return settings

    def clear_cached_setting(self, setting=None):
        "If setting=None, clear *all* cached settings"
        if setting != None:
            if hasattr(self, "_%s_cached_value" % setting):
                delattr(self, "_%s_cached_value" % setting)
        else:
            for setting in settings_properties:
                self.clear_cached_setting(setting)


if libbe.TESTING == True:
    class SavedSettingsObjectTests(unittest.TestCase):
        def testSimpleProperty(self):
            """Testing a minimal versioned property"""
            class Test(SavedSettingsObject):
                settings_properties = []
                required_saved_properties = []
                @versioned_property(name="Content-type",
                                    doc="A test property",
                                    settings_properties=settings_properties,
                                    required_saved_properties= \
                                        required_saved_properties)
                def content_type(): return {}
                def __init__(self):
                    SavedSettingsObject.__init__(self)
            t = Test()
            # access missing setting
            self.failUnless(t._settings_loaded == False, t._settings_loaded)
            self.failUnless(len(t.settings) == 0, len(t.settings))
            self.failUnless(t.content_type == None, t.content_type)
            # accessing t.content_type triggers the priming, which runs
            # t._setup_saved_settings, which fills out t.settings with
            # EMPTY data.  t._settings_loaded is still false though, since
            # the default priming does not do any of the `official' loading
            # that occurs in t.load_settings.
            self.failUnless(len(t.settings) == 1, len(t.settings))
            self.failUnless(t.settings["Content-type"] == EMPTY,
                            t.settings["Content-type"])
            self.failUnless(t._settings_loaded == False, t._settings_loaded)
            # load settings creates an EMPTY value in the settings array
            t.load_settings()
            self.failUnless(t._settings_loaded == True, t._settings_loaded)
            self.failUnless(t.settings["Content-type"] == EMPTY,
                            t.settings["Content-type"])
            self.failUnless(t.content_type == None, t.content_type)
            self.failUnless(len(t.settings) == 1, len(t.settings))
            self.failUnless(t.settings["Content-type"] == EMPTY,
                            t.settings["Content-type"])
            # now we set a value
            t.content_type = 5
            self.failUnless(t.settings["Content-type"] == 5,
                            t.settings["Content-type"])
            self.failUnless(t.content_type == 5, t.content_type)
            self.failUnless(t.settings["Content-type"] == 5,
                            t.settings["Content-type"])
            # now we set another value
            t.content_type = "text/plain"
            self.failUnless(t.content_type == "text/plain", t.content_type)
            self.failUnless(t.settings["Content-type"] == "text/plain",
                            t.settings["Content-type"])
            self.failUnless(t._get_saved_settings() == \
                                {"Content-type":"text/plain"},
                            t._get_saved_settings())
            # now we clear to the post-primed value
            t.content_type = EMPTY
            self.failUnless(t._settings_loaded == True, t._settings_loaded)
            self.failUnless(t.settings["Content-type"] == EMPTY,
                            t.settings["Content-type"])
            self.failUnless(t.content_type == None, t.content_type)
            self.failUnless(len(t.settings) == 1, len(t.settings))
            self.failUnless(t.settings["Content-type"] == EMPTY,
                            t.settings["Content-type"])
        def testDefaultingProperty(self):
            """Testing a defaulting versioned property"""
            class Test(SavedSettingsObject):
                settings_properties = []
                required_saved_properties = []
                @versioned_property(name="Content-type",
                                    doc="A test property",
                                    default="text/plain",
                                    settings_properties=settings_properties,
                                    required_saved_properties= \
                                        required_saved_properties)
                def content_type(): return {}
                def __init__(self):
                    SavedSettingsObject.__init__(self)
            t = Test()
            self.failUnless(t._settings_loaded == False, t._settings_loaded)
            self.failUnless(t.content_type == "text/plain", t.content_type)
            self.failUnless(t._settings_loaded == False, t._settings_loaded)
            t.load_settings()
            self.failUnless(t._settings_loaded == True, t._settings_loaded)
            self.failUnless(t.content_type == "text/plain", t.content_type)
            self.failUnless(t.settings["Content-type"] == EMPTY,
                            t.settings["Content-type"])
            self.failUnless(t._get_saved_settings() == {},
                            t._get_saved_settings())
            t.content_type = "text/html"
            self.failUnless(t.content_type == "text/html",
                            t.content_type)
            self.failUnless(t.settings["Content-type"] == "text/html",
                            t.settings["Content-type"])
            self.failUnless(t._get_saved_settings() == \
                                {"Content-type":"text/html"},
                            t._get_saved_settings())
        def testRequiredDefaultingProperty(self):
            """Testing a required defaulting versioned property"""
            class Test(SavedSettingsObject):
                settings_properties = []
                required_saved_properties = []
                @versioned_property(name="Content-type",
                                    doc="A test property",
                                    default="text/plain",
                                    settings_properties=settings_properties,
                                    required_saved_properties= \
                                        required_saved_properties,
                                    require_save=True)
                def content_type(): return {}
                def __init__(self):
                    SavedSettingsObject.__init__(self)
            t = Test()
            self.failUnless(t._get_saved_settings() == \
                                {"Content-type":"text/plain"},
                            t._get_saved_settings())
            t.content_type = "text/html"
            self.failUnless(t._get_saved_settings() == \
                                {"Content-type":"text/html"},
                            t._get_saved_settings())
        def testClassVersionedPropertyDefinition(self):
            """Testing a class-specific _versioned property decorator"""
            class Test(SavedSettingsObject):
                settings_properties = []
                required_saved_properties = []
                def _versioned_property(settings_properties= \
                                            settings_properties,
                                        required_saved_properties= \
                                            required_saved_properties,
                                        **kwargs):
                    if "settings_properties" not in kwargs:
                        kwargs["settings_properties"] = settings_properties
                    if "required_saved_properties" not in kwargs:
                        kwargs["required_saved_properties"] = \
                            required_saved_properties
                    return versioned_property(**kwargs)
                @_versioned_property(name="Content-type",
                                    doc="A test property",
                                    default="text/plain",
                                    require_save=True)
                def content_type(): return {}
                def __init__(self):
                    SavedSettingsObject.__init__(self)
            t = Test()
            self.failUnless(t._get_saved_settings() == \
                                {"Content-type":"text/plain"},
                            t._get_saved_settings())
            t.content_type = "text/html"
            self.failUnless(t._get_saved_settings() == \
                                {"Content-type":"text/html"},
                            t._get_saved_settings())
        def testMutableChangeHookedProperty(self):
            """Testing a mutable change-hooked property"""
            SAVES = []
            def prop_log_save_settings(self, old, new, saves=SAVES):
                saves.append("'%s' -> '%s'" % (str(old), str(new)))
                prop_save_settings(self, old, new)
            class Test(SavedSettingsObject):
                settings_properties = []
                required_saved_properties = []
                @versioned_property(name="List-type",
                                    doc="A test property",
                                    mutable=True,
                                    change_hook=prop_log_save_settings,
                                    settings_properties=settings_properties,
                                    required_saved_properties= \
                                        required_saved_properties)
                def list_type(): return {}
                def __init__(self):
                    SavedSettingsObject.__init__(self)
            t = Test()
            self.failUnless(t._settings_loaded == False, t._settings_loaded)
            t.load_settings()
            self.failUnless(SAVES == [], SAVES)
            self.failUnless(t._settings_loaded == True, t._settings_loaded)
            self.failUnless(t.list_type == None, t.list_type)
            self.failUnless(SAVES == [], SAVES)
            self.failUnless(t.settings["List-type"]==EMPTY,
                            t.settings["List-type"])
            t.list_type = []
            self.failUnless(t.settings["List-type"] == [],
                            t.settings["List-type"])
            self.failUnless(SAVES == [
                    "'<class 'libbe.storage.settings_object.EMPTY'>' -> '[]'"
                    ], SAVES)
            t.list_type.append(5)
            self.failUnless(SAVES == [
                    "'<class 'libbe.storage.settings_object.EMPTY'>' -> '[]'",
                    ], SAVES)
            self.failUnless(t.settings["List-type"] == [5],
                            t.settings["List-type"])
            self.failUnless(SAVES == [ # the append(5) has not yet been saved
                    "'<class 'libbe.storage.settings_object.EMPTY'>' -> '[]'",
                    ], SAVES)
            self.failUnless(t.list_type == [5], t.list_type)#get triggers saved

            self.failUnless(SAVES == [ # now the append(5) has been saved.
                    "'<class 'libbe.storage.settings_object.EMPTY'>' -> '[]'",
                    "'[]' -> '[5]'"
                    ], SAVES)

    unitsuite = unittest.TestLoader().loadTestsFromTestCase( \
        SavedSettingsObjectTests)
    suite = unittest.TestSuite([unitsuite, doctest.DocTestSuite()])