« back to all changes in this revision
Viewing changes to storm/properties.py
- browse files at revision 560
- compare with another revision
- download diff
- download tarball
- view history from revision 560
- Committer: Colin Watson
- Date: 2020-05-28 12:11:30 UTC
- mfrom: (558.1.1 docstring-properties)
- Revision ID: cjwatson@canonical.com-20200528121130-9sj36quihnr4s06r
Add docstrings for more classes in storm.properties. [r=ilasc]
- files modified:
- storm/properties.py
added
removed
storm/properties.py
42
42
43
43
44
44
class Property(object):
45
"""A property representing a database column.
46
47
Properties can be set as attributes of classes that have a
48
C{__storm_table__}, and can then be used like ordinary Python properties
49
on instances of the class, corresponding to database columns.
50
"""
45
51
46
52
def __init__(self, name=None, primary=False,
47
53
variable_class=Variable, variable_kwargs={}):
54
"""
55
@param name: The name of this property.
56
@param primary: A boolean indicating whether this property is a
57
primary key.
58
@param variable_class: The type of L{storm.variables.Variable}
59
corresponding to this property.
60
@param variable_kwargs: Dictionary of keyword arguments to be passed
61
when constructing the underlying variable.
62
"""
48
63
self._name = name
49
64
self._primary = primary
50
65
self._variable_class = variable_class
130
145
variable_class = None
131
146
132
147
def __init__(self, name=None, primary=False, **kwargs):
148
"""
149
@param name: The name of this property.
150
@param primary: A boolean indicating whether this property is a
151
primary key.
152
@param default: The initial value of this variable. The default
153
behavior is for the value to stay undefined until it is
154
set with L{set}.
155
@param default_factory: If specified, this will immediately be
156
called to get the initial value.
157
@param allow_none: A boolean indicating whether None should be
158
allowed to be set as the value of this variable.
159
@param validator: Validation function called whenever trying to
160
set the variable to a non-db value. The function should
161
look like validator(object, attr, value), where the first and
162
second arguments are the result of validator_object_factory()
163
(or None, if this parameter isn't provided) and the value of
164
validator_attribute, respectively. When called, the function
165
should raise an error if the value is unacceptable, or return
166
the value to be used in place of the original value otherwise.
167
@param kwargs: Other keyword arguments passed through when
168
constructing the underlying variable.
169
"""
133
170
kwargs["value"] = kwargs.pop("default", Undef)
134
171
kwargs["value_factory"] = kwargs.pop("default_factory", Undef)
135
172
Property.__init__(self, name, primary, self.variable_class, kwargs)
136
173
137
174
138
175
class Bool(SimpleProperty):
176
"""Boolean property.
177
178
This accepts integer, L{float}, or L{decimal.Decimal} values, and stores
179
them as booleans.
180
"""
139
181
variable_class = BoolVariable
140
182
183
141
184
class Int(SimpleProperty):
185
"""Integer property.
186
187
This accepts integer, L{float}, or L{decimal.Decimal} values, and stores
188
them as integers.
189
"""
142
190
variable_class = IntVariable
143
191
192
144
193
class Float(SimpleProperty):
194
"""Float property.
195
196
This accepts integer, L{float}, or L{decimal.Decimal} values, and stores
197
them as floating-point values.
198
"""
145
199
variable_class = FloatVariable
146
200
201
147
202
class Decimal(SimpleProperty):
203
"""Decimal property.
204
205
This accepts integer or L{decimal.Decimal} values, and stores them as
206
text strings containing their decimal representation.
207
"""
148
208
variable_class = DecimalVariable
149
209
210
150
211
class Bytes(SimpleProperty):
212
"""Bytes property.
213
214
This accepts L{bytes}, L{buffer} (Python 2), or L{memoryview} (Python 3)
215
objects, and stores them as byte strings.
216
217
Deprecated aliases: L{Chars}, L{RawStr}.
218
"""
151
219
variable_class = BytesVariable
152
220
221
153
222
# OBSOLETE: Bytes was Chars in 0.9. This will die soon.
154
223
Chars = Bytes
155
224
# DEPRECATED: Bytes was RawStr until 0.22.
156
225
RawStr = Bytes
157
226
227
158
228
class Unicode(SimpleProperty):
229
"""Unicode property.
230
231
This accepts L{unicode} (Python 2) or L{str} (Python 3) objects, and
232
stores them as text strings. Note that it does not accept L{str}
233
objects on Python 2.
234
"""
159
235
variable_class = UnicodeVariable
160
236
237
161
238
class DateTime(SimpleProperty):
239
"""Date and time property.
240
241
This accepts aware L{datetime.datetime} objects and stores them as
242
timestamps; it also accepts integer or L{float} objects, converting them
243
using L{datetime.utcfromtimestamp}. Note that it does not accept naive
244
L{datetime.datetime} objects (those that do not have timezone
245
information).
246
"""
162
247
variable_class = DateTimeVariable
163
248
249
164
250
class Date(SimpleProperty):
251
"""Date property.
252
253
This accepts L{datetime.date} objects and stores them as datestamps; it
254
also accepts L{datetime.datetime} objects, converting them using
255
L{datetime.datetime.date}.
256
"""
165
257
variable_class = DateVariable
166
258
259
167
260
class Time(SimpleProperty):
261
"""Time property.
262
263
This accepts L{datetime.time} objects and stores them as datestamps; it
264
also accepts L{datetime.datetime} objects, converting them using
265
L{datetime.datetime.time}.
266
"""
168
267
variable_class = TimeVariable
169
268
269
170
270
class TimeDelta(SimpleProperty):
271
"""Time delta property.
272
273
This accepts L{datetime.timedelta} objects and stores them as time
274
intervals.
275
"""
171
276
variable_class = TimeDeltaVariable
172
277
278
173
279
class UUID(SimpleProperty):
280
"""UUID property.
281
282
This accepts L{uuid.UUID} objects and stores them as their text
283
representation.
284
"""
174
285
variable_class = UUIDVariable
175
286
287
176
288
class Pickle(SimpleProperty):
289
"""Pickle property.
290
291
This accepts any object that can be serialized using L{pickle}, and
292
stores it as a byte string containing its pickled representation.
293
"""
177
294
variable_class = PickleVariable
178
295
296
179
297
class JSON(SimpleProperty):
298
"""JSON property.
299
300
This accepts any object that can be serialized using L{json}, and stores
301
it as a text string containing its JSON representation.
302
"""
180
303
variable_class = JSONVariable
181
304
182
305
183
306
class List(SimpleProperty):
307
"""List property.
308
309
This accepts iterable objects and stores them as a list where each
310
element is an object of the given value type.
311
"""
184
312
variable_class = ListVariable
185
313
186
314
def __init__(self, name=None, **kwargs):
315
"""
316
@param name: The name of this property.
317
@param type: An instance of L{Property} defining the type of each
318
element of this list.
319
@param default_factory: If specified, this will immediately be
320
called to get the initial value.
321
@param validator: Validation function called whenever trying to
322
set the variable to a non-db value. The function should
323
look like validator(object, attr, value), where the first and
324
second arguments are the result of validator_object_factory()
325
(or None, if this parameter isn't provided) and the value of
326
validator_attribute, respectively. When called, the function
327
should raise an error if the value is unacceptable, or return
328
the value to be used in place of the original value otherwise.
329
@param kwargs: Other keyword arguments passed through when
330
constructing the underlying variable.
331
"""
187
332
if "default" in kwargs:
188
333
raise ValueError("'default' not allowed for List. "
189
334
"Use 'default_factory' instead.")
Loggerhead is a web-based interface for Breezy
Version: 2.0.1