Commit 4df7cb4b authored by Christian Theune's avatar Christian Theune

- More improvements to front-page readability.

- Add missing files from last checkins.
parent e89b6518
Bugs
====
General bug reporting happens in the `Launchpad bug
tracker<http://bugs.launchpad.net/zodb>`_.
However, the ZODB has been around much longer and thus there are some historic
resource for bug-related information.:
* Zope collector (with topic `database`) at http://collector.zope.org/Collectors/Zope
* ZODB sourceforge bug tracker (much older) at http://sourceforge.net/tracker/?group_id=15628&atid=115628
......@@ -29,8 +29,16 @@ Other ZODB Resources
- `How To Love ZODB and Forget RDBMS
<http://zope.org/Members/adytumsolutions/HowToLoveZODB_PartI>`_
- `ZODB Wiki <http://www.zope.org/Wikis/ZODB/FrontPage>`_ and `Documentation
page <http://wiki.zope.org/ZODB/Documentation>`_
- `ZODB wiki <http://www.zope.org/Wikis/ZODB/FrontPage>`_ and `Documentation
page <http://wiki.zope.org/ZODB/Documentation>`_ and `Historical pages
<http://wiki.zope.org/ZODB/HistoricalPages>`_
- `Very old ZODB wiki <http://www.zope.org/Members/jim/ZODB/FrontPage>`_
- `ZODB-dev <http://mail.zope.org/mailman/listinfo/zodb-dev>`_ mailing list
and `archive <http://mail.zope.org/pipermail/zodb-dev/>`_
- `Administering Zope 2 - ZODB
<http://wiki.zope.org/zope2/ZODBZopeObjectDatabase>`_
- `Add-on software for ZODB <http://wiki.zope.org/ZODB/ZODBAddOns>`_
Feature requests
================
Feature requests are currently handled a bit ad-hoc. Feel free to write a post
to the mailing list asking for a feature and - if you don't want it to be
forgotten - add a `blueprint in
Launchpad<http://blueprints.launchpad.net/zodb>`.
Also, formerly we used to manage proposals in our old wiki at
http://wiki.zope.org/ZODB/ListOfProposals/contents#ListOfProposals
......@@ -24,29 +24,25 @@ Documentation
Downloads
=========
ZODB is available as Python eggs from the Python Package Index:
http://pypi.python.org/pypi/ZODB3/
ZODB is distributed as Python eggs through the `Python Package Index <http://pypi.python.org/pypi/ZODB3>`_.
You can install the egg using setuptools' easy_install command::
$ easy_install ZODB3
`Other downloads <downloads.rst>`_ are available for older releases and via
Subversion.
`Other downloads <downloads.rst>`_ are available for old (non-egg) releases
and via Subversion.
Community and contributing
==========================
Discussion occurs on the ZODB developers' mailing list. You can subscribe at
http://mail.zope.org/mailman/listinfo/zodb-dev.
Discussion occurs on the `ZODB developers' mailing list <http://mail.zope.org/mailman/listinfo/zodb-dev>`_.
Bug reporting, feature requests, and release planning are done on Launchpad
(http://launchpad.net/zodb).
:doc:`Bug reporting<bugs>`, :doc:`feature requests<features>`, and release planning are done on `Launchpad <http://launchpad.net/zodb>`_.
If you'd like to contribute then we'll gladly accept work on documentation,
helping out other developers and users at the mailing list, submitting bugs,
creating proposals and writing code.
ZODB is a project managed by the Zope Foundation so you can get write access
for contributing directly. Check out the `Zope Developer Information` section
at http://docs.zope.org for more information.
for contributing directly - check out the foundation's `Zope Developer Information <http://docs.zope.org/developer>`_.
Introduction
Lets have a look at a simple piece of code that we want to turn into using ZODB:
class Account(object):
def __init__(self):
self.balance = 0.0
def deposit(self, amount):
self.balance += amount
def cash(self, amount):
assert amount < self.balance
self.balance -= amount
This code defines a simple class that holds the balance of a bank account and provides two methods to manipulate the balance: deposit and cash.
Installation
If you do not have easy_install available on your system, follow the EasyInstall installation instructions.
There are other installation mechanisms available to manage the installation of Python packages. This tutorial assumes that you are using a plain Python installation and install ZODB globally.
Before being able to use ZODB we have to install it, using easy_install. Note that the actual package name is called "ZODB3":
$ easy_install ZODB3
...
$ python
>>> import ZODB
ZODB is now installed and can be imported from your Python installation.
Configuration
When a program wants to use the ZODB it has to establish a connection, like any other database. For the ZODB we need 3 different parts: a storage, a database and finally a connection:
>>> from ZODB.FileStorage import FileStorage
>>> from ZODB.DB import DB
>>>
>>> storage = FileStorage('Data.fs')
>>> db = DB(storage)
>>> connection = db.open()
>>> root = connection.root()
We create a storage called FileStorage, which is the current standard storage used by virtually everyone. It keeps track of all data in a single file as stated by the first parameter. From this storage we create a database and finally open up a connection. Finally, we retrieve the database root object from the connection that we opened.
Storing objects
Frameworks like Zope only create a single object in the ZODB root representing the application itself and then let all sub-objects be referenced from there on. They choose names like 'app' for the first object they place in the ZODB.
To store an object in the ZODB we simply attach it to any other object that already lives in the database. Hence, the root object functions as a boot-strapping point. The root object is a dictionary and you can start storing your objects directly in there:
>>> root['account-1'] = Account()
>>> root['account-2'] = Account()
Transactions
You now have two objects placed in your root object and in your database. However, they are not permanently stored yet. The ZODB uses transactions and to make your changes permanent, you have to commit the transaction:
>>> import transaction
>>> transaction.commit()
root.keys()
['account-1', 'account-2']
Now you can stop and start your application and look at the root object again, and you will find the entries 'account-1' and 'account-2' to be still be present and be the objects you created.
Objects that have not been stored in the ZODB yet are not rolled back by an abort.
If your application makes changes during a transaction and finds that it does not want to commit those changes, then you can abort the transaction and have the changes rolled back for you:
>>> del root['account-1']
>>> root.keys()
['account-2']
>>> transaction.abort()
>>> root.keys()
['account-1', 'account-2']
Persistent objects
Have a look at the reference documentation about the rules of persistency and to find out more about specialised persistent objects like BTrees.
One last aspect that we need to cover are persistent objects themselves. The ZODB will be happy to store almost any Python object that you pass to it (it won't store files for example). But in order for noticing which objects have changed the ZODB needs those objects to cooperate with the database. In general, you just subclass `persistent.Persistent` to make this happen. So our example class from above would read like:
import persistent
class Account(persistent.Persistent):
# ... same code as above ...
Summary
You have seen how to install ZODB and how to open a database in your application and to start storing objects in it. We also touched the two simple transaction commands: commit and abort. The reference documentation contains sections with more information on the individual topics.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment