Storm

Merge lp:~cjwatson/storm/docstring-properties into lp:storm

  1. docstring-properties
  2. Merge into trunk
Proposed by Colin Watson
Status: Merged
Merged at revision: 560
Proposed branch: lp:~cjwatson/storm/docstring-properties
Merge into: lp:storm
Diff against target: 220 lines (+146/-1)
1 file modified
storm/properties.py (+146/-1)
To merge this branch: bzr merge lp:~cjwatson/storm/docstring-properties
Reviewer Review Type Date Requested Status
Ioana Lasc (community) Approve
Storm Developers Pending
Review via email: mp+384558@code.launchpad.net

Commit message

Add docstrings for more classes in storm.properties.

To post a comment you must log in.
Revision history for this message
Ioana Lasc (ilasc) :
review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'storm/properties.py'
2--- storm/properties.py 2020-02-10 15:30:23 +0000
3+++ storm/properties.py 2020-05-26 16:31:09 +0000
4@@ -42,9 +42,24 @@
5
6
7 class Property(object):
8+ """A property representing a database column.
9+
10+ Properties can be set as attributes of classes that have a
11+ C{__storm_table__}, and can then be used like ordinary Python properties
12+ on instances of the class, corresponding to database columns.
13+ """
14
15 def __init__(self, name=None, primary=False,
16 variable_class=Variable, variable_kwargs={}):
17+ """
18+ @param name: The name of this property.
19+ @param primary: A boolean indicating whether this property is a
20+ primary key.
21+ @param variable_class: The type of L{storm.variables.Variable}
22+ corresponding to this property.
23+ @param variable_kwargs: Dictionary of keyword arguments to be passed
24+ when constructing the underlying variable.
25+ """
26 self._name = name
27 self._primary = primary
28 self._variable_class = variable_class
29@@ -130,60 +145,190 @@
30 variable_class = None
31
32 def __init__(self, name=None, primary=False, **kwargs):
33+ """
34+ @param name: The name of this property.
35+ @param primary: A boolean indicating whether this property is a
36+ primary key.
37+ @param default: The initial value of this variable. The default
38+ behavior is for the value to stay undefined until it is
39+ set with L{set}.
40+ @param default_factory: If specified, this will immediately be
41+ called to get the initial value.
42+ @param allow_none: A boolean indicating whether None should be
43+ allowed to be set as the value of this variable.
44+ @param validator: Validation function called whenever trying to
45+ set the variable to a non-db value. The function should
46+ look like validator(object, attr, value), where the first and
47+ second arguments are the result of validator_object_factory()
48+ (or None, if this parameter isn't provided) and the value of
49+ validator_attribute, respectively. When called, the function
50+ should raise an error if the value is unacceptable, or return
51+ the value to be used in place of the original value otherwise.
52+ @param kwargs: Other keyword arguments passed through when
53+ constructing the underlying variable.
54+ """
55 kwargs["value"] = kwargs.pop("default", Undef)
56 kwargs["value_factory"] = kwargs.pop("default_factory", Undef)
57 Property.__init__(self, name, primary, self.variable_class, kwargs)
58
59
60 class Bool(SimpleProperty):
61+ """Boolean property.
62+
63+ This accepts integer, L{float}, or L{decimal.Decimal} values, and stores
64+ them as booleans.
65+ """
66 variable_class = BoolVariable
67-
68+
69+
70 class Int(SimpleProperty):
71+ """Integer property.
72+
73+ This accepts integer, L{float}, or L{decimal.Decimal} values, and stores
74+ them as integers.
75+ """
76 variable_class = IntVariable
77
78+
79 class Float(SimpleProperty):
80+ """Float property.
81+
82+ This accepts integer, L{float}, or L{decimal.Decimal} values, and stores
83+ them as floating-point values.
84+ """
85 variable_class = FloatVariable
86
87+
88 class Decimal(SimpleProperty):
89+ """Decimal property.
90+
91+ This accepts integer or L{decimal.Decimal} values, and stores them as
92+ text strings containing their decimal representation.
93+ """
94 variable_class = DecimalVariable
95
96+
97 class Bytes(SimpleProperty):
98+ """Bytes property.
99+
100+ This accepts L{bytes}, L{buffer} (Python 2), or L{memoryview} (Python 3)
101+ objects, and stores them as byte strings.
102+
103+ Deprecated aliases: L{Chars}, L{RawStr}.
104+ """
105 variable_class = BytesVariable
106
107+
108 # OBSOLETE: Bytes was Chars in 0.9. This will die soon.
109 Chars = Bytes
110 # DEPRECATED: Bytes was RawStr until 0.22.
111 RawStr = Bytes
112
113+
114 class Unicode(SimpleProperty):
115+ """Unicode property.
116+
117+ This accepts L{unicode} (Python 2) or L{str} (Python 3) objects, and
118+ stores them as text strings. Note that it does not accept L{str}
119+ objects on Python 2.
120+ """
121 variable_class = UnicodeVariable
122
123+
124 class DateTime(SimpleProperty):
125+ """Date and time property.
126+
127+ This accepts aware L{datetime.datetime} objects and stores them as
128+ timestamps; it also accepts integer or L{float} objects, converting them
129+ using L{datetime.utcfromtimestamp}. Note that it does not accept naive
130+ L{datetime.datetime} objects (those that do not have timezone
131+ information).
132+ """
133 variable_class = DateTimeVariable
134
135+
136 class Date(SimpleProperty):
137+ """Date property.
138+
139+ This accepts L{datetime.date} objects and stores them as datestamps; it
140+ also accepts L{datetime.datetime} objects, converting them using
141+ L{datetime.datetime.date}.
142+ """
143 variable_class = DateVariable
144
145+
146 class Time(SimpleProperty):
147+ """Time property.
148+
149+ This accepts L{datetime.time} objects and stores them as datestamps; it
150+ also accepts L{datetime.datetime} objects, converting them using
151+ L{datetime.datetime.time}.
152+ """
153 variable_class = TimeVariable
154
155+
156 class TimeDelta(SimpleProperty):
157+ """Time delta property.
158+
159+ This accepts L{datetime.timedelta} objects and stores them as time
160+ intervals.
161+ """
162 variable_class = TimeDeltaVariable
163
164+
165 class UUID(SimpleProperty):
166+ """UUID property.
167+
168+ This accepts L{uuid.UUID} objects and stores them as their text
169+ representation.
170+ """
171 variable_class = UUIDVariable
172
173+
174 class Pickle(SimpleProperty):
175+ """Pickle property.
176+
177+ This accepts any object that can be serialized using L{pickle}, and
178+ stores it as a byte string containing its pickled representation.
179+ """
180 variable_class = PickleVariable
181
182+
183 class JSON(SimpleProperty):
184+ """JSON property.
185+
186+ This accepts any object that can be serialized using L{json}, and stores
187+ it as a text string containing its JSON representation.
188+ """
189 variable_class = JSONVariable
190
191
192 class List(SimpleProperty):
193+ """List property.
194+
195+ This accepts iterable objects and stores them as a list where each
196+ element is an object of the given value type.
197+ """
198 variable_class = ListVariable
199
200 def __init__(self, name=None, **kwargs):
201+ """
202+ @param name: The name of this property.
203+ @param type: An instance of L{Property} defining the type of each
204+ element of this list.
205+ @param default_factory: If specified, this will immediately be
206+ called to get the initial value.
207+ @param validator: Validation function called whenever trying to
208+ set the variable to a non-db value. The function should
209+ look like validator(object, attr, value), where the first and
210+ second arguments are the result of validator_object_factory()
211+ (or None, if this parameter isn't provided) and the value of
212+ validator_attribute, respectively. When called, the function
213+ should raise an error if the value is unacceptable, or return
214+ the value to be used in place of the original value otherwise.
215+ @param kwargs: Other keyword arguments passed through when
216+ constructing the underlying variable.
217+ """
218 if "default" in kwargs:
219 raise ValueError("'default' not allowed for List. "
220 "Use 'default_factory' instead.")

Subscribers

People subscribed via source and target branches

to status/vote changes: