tutorial.txt

Python的一个ORM,现在很火

Let's create another company to check something. This time we'll
flush the store just after adding it.

{{{#!python
>>> sweets = store.add(Company(u"Sweets Inc."))
>>> store.flush()
>>> sweets.id
2

}}}


Nice, we've already got the id of the new company. So, what would
happen if we changed '''just the id''' for Ben's company?

{{{#!python
>>> ben.company_id = 2
>>> ben.company.name
u'Sweets Inc.'
>>> ben.company is sweets
True

}}}

Hah! '''That''' wasn't expected, was it? ;-)

Let's commit everything.

{{{#!python
>>> store.commit()
>>>
}}}

==== Many-to-one reference sets ====

So, while our model says that employees work for a single company
(we only design normal people here), companies may of course have
multiple employees. We represent that in Storm using reference sets.

We won't define the company again. Instead, we'll add a new attribute
to the class.

{{{#!python
>>> Company.employees = ReferenceSet(Company.id, Employee.company_id)
>>> 
}}}

Without any further work, we can already see which employees are
working for a given company.

{{{#!python
>>> sweets.employees.count()
1

>>> for employee in sweets.employees:
...     print "%r, %r" % (employee.id, employee.name)
...     print employee is ben
...
1, u'Ben Bill'
True

}}}

Let's create another employee, and add him to the company, rather
than setting the company in the employee (it sounds better, at least).

{{{#!python
>>> mike = store.add(Employee(u"Mike Mayer"))
>>> sweets.employees.add(mike)
>>>
}}}

That, of course, means that Mike's working for a company, and so it
should be reflected elsewhere.

{{{#!python
>>> mike.company_id
2

>>> mike.company is sweets
True

}}}


==== Many-to-many reference sets and composed keys ====

We want to represent accountants in our model as well.  Companies have
accountants, but accountants may also attend several companies, so we'll
represent that using a many-to-many relationship.

Let's create a simple class to use with accountants, and the relationship
class.

{{{#!python
>>> class Accountant(Person):
...     __storm_table__ = "accountant"
...     def __init__(self, name):
...         self.name = name

>>> class CompanyAccountant(object):
...     __storm_table__ = "company_accountant"
...     __storm_primary__ = "company_id", "accountant_id"
...     company_id = Int()
...     accountant_id = Int()

}}}

Hey, we've just declared a class with a composed key!

Now, let's use it to declare the many-to-many relationship in the
company.  Once more, we'll just stick the new attribute in the
existent object.  It may easily be defined at class definition
time.  Later we'll see another way to do that as well.

{{{#!python
>>> Company.accountants = ReferenceSet(Company.id,
...                                    CompanyAccountant.company_id,
...                                    CompanyAccountant.accountant_id,
...                                    Accountant.id)

}}}

Done!  The order in which attributes were defined is important,
but the logic should be pretty obvious.

We're missing some tables, at this point.

{{{#!python
>>> store.execute("CREATE TABLE accountant "
...               "(id INTEGER PRIMARY KEY, name VARCHAR)", noresult=True)
...

>>> store.execute("CREATE TABLE company_accountant "
...               "(company_id INTEGER, accountant_id INTEGER,"
...               " PRIMARY KEY (company_id, accountant_id))", noresult=True)

}}}


Let's give life to a couple of accountants, and register them
in both companies.

{{{#!python
>>> karl = Accountant(u"Karl Kent")
>>> frank = Accountant(u"Frank Fourt")

>>> sweets.accountants.add(karl)
>>> sweets.accountants.add(frank)

>>> circus.accountants.add(frank)
>>>
}}}

That's it! Really!  Notice that we didn't even have to add them to
the store, since it happens implicitly by linking to the other object
which is already in the store, and that we didn't have to declare the
relationship object, since that's known to the reference set.

We can now check them.

{{{
>>> sweets.accountants.count()
2

>>> circus.accountants.count()
1

}}}

Even though we didn't use the Company``Accountant object explicitly,
we can check it if we're really curious.

{{{#!python
>>> store.get(CompanyAccountant, (sweets.id, frank.id))
<CompanyAccountant object at 0x...>

}}}

Notice that we pass a tuple for the `get()` method, due to the
composed key.

If we wanted to know for which companies accountants are working,
we could easily define a reversed relationship:

{{{#!python
>>> Accountant.companies = ReferenceSet(Accountant.id,
...                                     CompanyAccountant.accountant_id,
...                                     CompanyAccountant.company_id,
...                                     Company.id)

>>> [company.name for company in frank.companies]
[u'Circus Inc.', u'Sweets Inc.']

>>> [company.name for company in karl.companies]
[u'Sweets Inc.']

}}}


