tut

Storm（Python对象关系映射库）官方教程简体中文翻译版

最后更新自:2010.12.26

索引

跑起来再说！
载入
基本定义
创建一个数据库以及仓库(store)
创建对象
对象的仓库
对象的查找
缓存特性
刷新
改变仓库中的对象
提交
回滚
构造函数
引用和继承
多对一引用集合
多对多引用集合以及组合键(composed keys)
联接(Joins)
子查询
排序以及限制(limiting)结果
多类型查询
Storm基类
载入钩子
执行表达式
自动重载(reloading)值
表达式的值
别名
调试
更多！

跑起来再说！

这份Storm教程包含在源代码tests/tutorial.txt当中，因此它会被测试并保持更新。

Ubuntu的Storm包由Storm团队提供：

sudo apt-add-repository ppa:storm/ppa
sudo apt-get update
sudo apt-get install python-storm

载入

让我们从往命名空间(namespace)载入一些名字(names)开始。

1 >>> from storm.locals import *
2 >>>

基本定义

现在，我们定义一种用几项属性来描述信息的类型(type)，用它来作映射。

1 >>> class Person(object):
2 ... __storm_table__ = "person"
3 ... id = Int(primary=True)
4 ... name = Unicode()

注意，这个定义没有使用任何Storm定义的base类或构造函数。

创建一个数据库以及仓库(store)

我们还是什么都没讲到，因此，让我们来定义一个储存在内存中的SQLite数据库，以及使用该数据库的仓库来玩玩。

1 >>> database = create_database("sqlite:")
2 >>> store = Store(database)
3 >>>

目前，有三种数据库被支持：SQLite，MySQL以及PostgreSQL。create_database()接受URI作为参数，就像这样：

database = create_database("scheme://username:password@hostname:port/database_name")

其中的scheme可以是“sqlite”，“postgres”，或“mysql”。

现在我们要创建一个表，将该表用来保存我们类中的数据。

1 >>> store.execute("CREATE TABLE person "
2 ... "(id INTEGER PRIMARY KEY, name VARCHAR)")
3 <storm.databases.sqlite.SQLiteResult object at 0x...>>

我们得到了一个结果(result)，不过现在不必关心它。通过使用noresult=True，我们也可以省略所有结果。

创建对象

让我们通过前面定义的类来创建对象。

1 >>> joe = Person()
2 >>> joe.name = u"Joe Johnes"
3
4 >>> print "%r, %r" % (joe.id, joe.name)
5 None, u'Joe Johnes'

到目前为止，这个对象都还没有连接到数据库。现在，让我们将它加入到前面创建的仓库当中。

1 >>> store.add(joe)
2 <Person object at 0x...>
3
4 >>> print "%r, %r" % (joe.id, joe.name)
5 None, u'Joe Johnes'

请注意，这个对象并没有任何改变，即便是被加入到仓库之后——这是因为它还没有刷新呢。

对象的仓库

一旦对象被加入到仓库，或从仓库中被检索，它和仓库的关系就明了了。我们也可以很容易地验证对象绑定到了哪一个仓库。

>>> Store.of(joe) is store
True

>>> Store.of(Person()) is None
True

对象的查找

现在，如果我们向仓库查询名为Joe Johnes的人，会发生什么事？

1 >>> person = store.find(Person, Person.name == u"Joe Johnes").one()
2
3 >>> print "%r, %r" % (person.id, person.name)
4 1, u'Joe Johnes'

Joe Johnes已经被仓库记录了！是的，就正如你所期待的一样。

我们还可以通过主键(primary key)来检索对象。

1 >>> store.get(Person, 1).name
2 u'Joe Johnes

缓存特性

有趣的是，person变量实际上就是joe，是吧？我们才刚刚添加了一个对象，所以应该只有一个Joe，为什么会有两个不同的对象呢？不是这样的。

1 >>> person is joe
2 True

