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