bmuller · xadhoom · Mar 17, 2011 · Mar 18, 2011 · Apr 28, 2011 · Apr 28, 2011
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [2.7]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: python -m pip install -q Twisted
+      - name: Run txconnectionpool tests
+        run: trial txconnectionpool
+      - name: Run test
+        run: trial twistar
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,3 @@ doc/*.html
 _trial_temp
 build
 dist
-twistar.egg-info
diff --git a/INSTALL b/INSTALL
diff --git a/README.markdown b/README.markdown
@@ -0,0 +1,80 @@
+# twistar: Asynchronous Python ORM
+[![Build Status](https://secure.travis-ci.org/xadhoom/twistar.png?branch=master)](https://travis-ci.org/xadhoom/twistar)
+
+The Twistar Project provides an ActiveRecord (ORM) pattern interface to the Twisted Project's RDBMS library.  This file contains minimal documentation - see the project home page at http://findingscience.com/twistar for more information.
+
+## Installation
+
+```
+easy_install twistar
+```
+
+## Usage
+Your database must be one of: MySQL, PostgreSQL, or SQLite.  The only DBAPI modules supported by Twistar are: MySQLdb, psycopg2, and sqlite3 - at least one of these must be installed.
+
+Here's the obligatory TL;DR example of creating a User record, assuming that there is a table named "users" with varchar columns for first_name and last_name and an int age column:
+
+```python
+#!/usr/bin/env python
+from twisted.enterprise import adbapi
+from twistar.registry import Registry
+from twistar.dbobject import DBObject
+from twisted.internet import reactor
+
+class User(DBObject):
+     pass
+
+def done(user):
+     print "A user was just created with the name %s" % user.first_name
+     reactor.stop()
+
+# Connect to the DB
+Registry.DBPOOL = adbapi.ConnectionPool('MySQLdb', user="twistar", passwd="apass", db="twistar")
+
+# make a user
+u = User()
+u.first_name = "John"
+u.last_name = "Smith"
+u.age = 25
+
+# Or, use this shorter version:
+u = User(first_name="John", last_name="Smith", age=25)
+
+# save the user
+u.save().addCallback(done)
+
+reactor.run()
+```
+
+Then, finding this user is easy:
+
+```python
+def found(users):
+    print "I found %i users!" % len(users)
+    for user in users:
+        print "User: %s %s" % (user.first_name, user.last_name)
+
+u = User.findBy(first_name="John", age=25).addCallback(found)
+```
+
+This is a very simple example - see http://findingscience.com/twistar for more complicated examples and additional uses.
+
+## Testing
+You will need to install the sqlite3 python package if you want to run the default tests.  To run the tests:
+
+```
+trial twistar
+```
+
+See the README in the twistar/tests folder for more information on testing with different database types.
+
+## Documenation
+If you intent on generating API documentation, you will need pydoctor.  If you want to generate the user documentation, you will need to install Twisted Lore.
+
+To generate documentation:
+
+```
+make docs
+```
+
+Then open the docs/index.html file in a browser.
diff --git a/README → README.rst b/README → README.rst
@@ -1,3 +1,8 @@
+Twistar
+=======
+
+.. image:: https://secure.travis-ci.org/xadhoom/twistar.png?branch=master
+
 The Twistar Project provides an ActiveRecord (ORM) pattern interface to 
 the Twisted Project's RDBMS library.
 
@@ -6,3 +11,4 @@ those instructions are the steps to generating API, docs, and HOWTO examples.
 
 For more information, see the project home page at:
 http://findingscience.com/twistar
+
diff --git a/doc/examples.xhtml b/doc/examples.xhtml
@@ -9,13 +9,13 @@
   <body>
     <h1>Simple Examples</h1>
 <p>
-  Since Twistar uses Twisted, most methodand function calls willreturn a <code class="python">twisted.internet.defer.Deferred</code>
-  object. You must understand the propper use of these objects before most of this documentationwill make sense.
+  Since Twistar uses Twisted, most methods and function calls will return a <code class="python">twisted.internet.defer.Deferred</code>
+  object. You must understand the proper use of these objects before most of this documentation will make sense.
 </p>
 
     <h2>Initialization</h2>
-    <p>Before using Twistar a connection to the DB must first be made.  The method of connecting to the database
-is to use Twisted's <code class="python">twisted.enterprise.adapi</code> module and the <code class="python">ConnectionPool</code>
+    <p>Before using Twistar a connection to the DB must be made.  To connect to the database
+use Twisted's <code class="python">twisted.enterprise.adapi</code> module and the <code class="python">ConnectionPool</code>
 object.  The <code class="python">Registry</code> class is used to keep track of that pool.  For instance, this is the 
 method to specify a connection to a MySQL database:
 </p>
@@ -54,7 +54,7 @@ an auto-incrementing integer column named <q>id</q>.
 
 <h2>Defining and Interacting With Objects</h2>
 <p>
-Object's representing rows in a database need only extend the 
+Objects representing rows in a database need only extend the 
 <code class="python">DBObject</code> class.
 </p>
 <pre class="python">
@@ -147,13 +147,13 @@ User.exists(['first_name = ?', "John"]).addCallback(printExists)
 
 <h2>Validations</h2>
 <p>
-Twistar also supports validations.  Validations describe constraints on an objects
+Twistar also supports validations.  Validations describe constraints on an object's
 parameters.  If those constraints are violated, then an object will not be saved (this
 includes both creating and updating).  In such a case a special parameter in the object
 keeps track of the errors and the messages.
 </p>
 <p>
-As an example, let's say that we want all users to always have a first name set and a last
+As an example, let's say that we want all users to have a first name set and a last
 name that has a length between 1 and 256 characters.  First, we describe the class 
 <code class="python">User</code> as above and then add restrictions on it.
 </p>

diff --git a/doc/index.xhtml b/doc/index.xhtml
@@ -24,6 +24,7 @@ object.  You must understand the propper use of these objects before most of thi
     <li><a href="examples.xhtml">Basic Examples</a></li>
     <li><a href="relationship_examples.xhtml">Examples With Relationships</a></li>
     <li><a href="lowlevel.xhtml">Lowlevel Database Interaction</a></li>
+    <li><a href="transactions.xhtml">Examples with Transactions</a></li>
   </ul>
 
 </body>

diff --git a/doc/relationship_examples.xhtml b/doc/relationship_examples.xhtml
@@ -150,12 +150,12 @@ Registry.register(User, Picture)
 Assuming the DB structure is the same as in the "has many" example, you can now get and set the user that 
 a particular picture belongs to (using <code class="python">get()</code> and <code class="python">set()</code>
 methods on <code class="python">picture.user</code>).  Additionally, there is a <code>clear()</code> method that will clear all
-objects in a given belongs to relationship.
+objects in a given "belongs to" relationship.
 </p>
   <h2>Has and Belongs To Many</h2>
 <p>
-In a has and belongs to many relationship two objects have a many to many relationship.  For instance, users and favorite colors.  
-A user can have many favorite colors and a favorite color could belong to many users.  In this example, there should be three tables -
+In a "has and belongs to many" relationship two objects have a many to many relationship.  For instance, users and favorite colors.  
+A user can have many favorite colors and a favorite color could belong to many users.  In this example, there should be three tables &mdash;
 a <code>users</code> table, a <code>favorite_colors</code> table, and a <code>favorite_colors_users</code> table.  The last on the list 
 is a special table that stores the relationships between the colors and users.  It has no primary key, and two columns: one for 
 <code>user_id</code>s and one for <code>favorite_color_id</code>s.  The table's name by convention should be the combination of the other

diff --git a/doc/transactions.xhtml b/doc/transactions.xhtml
@@ -0,0 +1,112 @@
+<?xml version="1.0"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Transaction Examples</title>
+  </head>
+
+  <body>
+    <h1>Transaction Examples</h1>
+<p>From Active Record Transactions:
+<q>Transactions are protective blocks where SQL statements are only permanent if they can all succeed as one atomic action. 
+The classic example is a transfer between two accounts where you can only have a deposit if the withdrawal succeeded and vice versa. 
+Transactions enforce the integrity of the database and guard the data against program errors or database break-downs. 
+So basically you should use transactions whenever you have a number of statements that must be executed together or not at all.</q>
+</p>
+<p>
+More examples can be found in the <code class="python">RelationshipTest</code> class.
+</p>
+  <h2>Initialization</h2>
+  <p>Given a <code class="python">DBObject</code> class instance, developer can call <code class="python">transaction()</code>
+  method on it, causing the start of the transaction. The method will return a transaction identifier.</p>
+<pre class="python">
+from twisted.internet.defer import inlineCallback
+
+@inlineCallbacks
+def do_some_pen_operations:
+	pen = Pen()
+	txn = pen.transaction()
+</pre>
+
+  <h2>Commit / Rollback</h2>
+  <p>In this example, we will be using a <code class="python">Pen</code> object, which extends <code class="python">DBObject</code> class.</p>
+  <p>WARNING: pseudocode!</p>
+<pre class="python">
+from twisted.internet.defer import inlineCallback
+
+@inlineCallbacks
+def do_some_pen_operations:
+	pen = Pen()
+	pen.transaction()
+
+	pen.owner = "Luke"
+	yield pen.save()
+
+	pen.use() /* do something with the pen */
+
+	/* check if the owner is still Luke, after use */
+	if pen.owner == "Luke":
+		yield pen.commit()
+	else:
+		/* owner has changed, cannot apply ! */
+		yield pen.rollback()
+
+</pre>
+  <h2>Different classes in a single transaction</h2>
+  <p>In this example, we use the same transaction across different objects, to bind all operations on them to same handler.</p>
+  <p>WARNING: pseudocode!</p>
+<pre class="python">
+from twisted.internet.defer import inlineCallback
+
+@inlineCallbacks
+def do_some_financial_operations:
+	money = Balance()
+	txn = money.transaction()
+
+	account = Account(transaction=txn)
+
+	money.total = 100
+	account.total = -100
+
+
+	yield money.save()
+	yield account.save()
+
+	try:
+		money.commit() /* or account.commit() */
+	except Exception, e:
+		money.rollback()
+</pre>
+  <h2>Notes</h2>
+  <p>After a rollback or commit, the transaction is closed. You need to call <code class="python">transaction()</code> method again
+  to start a new transaction.</p>
+  <p>Depending on DB engine, you cannot call save on a <code class="python">DBObject</code> instance if same class type has an open transaction
+  (not committed yet), because the code will block waiting for the first transaction to finish. If the first open transaction will finish
+  before operation timeout, save will be done, otherwise will get executed after the transaction timeout of the DB engine. For example :</p>
+  <p>WARNING: pseudocode!</p>
+<pre class="python">
+from twisted.internet.defer import inlineCallback
+
+@inlineCallbacks
+def do_some_pen_operations:
+	pen = Pen(color="red")
+	pen.transaction() /* start transaction only on pen */
+
+	another_pen = Pen(color="blue") /* this is not in transaction */
+
+	yield pen.save()
+
+	/* code will block here utile DB engine timeout ... after that save() will throw an Exception */
+	/* after that, neither pen and another_pen are really save, the former because commit has not been called,
+	 * the latter because the DB engine throwed an exception */
+	yield another_pen.save()
+
+	/* not executed at all */
+	yield pen.commit()
+	yield another_pen.commit()
+</pre>
+
+  </body>
+</html>
+
diff --git a/setup.py b/setup.py
@@ -1,17 +1,17 @@
 #!/usr/bin/env python
-try:
-    from setuptools import setup, Extension
-except ImportError:
-    from distutils.core import setup, Extension
+from setuptools import setup, find_packages
+
+from twistar import version
 
 setup(
     name="twistar",
-    version="1.0",
+    version=version,
     description="An implementation of the Active Record pattern for Twisted",
     author="Brian Muller",
     author_email="bamuller@gmail.com",
-    license="GPLv3",
+    license="MIT",
     url="http://findingscience.com/twistar",
-    packages=["twistar", "twistar.dbconfig", "twistar.tests", 'BermiInflector', 'BermiInflector.Rules'],
-    requires=["twisted.enterprise.adbapi"]
+    packages=find_packages(),
+    requires=["twisted.enterprise.adbapi"],
+    install_requires=['twisted >= 12.1']
 )
diff --git a/twistar/__init__.py b/twistar/__init__.py
@@ -6,6 +6,5 @@
 
 @author: Brian Muller U{bamuller@gmail.com}
 """
-
-version = "0.1"
-version_info = (0, 1)
+version_info = (1, 3)
+version = '.'.join(map(str, version_info))
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,4 +4,3 @@ doc/*.html @@
     _trial_temp
     build
     dist
-    twistar.egg-info