事实上，每个仓库都一个对象缓存(cache)。当一个对象加入到仓库之后，在它被其他地方引用(reference)期间，仓库会尽可能地缓存它，直到该对象被污染(dirty，即有更改未被刷新)。

Storm保证至少有一定数目的最近使用对象被保存到内存中用以取代查询，因此频繁使用的对象就不必事无大小都检索数据库了。

刷新

当第一次试图在数据库中查找Joe的时候，我们神奇地发现属性id已经被赋值了。这是因为对象已经被隐含地(implicitly)刷新了，也就是说，某些行为也会导致之前的改动操作(changes)生效。

刷新也可以强制地(explicitly)发生。

1 >>> mary = Person()
2 >>> mary.name = u"Mary Margaret"
3 >>> store.add(mary)
4 <Person object at 0x...>
5
6 >>> print "%r, %r" % (mary.id, mary.name)
7 None, u'Mary Margaret'
8
9 >>> store.flush()
10 >>> print "%r, %r" % (mary.id, mary.name)
11 2, u'Mary Margaret'

改变仓库中的对象

正如往常修改对象一样，我们也可以通过使用表达式修改绑定了数据库的对象，并因此收益。

1 >>> store.find(Person, Person.name == u"Mary Margaret").set(name=u"Mary Maggie")
2 >>> mary.name
3 u'Mary Maggie'

此操作会修改数据库及内存中所有匹配对象。

提交

至今为止我们所做的一切都只是事务(transaction)。在这个点上，我们既可以通过提交(committing)操作，将之前未提交的改动操作都执行，又或者，我们可以通过回滚(rolling)操作来取消它们。

让我们来提交它，这很简单：

1 >>> store.commit()
2 >>>

一目了然。一切还是像以前一样，但现在改动操作已经是板上钉钉了。

回滚

想要终止改动操作也是同样直观的。

1 >>> joe.name = u"Tom Thomas"
2 >>>

让我们在Storm的数据库中看看这种改动将会是什么样子。

1 >>> person = store.find(Person, Person.name == u"Tom Thomas").one()
2 >>> person is joe
3 True