==== Joins ====

Since we've got some nice data to play with, let's try to make a
few interesting queries.

Let's start by checking which companies have at least one employee
named Ben.  We have at least two ways to do it.

First, with an implicit join.

{{{#!python
>>> result = store.find(Company,
...                     Employee.company_id == Company.id,
...                     Employee.name.like(u"Ben %"))
...

>>> [company.name for company in result]
[u'Sweets Inc.']

}}}

Then, we can also do an explicit join.  This is interesting for mapping
complex SQL joins to Storm queries.

{{{#!python
>>> origin = [Company, Join(Employee, Employee.company_id == Company.id)]
>>> result = store.using(*origin).find(Company, Employee.name.like(u"Ben %"))

>>> [company.name for company in result]
[u'Sweets Inc.']

}}}


If we already had the company, and wanted to know which of his employees
were named Ben, that'd have been easier.

{{{#!python
>>> result = sweets.employees.find(Employee.name.like(u"Ben %"))

>>> [employee.name for employee in result]
[u'Ben Bill']

}}}


==== The Storm base class ====

So far we've been defining our references and reference sets using
classes and their properties.  This has some advantages, like being
easier to debug, but also has some disadvantages, such as requiring
classes to be present in the local scope, what potentially leads to
circular import issues.

To prevent that kind of situation, Storm supports defining these
references using the stringified version of the class and property
names.  The only inconvenience of doing so is that all involved
classes must inherit from the `Storm` base class.

Let's define some new classes to show that.  To expose the point,
we'll refer to a class before it's actually defined.

{{{#!python
>>> class Country(Storm):
...     __storm_table__ = "country"
...     id = Int(primary=True)
...     name = Unicode()
...     currency_id = Int()
...     currency = Reference(currency_id, "Currency.id")

>>> class Currency(Storm):
...     __storm_table__ = "currency"
...     id = Int(primary=True)
...     symbol = Unicode()

>>> store.execute("CREATE TABLE country "
...               "(id INTEGER PRIMARY KEY, name VARCHAR, currency_id INTEGER)",
...               noresult=True)

>>> store.execute("CREATE TABLE currency "
...               "(id INTEGER PRIMARY KEY, symbol VARCHAR)", noresult=True)

}}}


Now, let's see if it works.

{{{#!python
>>> real = store.add(Currency())
>>> real.id = 1
>>> real.symbol = u"BRL"

>>> brazil = store.add(Country())
>>> brazil.name = u"Brazil"
>>> brazil.currency_id = 1

>>> brazil.currency.symbol
u'BRL'

}}}

Questions!? ;-)


==== Loading hook ====

Storm allows classes to define a few different hooks are called
to act when certain things happen.  One of the interesting hooks
available is the `__storm_loaded__` one.

Let's play with it.  We'll define a temporary subclass of Person
for that.

{{{#!python
>>> class PersonWithHook(Person):
...     def __init__(self, name):
...         print "Creating %s" % name
...         self.name = name
...
...     def __storm_loaded__(self):
...         print "Loaded %s" % self.name


>>> earl = store.add(PersonWithHook(u"Earl Easton"))
Creating Earl Easton

>>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()

>>> del earl
>>> collected = gc.collect()

>>> earl = store.find(PersonWithHook, name=u"Earl Easton").one()
Loaded Earl Easton

}}}

Note that in the first find, nothing was called, since the object
was still in memory and cached.  When we deleted the object and
ensured that it was collected, the object had to be retrieved
from the database again, and thus the hook was called (and not
the constructor!).


==== Auto-reloading values ====

Storm offers some special values that may be assigned to attributes
under its control.  One of these values is `AutoReload`.  When used,
it will make the object automatically reload the value from the
database when touched.  Even primary keys may benefit from its use,
as shown below.

{{{
>>> from storm.locals import AutoReload

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

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

}}}

This may be set as the default value for any attribute, making the
object be automatically flushed if necessary.


==== Expression values ====

Besides auto-reloading, it's also possible to assign a value that
will run a SQL expression to update a value.  For instance:

{{{#!python
from storm.locals import SQL

>>> ruy.name = SQL("(SELECT name || ' Ritcher' FROM person WHERE id=4)")
>>> ruy.name
u'Ruy Ritcher'

}}}

That's a silly example, of course, but there are many useful ways
to use that feature.


==== Much more! ====

There's a lot more about Storm to be shown.  This tutorial is just a
way to get initiated on some of the concepts.  While your questions
are not answered somewhere else, feel free to ask them in the mailing
list.


## vim:ts=4:sw=4:et:ft=moin