[Checkins] SVN: zodbdocs/trunk/ - More improvements to front-page readability.

Christian Theune ct at gocept.com
Thu Feb 18 05:24:49 EST 2010


Log message for revision 109113:
  - More improvements to front-page readability.
  - Add missing files from last checkins.
  

Changed:
  A   zodbdocs/trunk/.static/
  A   zodbdocs/trunk/bugs.rst
  U   zodbdocs/trunk/documentation/articles/index.rst
  A   zodbdocs/trunk/features.rst
  U   zodbdocs/trunk/index.rst
  A   zodbdocs/trunk/tutorial.rst

-=-
Added: zodbdocs/trunk/bugs.rst
===================================================================
--- zodbdocs/trunk/bugs.rst	                        (rev 0)
+++ zodbdocs/trunk/bugs.rst	2010-02-18 10:24:49 UTC (rev 109113)
@@ -0,0 +1,11 @@
+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

Modified: zodbdocs/trunk/documentation/articles/index.rst
===================================================================
--- zodbdocs/trunk/documentation/articles/index.rst	2010-02-18 10:02:18 UTC (rev 109112)
+++ zodbdocs/trunk/documentation/articles/index.rst	2010-02-18 10:24:49 UTC (rev 109113)
@@ -29,8 +29,16 @@
 - `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>`_

Added: zodbdocs/trunk/features.rst
===================================================================
--- zodbdocs/trunk/features.rst	                        (rev 0)
+++ zodbdocs/trunk/features.rst	2010-02-18 10:24:49 UTC (rev 109113)
@@ -0,0 +1,10 @@
+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

Modified: zodbdocs/trunk/index.rst
===================================================================
--- zodbdocs/trunk/index.rst	2010-02-18 10:02:18 UTC (rev 109112)
+++ zodbdocs/trunk/index.rst	2010-02-18 10:24:49 UTC (rev 109113)
@@ -24,29 +24,25 @@
 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>`_.

Added: zodbdocs/trunk/tutorial.rst
===================================================================
--- zodbdocs/trunk/tutorial.rst	                        (rev 0)
+++ zodbdocs/trunk/tutorial.rst	2010-02-18 10:24:49 UTC (rev 109113)
@@ -0,0 +1,83 @@
+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.



More information about the checkins mailing list