一切如常，现在，魔术开始(音乐，起！）。

1 >>> store.rollback()
2 >>>

呃。。。啥事都没发生？

其实不然。Joe，他回来了！

1 >>> print "%r, %r" % (joe.id, joe.name)
2 1, u'Joe Johnes'

构造函数

我们研究“人”(Person类)已经够久了。现在，让我们在模型中增加一种新数据：公司(Company类)。我们将在“公司”中使用构造函数，因为这会比较好玩。这将是你所见过的最简单的公司类：

1 >>> class Company(object):
2 ... __storm_table__ = "company"
3 ... id = Int(primary=True)
4 ... name = Unicode()
5 ...
6 ... def __init__(self, name):
7 ... self.name = name

注意，构造函数的参数并非是可选的。如果你愿意，它也可以是可选的，但公司总得有个名字吧。

让我们为它添加表。

1 >>> store.execute("CREATE TABLE company "
2 ... "(id INTEGER PRIMARY KEY, name VARCHAR)", noresult=True)

然后，创建一个新公司。

>>> circus = Company(u"Circus Inc.")

>>> print "%r, %r" % (circus.id, circus.name)
None, u'Circus Inc.'

因为我们还没刷新，所以id仍然是未定义的。事实上，我们甚至还没有把“公司”加入到仓库中。我们马上就来做这事。看好了。

引用和继承

现在，我们希望指派一些雇员到我们的公司。与其重定义Person类，我们不如让其维持原状，因为它足够一般，我们创建一个它的子类作为雇员类，其中雇员类还有一个新加入的字段：公司的id。

1 >>> class Employee(Person):
2 ... __storm_table__ = "employee"
3 ... company_id = Int()
4 ... company = Reference(company_id, Company.id)
5 ...
6 ... def __init__(self, name):
7 ... self.name = name

注意上面的定义，它没有改写Person类原有的东西，而是引入了引用到其他类的两个属性：company_id和company。它也有构造函数，但里面并没有任何关于company的定义。

像往常一样，我们需要一个表。SQLite对外键(foreign key)没有太多想法，所以我们也懒得去定义它。

1 >>> store.execute("CREATE TABLE employee "
2 ... "(id INTEGER PRIMARY KEY, name VARCHAR, company_id INTEGER)",
3 ... noresult=True)

该让Ben闪亮登场了。

1 >>> ben = store.add(Employee(u"Ben Bill"))
2
3 >>> print "%r, %r, %r" % (ben.id, ben.name, ben.company_id)
4 None, u'Ben Bill', None

我们可以看到，以上内容还没有被刷新。即便如此，我们也可以断言Bill在马戏团(Circus)工作。

1 >>> ben.company = circus
2
3 >>> print "%r, %r" % (ben.company_id, ben.company.name)
4 None, u'Circus Inc.'

当然，在数据库刷新之前，我们仍然不知道公司id，也不显式地给他指定一个。即便如此，Storm还是能保持它们之间的关系。

如果有任何正在等待的操作被刷新到数据库中(无论是隐式或强制)，对象会获取它们的id，并保证在刷新之前，所有引用关系都可以顺利被更新。

1 >>> store.flush()
2
3 >>> print "%r, %r" % (ben.company_id, ben.company.name)
4 1, u'Circus Inc.'

它们都被刷新到数据库里面了。现在，请注意马戏团公司并没有强制地被加入到仓库。Storm会自动为引用和被引用对象双方完成该任务。

让我们创建另一家公司来检查一下。这一次，我们会在加入新公司之后立刻刷新。

1 >>> sweets = store.add(Company(u"Sweets Inc."))
2 >>> store.flush()
3 >>> sweets.id
4 2

不错，我们已经得到了新公司的id。那么，如果我们只改变Ben的公司的id，会怎么样？

1 >>> ben.company_id = 2
2 >>> ben.company.name
3 u'Sweets Inc.'
4 >>> ben.company is sweets
5 True

哈哈！没有料到吧？

让我们将所有改动都提交了吧。

1 >>> store.commit()
2 >>>

多对一引用集合

我们的模型表示，员工们只在一间公司工作(我们这里只设计平常人)，而公司当然可以有多个员工。在Storm中我们用引用集合(reference sets)表示它们。

我们不重新定义company类，而是将一个新特性(attribute)加给它。

1 >>> Company.employees = ReferenceSet(Company.id, Employee.company_id)
2 >>>

仅次而已，我们已经可以查看哪些员工在给定的公司工作。

1 >>> sweets.employees.count()
2 1
3
4 >>> for employee in sweets.employees:
5 ... print "%r, %r" % (employee.id, employee.name)
6 ... print employee is ben
7 ...
8 1, u'Ben Bill'
9 True

让我们创建另一名雇员，并将他加入到公司当中，这比在company类中设置employee要好（这听起来更好，至少）。

1 >>> mike = store.add(Employee(u"Mike Mayer"))
2 >>> sweets.employees.add(mike)
3 >>>

毋庸置疑，Mike现在已经是公司的职员了，这一情况也应该被反映在其他地方。

1 >>> mike.company_id
2 2
3
4 >>> mike.company is sweets
5 True

多对多引用集合以及组合键(composed keys)

我们还打算在模型中表示会计师。公司都有会计师，但会计师通常可以为多间公司服务，因此我们用多对多关系来表示它们。

让我们创建简单的类，用来表示会计师及其关系。

1 >>> class Accountant(Person):
2 ... __storm_table__ = "accountant"
3 ... def __init__(self, name):
4 ... self.name = name
5
6 >>> class CompanyAccountant(object):
7 ... __storm_table__ = "company_accountant"
8 ... __storm_primary__ = "company_id", "accountant_id"
9 ... company_id = Int()
10 ... accountant_id = Int()

嘿，我们刚刚定义了带组合键的类！

现在，让我们使用它在company类中定义多对多关系。再一次，我们将新属性塞进已有的对象当中。在编写类的时候定义这些属性也很简单。稍候我们会看到如何用别的方法做这事。

1 >>> Company.accountants = ReferenceSet(Company.id,
2 ... CompanyAccountant.company_id,
3 ... CompanyAccountant.accountant_id,
4 ... Accountant.id)

搞定！属性排列的先后顺序事关重大，但这里面的逻辑应该是一目了然的。

在这个点上，我们还缺一些表。

1 >>> store.execute("CREATE TABLE accountant "
2 ... "(id INTEGER PRIMARY KEY, name VARCHAR)", noresult=True)
3 ...
4
5 >>> store.execute("CREATE TABLE company_accountant "
6 ... "(company_id INTEGER, accountant_id INTEGER,"
7 ... " PRIMARY KEY (company_id, accountant_id))", noresult=True)

我们将一对会计夫妇登记到两个公司。

1 >>> karl = Accountant(u"Karl Kent")
2 >>> frank = Accountant(u"Frank Fourt")
3
4 >>> sweets.accountants.add(karl)
5 >>> sweets.accountants.add(frank)
6
7 >>> circus.accountants.add(frank)
8 >>>

大功告成！真的！请注意，我们甚至不必将它们添加到仓库，当它们链接到其他已经在仓库内的对象时，这已经被隐式地执行了，我们也无须宣告对象间的关系，因为那已经在引用对象集合中明晰了。

现在，让我们来验证一下。

>>> sweets.accountants.count()
2

>>> circus.accountants.count()
1

我们还没有显式地使用过CompanyAccountant对象，假如你好奇的话，也可以验证一下它。

1 >>> store.get(CompanyAccountant, (sweets.id, frank.id))
2 <CompanyAccountant object at 0x...>>

请注意，因为组合键的关系，我们往get()方法传递了一个元组(tuple)。

如果我们想知道会计师为哪些公司工作，我们可以很容易地定义一个反向(reversed)关系：

1 >>> Accountant.companies = ReferenceSet(Accountant.id,
2 ... CompanyAccountant.accountant_id,
3 ... CompanyAccountant.company_id,
4 ... Company.id)
5
6 >>> [company.name for company in frank.companies]
7 [u'Circus Inc.', u'Sweets Inc.']
8
9 >>> [company.name for company in karl.companies]
10 [u'Sweets Inc.']

联接(Joins)

既然已经有了一些不错的数据，让我们尝试做一些有趣的查询(queries)玩玩看。

先来检查看看哪些公司至少有一名叫Ben的员工。我们至少有两种方法可以做到这一点。

首先，使用隐式联接。

1 >>> result = store.find(Company,
2 ... Employee.company_id == Company.id,
3 ... Employee.name.like(u"Ben %"))
4 ...
5
6 >>> [company.name for company in result]
7 [u'Sweets Inc.']

然后，我们也可以做一个显式联接。这是Storm查询当中，映射复杂SQL联接的有趣之处。

1 >>> origin = [Company, Join(Employee, Employee.company_id == Company.id)]
2 >>> result = store.using(*origin).find(Company, Employee.name.like(u"Ben %"))
3
4 >>> [company.name for company in result]
5 [u'Sweets Inc.']

如果我们已经定义过公司，并且想知道公司内哪个员工名叫Ben，这再容易不过了。

1 >>> result = sweets.employees.find(Employee.name.like(u"Ben %"))
2
3 >>> [employee.name for employee in result]
4 [u'Ben Bill']

子查询

假设我们想找出所有不属于公司的会计，可以使用子查询。

1 >>> laura = Accountant(u"Laura Montgomery")
2 >>> store.add(laura)
3 <Accountant ...>
4
5 >>> subselect = Select(CompanyAccountant.accountant_id, distinct=True)
6 >>> result = store.find(Accountant, Not(Accountant.id.is_in(subselect)))
7 >>> result.one() is laura
8 True
9 >>>

排序以及限制(limiting)结果

排序和限制结果通常是这样那样工具的最简单而又最迫切的功能，所以我们希望它们能够既简单又易用，这是当然的了。

一行代码胜过千言万语，这里有几个例子，说明它是如何工作的：

>>> garry = store.add(Employee(u"Garry Glare"))

>>> result = store.find(Employee)

>>> [employee.name for employee in result.order_by(Employee.name)]
[u'Ben Bill', u'Garry Glare', u'Mike Mayer']

>>> [employee.name for employee in result.order_by(Desc(Employee.name))]
[u'Mike Mayer', u'Garry Glare', u'Ben Bill']

>>> [employee.name for employee in result.order_by(Employee.name)[:2]]
[u'Ben Bill', u'Garry Glare']

多类型查询

有时候，用一个查询检索多于一个对象也是蛮有趣的。想象一下，例如除了想知道哪个公司有名叫Ben的员工外，我们也想知道这名员工到底是何许人也。这可以用类似如下的查询来完成：

1 >>> result = store.find((Company, Employee),
2 ... Employee.company_id == Company.id,
3 ... Employee.name.like(u"Ben %"))
4
5 >>> [(company.name, employee.name) for company, employee in result]
6 [(u'Sweets Inc.', u'Ben Bill')]

Storm基类

到目前为止，我们已经用类和类的属性定义好了引用关系及引用集合。这一做法有一定优势，比如更易于调试，但也有一定缺点，比如因为类需要在本地范围(local scope)内被表示(be present)，可能会导致循环引用(circular import)情况。

为了避免那样的状况，Storm支持使用字符串化的方式，为类和属性名字(names)定义引用关系。这样做的唯一不便是，所有相关的类都必须继承Storm类。

让我们定义一些新的类来演示一下。为了揭示要点，我们将在类实际定义引用关系之前引用它们。

1 >>> class Country(Storm):
2 ... __storm_table__ = "country"
3 ... id = Int(primary=True)
4 ... name = Unicode()
5 ... currency_id = Int()
6 ... currency = Reference(currency_id, "Currency.id")
7
8 >>> class Currency(Storm):
9 ... __storm_table__ = "currency"
10 ... id = Int(primary=True)
11 ... symbol = Unicode()
12
13 >>> store.execute("CREATE TABLE country "
14 ... "(id INTEGER PRIMARY KEY, name VARCHAR, currency_id INTEGER)",
15 ... noresult=True)
16
17 >>> store.execute("CREATE TABLE currency "
18 ... "(id INTEGER PRIMARY KEY, symbol VARCHAR)", noresult=True)

现在，让我们看看它是否工作。

1 >>> real = store.add(Currency())
2 >>> real.id = 1
3 >>> real.symbol = u"BRL"
4
5 >>> brazil = store.add(Country())
6 >>> brazil.name = u"Brazil"
7 >>> brazil.currency_id = 1
8
9 >>> brazil.currency.symbol
10 u'BRL'

还有啥问题！？

载入钩子

Storm允许类定义几个不同的钩子，当某些事情发生时，它们就会采取行动。这里就有一个有趣的钩子：__storm_loaded__。

让我们定义Person的一个临时的子类，然后来测试一下它。

1 >>> class PersonWithHook(Person):
2 ... def __init__(self, name):
3 ... print "Creating %s" % name
4 ... self.name = name
5 ...
6 ... def __storm_loaded__(self):
7 ... print "Loaded %s" % self.name
8
9
10 >>> earl = store.add(PersonWithHook(u"Earl Easton"))
11 Creating Earl Easton
12
13 >>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()
14
15 >>> store.invalidate(earl)
16 >>> del earl
17 >>> import gc
18 >>> collected = gc.collect()
19
20 >>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()
21 Loaded Earl Easton

请注意，在第一次查找(find)的时候，没有返回结果，因为当时对象还只存在于内存和缓存中。然后，我们从Storm缓存中无效化(invalidated)对象，并触发垃圾回收以确保对象不在内存当中。在此之后，对象必须通过数据库被再次检索，钩子(不是构造函数！)也因此被调用。

执行表达式

Storm还提供了一种非数据库式(database-agnostic way)的方式来执行表达式，以备不时之需。

例如：

1 >>> result = store.execute(Select(Person.name, Person.id == 1))
2 >>> result.get_one()
3 (u'Joe Johnes',)

这一机制被Storm自身内部用以实现更高级功能。

自动重载(reloading)值

Storm提供了一些在它控制之下的特殊值，可以将它们赋给属性。其中一个特殊值就是AutoReload。启用它后，每次接触(touched)数据库，对象的值都将被自动重载。这对主键可能有用，就如下面的例子所示。

>>> from storm.locals import AutoReload

>>> ruy = store.add(Person())
>>> ruy.name = u"Ruy"
>>> print ruy.id
None

>>> ruy.id = AutoReload
>>> print ruy.id
4

当有需要时，可以将属性的默认值设为AutoReload，让对象实行自动刷新。

表达式的值

可以赋给属性的除了自动重载之外，还有“惰性表达式”。这种表达式只在属性被访问、或者当对象被刷新到数据库(插入/更新)时，才会被刷新到数据库。

例如：

1 from storm.locals import SQL
2
3 >>> ruy.name = SQL("(SELECT name || ? FROM person WHERE id=4)", (" Ritcher",))
4 >>> ruy.name
5 u'Ruy Ritcher'

请注意，这只是一个关于“可以做什么”的例子，并不是说非要这样写SQL语句不可。你可以用Storm提供的基于类的SQL表达式，把惰性表达式忘到九霄云外。

别名

现在，我们想要找出所有在同一家公司工作的人——我不知道到底是谁想这么干，但这是一个使用别名的好机会。

首先，我们要将ClassAlias引入到本地命名空间当中(友情提示：storm.local也应该被载入)，并且创建一个引用指向它。

1 >>> from storm.info import ClassAlias
2 >>> AnotherEmployee = ClassAlias(Employee)

它看上去不错，不是嘛？

现在，我们可以用一种简单直接的方式来查询：

1 >>> result = store.find((Employee, AnotherEmployee),
2 ... Employee.company_id == AnotherEmployee.company_id,
3 ... Employee.id > AnotherEmployee.id)
4
5 >>> for employee1, employee2 in result:
6 ... print (employee1.name, employee2.name)
7 (u'Mike Mayer', u'Ben Bill')

哇！Mike和Ben为同一家公司工作！

(考考你：为什么上面的查询里要使用大于号？)

调试

某些时候，你需查看Storm正在执行的语句。一个建立在Storm跟踪系统之上的调试跟踪器可以用来查看引擎盖下到底发生了什么事。跟踪器是一个对象，当有趣的事情发生——比如当Storm执行一个语句时，它会收到通知。提供了一个函数来开启和关闭语句跟踪语句。语句默认记录在sys.stderr之下，也可以自己指定一个流。

1 >>> import sys
2 >>> from storm.tracer import debug
3
4 >>> debug(True, stream=sys.stdout)
5 >>> result = store.find((Employee, AnotherEmployee),
6 ... Employee.company_id == AnotherEmployee.company_id,
7 ... Employee.id > AnotherEmployee.id)
8 >>> list(result)
9 EXECUTE: 'SELECT employee.company_id, employee.id, employee.name, "...".company_id, "...".id, "...".name FROM employee, employee AS "..." WHERE employee.company_id = "...".company_id AND employee.id > "...".id', ()
10 [(<Employee object at ...>, <Employee object at ...>)]
11
12 >>> debug(False)
13 >>> list(result)
14 [(<Employee object at ...>, <Employee object at ...>)]