1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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