``````````
SQLBuilder
``````````

A number of variables from SQLBuilder are included with ``from
sqlobject import *`` -- see the `relevant SQLObject documentation`_
for more.  Its functionality is also available through the special
``q`` attribute of `SQLObject` classes.

.. _`relevant SQLObject documentation`: SQLObject.html#exported-symbols

Using SQLBuilder
================

SQLBuilder uses clever overriding of operators to make Python
expressions build SQL expressions -- so long as you start with a Magic
Object that knows how to fake it.

With SQLObject, you get a Magic Object by access the ``q`` attribute
of a table class -- this gives you an object that represents the
field.  Maybe explanations aren't as good.  Here's some examples::

    >>> from sqlobject.sqlbuilder import *
    >>> person = table.person
    # person is now equivalent to the Person.q object from the SQLObject
    # documentation
    >>> person
    person
    >>> person.first_name
    person.first_name
    >>> person.first_name == 'John'
    person.first_name = 'John'
    >>> name = 'John'
    >>> person.first_name != name
    person.first_name <> 'John'
    >>> AND(person.first_name == 'John', person.last_name == 'Doe')
    (person.first_name = 'John' AND person.last_name = 'Doe')

Most of the operators work properly: <, >, <=, >=, !=, ==, +, -, /,
\*, \*\*, %.  However, ``and``, ``or``, and ``not`` **do not work**.
You can use &, \|, and ~ instead -- but be aware that these have
the same precedence as multiplication.  So::

    # This isn't what you want:
    >> person.first_name == 'John' & person.last_name == 'Doe'
    (person.first_name = ('John' AND person.last_name)) = 'Doe')
    # This is:
    >> (person.first_name == 'John') & (person.last_name == 'Doe')
    ((person.first_name = 'John') AND (person.last_name == 'Doe'))

SQLBuilder also contains the functions ``AND``, ``OR``, and ``NOT`` which
also work -- I find these easier to work with.  ``AND`` and ``OR`` can
take any number of arguments.

You can also use ``.startswith()`` and ``.endswith()`` on a SQL
expression -- these will translate to appropriate ``LIKE`` statements
(but all ``%`` quoting is handled for you, so you can ignore that
implementation detail).  There is also a ``LIKE`` function, where you
can pass your string, with ``%`` for the wildcard, as usual.

If you want to access a SQL function, use the ``func`` variable,
like::

    >> person.created < func.NOW()

That's it -- enjoy!

.. image:: http://sflogo.sourceforge.net/sflogo.php?group_id=74338&type=10
   :target: http://sourceforge.net/projects/sqlobject
   :class: noborder
   :align: center
   :height: 15
   :width: 80
   :alt: Get SQLObject at SourceForge.net. Fast, secure and Free Open Source software downloads