Storm

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

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

Commit message

Add more docstrings to storm.references.

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/references.py'
2--- storm/references.py 2020-05-26 10:37:54 +0000
3+++ storm/references.py 2020-05-26 16:33:23 +0000
4@@ -105,6 +105,9 @@
5 Assigning to the property, for example with C{MyGuy().other_guy =
6 OtherGuy()}, will link the objects and update either
7 C{MyGuy.other_guy_id} or C{OtherGuy.my_guy_id} accordingly.
8+
9+ String references may be used in place of L{storm.expr.Column} objects
10+ throughout, and are resolved to columns using L{PropertyResolver}.
11 """
12
13 # Must initialize _relation later because we don't want to resolve
14@@ -214,6 +217,47 @@
15
16
17 class ReferenceSet(object):
18+ """Descriptor for many-to-one and many-to-many reference sets.
19+
20+ This is typically used when another class has a foreign key onto the
21+ class being defined, either directly (the many-to-one case) or via an
22+ intermediate table (the many-to-many case). For instance::
23+
24+ class Person(Storm):
25+ ...
26+ id = Int(primary=True)
27+ email_addresses = ReferenceSet("id", "EmailAddress.owner_id")
28+
29+ class EmailAddress(Storm):
30+ ...
31+ owner_id = Int(name="owner", allow_none=False)
32+ owner = Reference(owner_id, "Person.id")
33+
34+ class TeamMembership(Storm):
35+ ...
36+ person_id = Int(name="person", allow_none=False)
37+ person = Reference(person_id, "Person.id")
38+ team_id = Int(name="team", allow_none=False)
39+ team = Reference(team_id, "Team.id")
40+
41+ class Team(Storm):
42+ ...
43+ id = Int(primary=True)
44+ members = ReferenceSet(
45+ "id", "TeamMembership.team_id",
46+ "TeamMembership.person_id", "Person.id",
47+ order_by="Person.name")
48+
49+ In this case, C{Person().email_addresses} resolves to a
50+ L{BoundReferenceSet} of all the email addresses linked to that person (a
51+ many-to-one relationship), while C{Team().members} resolves to a
52+ L{BoundIndirectReferenceSet} of all the members of that team (a
53+ many-to-many relationship). These can be used in a somewhat similar way
54+ to L{ResultSet <storm.store.ResultSet>} objects.
55+
56+ String references may be used in place of L{storm.expr.Column} objects
57+ throughout, and are resolved to columns using L{PropertyResolver}.
58+ """
59
60 # Must initialize later because we don't want to resolve string
61 # references at definition time, since classes refered to might
62@@ -224,6 +268,23 @@
63
64 def __init__(self, local_key1, remote_key1,
65 remote_key2=None, local_key2=None, order_by=None):
66+ """
67+ @param local_key1: The sibling column which has the same value as
68+ that for C{remote_key1} when resolved on an instance.
69+ @param remote_key1: The column on the referring object (in the case
70+ of a many-to-one relation) or on the intermediate table (in the
71+ case of a many-to-many relation) which is the foreign key onto
72+ C{local_key1}.
73+ @param remote_key2: In the case of a many-to-many relation, the
74+ column on the intermediate table which is the foreign key onto
75+ C{local_key2}.
76+ @param local_key2: In the case of a many-to-many relation, the
77+ column on the referred-to object which has the same value as
78+ C{remote_key2} when resolved on an instance.
79+ @param order_by: If not C{None}, order the resolved
80+ L{BoundReferenceSet} or L{BoundIndirectReferenceSet} by these
81+ columns, as in L{storm.store.ResultSet.order_by}.
82+ """
83 self._local_key1 = local_key1
84 self._remote_key1 = remote_key1
85 self._remote_key2 = remote_key2
86@@ -254,7 +315,7 @@
87 self._order_by)
88
89 def __set__(self, local, value):
90- raise FeatureError("Assigning to ResultSets not supported")
91+ raise FeatureError("Assigning to ReferenceSets not supported")
92
93 def _build_relations(self):
94 resolver = PropertyResolver(self, self._cls)
95@@ -325,6 +386,7 @@
96
97
98 class BoundReferenceSet(BoundReferenceSetBase):
99+ """An instance of a many-to-one relation."""
100
101 def __init__(self, relation, local, order_by):
102 self._relation = relation
103@@ -354,6 +416,7 @@
104
105
106 class BoundIndirectReferenceSet(BoundReferenceSetBase):
107+ """An instance of a many-to-many relation."""
108
109 def __init__(self, relation1, relation2, local, order_by):
110 self._relation1 = relation1

Subscribers

People subscribed via source and target branches

to status/vote changes: