mysql

Package mysql |
[hide private]
[frames] | no frames]

# Source Code for Package mysql

      1  # $Header: /home/cvs2/mysql/mysql/__init__.py,v 1.6 2006/08/27 03:01:17 ehuss Exp $
      2  # Copyright (c) 2006, Eric Huss
      3  # All rights reserved.
      4  #
      5  # Redistribution and use in source and binary forms, with or without
      6  # modification, are permitted provided that the following conditions are met:
      7  #
      8  # 1. Redistributions of source code must retain the above copyright notice,
      9  #    this list of conditions and the following disclaimer.
     10  # 2. Redistributions in binary form must reproduce the above copyright notice,
     11  #    this list of conditions and the following disclaimer in the documentation
     12  #    and/or other materials provided with the distribution.
     13  # 3. Neither the name of Eric Huss nor the names of any contributors may be
     14  #    used to endorse or promote products derived from this software without
     15  #    specific prior written permission.
     16  #
     17  # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
     18  # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     19  # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
     20  # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
     21  # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
     22  # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
     23  # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
     24  # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
     25  # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
     26  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     27  # POSSIBILITY OF SUCH DAMAGE.
     28
     29  """MySQL 5 interface.
     30
     31  :Author: Eric Huss
     32  :Contact: http://ehuss.org/mysql/
     33  :License: BSD (See ``LICENSE`` file that came with distribution.)
     34  :Copyright: |copy| 2006 Eric Huss
     35  :Version: 0.9.0 Alpha 1
     36
     37  .. packagetree:: mysql
     38
     39  Introduction
     40  ============
     41  This is an interface to MySQL 5 written in Pyrex.  See
     42  http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/ for more detail on
     43  Pyrex.  Note that this library uses a slightly modified version of Pyrex. A
     44  copy is included in the distribution in case you want to extend any of the
     45  code.
     46
     47  There are 3 fundamental different ways to use the library.  They are:
     48
     49  1. "Simple" API.  This uses MySQL's normal query API.  It is a
     50     straightforward API of issuing SQL statements and getting results back.
     51  2. "Container" API.  This API piggybacks on the "simple" API, but provides a
     52     slightly more convenient way to issue queries and retrieve results in an
     53     object-oriented environment.
     54  3. "Statement" API.  The Statement API was introduced in MySQL 5.  It provides
     55     a method to pre-parse a SQL statement on the server-side.  You can then reuse
     56     that statement object repeatedly.  This offers a greater performance benefit
     57     if you are repeatedly issuing the same statements.
     58
     59  Connections
     60  ===========
     61  Everything in the API centers around the connection object.  A connection
     62  object represents a connection to the MySQL server.  It has a ``connect``
     63  method to establish the connection::
     64
     65      connection = mysql.connection.Connection()
     66      connection.connect(user=USER, password=PASSWORD)
     67
     68  Beware the MySQL typically only allows you to perform one operation at once
     69  on the connection.  The interface will attempt to keep track of what you are
     70  doing and abort any previous operations (such as reading results) if it would
     71  conflict.  Details are sprinkled throughout the API with information on which
     72  commands will abort other unfinished operations.
     73
     74  See the `mysql.connection` module for more details on the connection object.
     75
     76  Simple API
     77  ==========
     78  Issuing SQL statements with the simple API is relatively, well, simple::
     79
     80      connection.execute(
     81          'INSERT INTO sometable (foo, bar) VALUES ($foo, $bar)',
     82          foo=42, bar=24
     83      )
     84
     85  As you can see in this example, it uses Python's string template
     86  interpolation scheme. See documentation for ``paramstyle`` in
     87  `mysql.connection.Connection` for more detail and other schemes available.
     88
     89  For INSERT/UPDATE statements, the ``execute`` method will return the number
     90  of rows affected.  For SELECT statements, it returns a `mysql.result.Result`
     91  object which can be used to fetch rows::
     92
     93      result = connection.execute('SELECT foo, bar FROM sometable')
     94      for foo, bar in result:
     95          ...
     96
     97  Data Conversion
     98  ---------------
     99  The simple API provides a mechanism to convert between Python and MySQL data
    100  types. MySQL values are always strings.  However, the conversion API allows
    101  you to convert any type of input to a string, and convert certain types of
    102  outputs to their Python data type equivalents.
    103
    104  When you create a connection object, one of the optional parameters is a
    105  converter object.  There are some default converter objects that are used if
    106  you do not specify one.  They have support for many data types, such as Sets,
    107  datetime, decimal, integers, floats, strings, and more.
    108
    109  If you do not want result objects to convert values to Python data types, use
    110  the `mysql.conversion.output.No_Conversion` object when creating the
    111  connection. All values will be returned as strings as formatted by MySQL.
    112
    113  See `mysql.conversion` for more details on the conversion API.
    114
    115  Container API
    116  =============
    117  The container API is an extension of the simple API intended to simplify
    118  object-oriented programming.  Essentially it provides an automatic method to
    119  get and set values from/to an object.  It centers around the
    120  `mysql.connection.Connection.exec_container` and
    121  `mysql.connection.Connection.exec_fetch_container` for inserting and
    122  retrieving data respectively.
    123
    124  An example of how this could be used is::
    125
    126      class User:
    127
    128          def __init__(self, connection):
    129              self.connection = connection
    130
    131          def load(self, id):
    132              self.id = id
    133              self.connection.exec_fetch_container(self,
    134                  'SELECT name FROM users WHERE id=$id')
    135
    136          def update(self):
    137              self.connection.exec_container(self,
    138                  'UPDATE users SET name=$name WHERE id=$id')
    139
    140          def create(self, name):
    141              self.name = name
    142              self.connection.exec_container(self,
    143                  'INSERT INTO users (name) VALUES ($name)')
    144              self.id = self.connection.last_insert_id()
    145
    146  You can think of this as a little more sophisticated than the simple API, but
    147  not quite an Object-Relational Mapping library.
    148
    149  Statement API
    150  =============
    151  The statement API uses a new facility introduced in MySQL 5 that allows you
    152  to pre-parse a SQL statement on the server-side, and then reuse that statement
    153  object for higher performance.  It also provides a mechanism for streaming
    154  BLOB objects.
    155
    156  See `mysql.stmt` for details and examples on using the statement API.
    157
    158  Exceptions
    159  ==========
    160  All MySQL errors are mapped to error-specific exceptions so that you can
    161  naturally catch the errors you are interested in.  See `mysql.exceptions` for
    162  details about the exception heirarchy.
    163
    164  .. |copy| unicode:: 0xA9 .. copyright sign
    165  """
    166
    167  __version__ = '0.9.0a1'
    168
    169
    170  __all__ = [
    171      'connection',
    172      'constants',
    173      'conversion',
    174      'exceptions',
    175      'result',
    176      'stmt',
    177      'util',
    178      'version',
    179  ]
    180