Merge branch 'encukou-markdown-identifiers'
[zzz-pokedex.git] / pokedex / db / multilang.py
1 from functools import partial
2
3 from sqlalchemy.ext.associationproxy import association_proxy
4 from sqlalchemy.orm import aliased, compile_mappers, mapper, relationship, synonym
5 from sqlalchemy.orm.collections import attribute_mapped_collection
6 from sqlalchemy.orm.scoping import ScopedSession
7 from sqlalchemy.orm.session import Session, object_session
8 from sqlalchemy.schema import Column, ForeignKey, Table
9 from sqlalchemy.sql.expression import and_, bindparam, select
10 from sqlalchemy.types import Integer
11
12 def create_translation_table(_table_name, foreign_class, relation_name,
13 language_class, relation_lazy='select', **kwargs):
14 """Creates a table that represents some kind of data attached to the given
15 foreign class, but translated across several languages. Returns the new
16 table's mapped class. It won't be declarative, but it will have a
17 `__table__` attribute so you can retrieve the Table object.
18
19 `foreign_class` must have a `__singlename__`, currently only used to create
20 the name of the foreign key column.
21
22 Also supports the notion of a default language, which is attached to the
23 session. This is English by default, for historical and practical reasons.
24
25 Usage looks like this:
26
27 class Foo(Base): ...
28
29 create_translation_table('foo_bars', Foo, 'bars',
30 name = Column(...),
31 )
32
33 # Now you can do the following:
34 foo.name
35 foo.name_map['en']
36 foo.foo_bars['en']
37
38 foo.name_map['en'] = "new name"
39 del foo.name_map['en']
40
41 q.options(joinedload(Foo.bars_local))
42 q.options(joinedload(Foo.bars))
43
44 The following properties are added to the passed class:
45
46 - `(relation_name)`, a relation to the new table. It uses a dict-based
47 collection class, where the keys are language identifiers and the values
48 are rows in the created tables.
49 - `(relation_name)_local`, a relation to the row in the new table that
50 matches the current default language.
51 - `(relation_name)_class`, the class created by this function.
52
53 Note that these are distinct relations. Even though the former necessarily
54 includes the latter, SQLAlchemy doesn't treat them as linked; loading one
55 will not load the other. Modifying both within the same transaction has
56 undefined behavior.
57
58 For each column provided, the following additional attributes are added to
59 Foo:
60
61 - `(column)_map`, an association proxy onto `foo_bars`.
62 - `(column)`, an association proxy onto `foo_bars_local`.
63
64 Pardon the naming disparity, but the grammar suffers otherwise.
65
66 Modifying these directly is not likely to be a good idea.
67 """
68 # n.b.: language_class only exists for the sake of tests, which sometimes
69 # want to create tables entirely separate from the pokedex metadata
70
71 foreign_key_name = foreign_class.__singlename__ + '_id'
72
73 Translations = type(_table_name, (object,), {
74 '_language_identifier': association_proxy('local_language', 'identifier'),
75 })
76
77 # Create the table object
78 table = Table(_table_name, foreign_class.__table__.metadata,
79 Column(foreign_key_name, Integer, ForeignKey(foreign_class.id),
80 primary_key=True, nullable=False,
81 info=dict(description="ID of the %s these texts relate to" % foreign_class.__singlename__)),
82 Column('local_language_id', Integer, ForeignKey(language_class.id),
83 primary_key=True, nullable=False,
84 info=dict(description="Language these texts are in")),
85 )
86 Translations.__table__ = table
87
88 # Add ye columns
89 # Column objects have a _creation_order attribute in ascending order; use
90 # this to get the (unordered) kwargs sorted correctly
91 kwitems = kwargs.items()
92 kwitems.sort(key=lambda kv: kv[1]._creation_order)
93 for name, column in kwitems:
94 column.name = name
95 table.append_column(column)
96
97 # Construct ye mapper
98 mapper(Translations, table, properties={
99 'foreign_id': synonym(foreign_key_name),
100 'local_language': relationship(language_class,
101 primaryjoin=table.c.local_language_id == language_class.id,
102 innerjoin=True,
103 lazy='joined'),
104 })
105
106 # Add full-table relations to the original class
107 # Foo.bars_table
108 setattr(foreign_class, relation_name + '_table', Translations)
109 # Foo.bars
110 setattr(foreign_class, relation_name, relationship(Translations,
111 primaryjoin=foreign_class.id == Translations.foreign_id,
112 collection_class=attribute_mapped_collection('local_language'),
113 ))
114 # Foo.bars_local
115 # This is a bit clever; it uses bindparam() to make the join clause
116 # modifiable on the fly. db sessions know the current language and
117 # populate the bindparam.
118 # The 'dummy' value is to trick SQLA; without it, SQLA thinks this
119 # bindparam is just its own auto-generated clause and everything gets
120 # fucked up.
121 local_relation_name = relation_name + '_local'
122 setattr(foreign_class, local_relation_name, relationship(Translations,
123 primaryjoin=and_(
124 Translations.foreign_id == foreign_class.id,
125 Translations.local_language_id == bindparam('_default_language_id',
126 value='dummy', type_=Integer, required=True),
127 ),
128 foreign_keys=[Translations.foreign_id, Translations.local_language_id],
129 uselist=False,
130 #innerjoin=True,
131 lazy=relation_lazy,
132 ))
133
134 # Add per-column proxies to the original class
135 for name, column in kwitems:
136 # Class.(column) -- accessor for the default language's value
137 setattr(foreign_class, name,
138 association_proxy(local_relation_name, name))
139
140 # Class.(column)_map -- accessor for the language dict
141 # Need a custom creator since Translations doesn't have an init, and
142 # these are passed as *args anyway
143 def creator(language, value):
144 row = Translations()
145 row.local_language = language
146 setattr(row, name, value)
147 return row
148 setattr(foreign_class, name + '_map',
149 association_proxy(relation_name, name, creator=creator))
150
151 # Add to the list of translation classes
152 foreign_class.translation_classes.append(Translations)
153
154 # Done
155 return Translations
156
157 class MultilangSession(Session):
158 """A tiny Session subclass that adds support for a default language.
159
160 Needs to be used with `MultilangScopedSession`, below.
161 """
162 default_language_id = None
163
164 def __init__(self, *args, **kwargs):
165 if 'default_language_id' in kwargs:
166 self.default_language_id = kwargs.pop('default_language_id')
167
168 super(MultilangSession, self).__init__(*args, **kwargs)
169
170 def execute(self, clause, params=None, *args, **kwargs):
171 if not params:
172 params = {}
173 params.setdefault('_default_language_id', self.default_language_id)
174
175 return super(MultilangSession, self).execute(
176 clause, params, *args, **kwargs)
177
178 class MultilangScopedSession(ScopedSession):
179 """Dispatches language selection to the attached Session."""
180
181 def __init__(self, *args, **kwargs):
182 super(MultilangScopedSession, self).__init__(*args, **kwargs)
183
184 @property
185 def default_language_id(self):
186 """Passes the new default language id through to the current session.
187 """
188 return self.registry().default_language_id
189
190 @default_language_id.setter
191 def default_language_id(self, new):
192 self.registry().default_language_id = new