[Sqlalchemy-commits] [1197] sqlalchemy/trunk/lib/sqlalchemy: update to types doc
Brought to you by:
zzzeek
Menu
▾
▴
[Sqlalchemy-commits] [1197] sqlalchemy/trunk/lib/sqlalchemy: update to types doc
|
From: <co...@sq...> - 2006-03-25 15:25:41
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head><style type="text/css"><!-- #msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; } #msg dt { float: left; width: 6em; font-weight: bold; } #msg dt:after { content:':';} #msg dl, #msg dt, #msg ul, #msg li { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; } #msg dl a { font-weight: bold} #msg dl a:link { color:#fc3; } #msg dl a:active { color:#ff0; } #msg dl a:visited { color:#cc6; } h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; } #msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding: 6px; } #msg ul, pre { overflow: auto; } #patch { width: 100%; } #patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;} #patch .propset h4, #patch .binary h4 {margin:0;} #patch pre {padding:0;line-height:1.2em;margin:0;} #patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;} #patch .propset .diff, #patch .binary .diff {padding:10px 0;} #patch span {display:block;padding:0 10px;} #patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;} #patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;} #patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;} #patch .lines, .info {color:#888;background:#fff;} --></style> <title>[1197] sqlalchemy/trunk/lib/sqlalchemy: update to types doc</title> </head> <body> <div id="msg"> <dl> <dt>Revision</dt> <dd>1197</dd> <dt>Author</dt> <dd>zzzeek</dd> <dt>Date</dt> <dd>2006-03-25 09:25:29 -0600 (Sat, 25 Mar 2006)</dd> </dl> <h3>Log Message</h3> <pre>update to types doc commented out 'tutorial' from docuemnt_base until its complete float extends numeric type</pre> <h3>Modified Paths</h3> <ul> <li><a href="#sqlalchemytrunkdocbuildcontentdocument_basemyt">sqlalchemy/trunk/doc/build/content/document_base.myt</a></li> <li><a href="#sqlalchemytrunkdocbuildcontenttypesmyt">sqlalchemy/trunk/doc/build/content/types.myt</a></li> <li><a href="#sqlalchemytrunklibsqlalchemytypespy">sqlalchemy/trunk/lib/sqlalchemy/types.py</a></li> </ul> </div> <div id="patch"> <h3>Diff</h3> <a id="sqlalchemytrunkdocbuildcontentdocument_basemyt"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/content/document_base.myt (1196 => 1197)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/content/document_base.myt 2006-03-25 02:49:10 UTC (rev 1196) +++ sqlalchemy/trunk/doc/build/content/document_base.myt 2006-03-25 15:25:29 UTC (rev 1197) </span><span class="lines">@@ -3,7 +3,7 @@ </span><span class="cx"> <%python scope="global"> </span><span class="cx"> </span><span class="cx"> files = [ </span><del>- 'tutorial', </del><ins>+ #'tutorial', </ins><span class="cx"> 'trailmap', </span><span class="cx"> 'pooling', </span><span class="cx"> 'dbengine', </span></span></pre></div> <a id="sqlalchemytrunkdocbuildcontenttypesmyt"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/doc/build/content/types.myt (1196 => 1197)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/doc/build/content/types.myt 2006-03-25 02:49:10 UTC (rev 1196) +++ sqlalchemy/trunk/doc/build/content/types.myt 2006-03-25 15:25:29 UTC (rev 1197) </span><span class="lines">@@ -6,23 +6,28 @@ </span><span class="cx"> </p> </span><span class="cx"> <&|doclib.myt:item, name="standard", description="Built-in Types" &> </span><span class="cx"> </span><del>-<p>SQLAlchemy comes with a set of standard generic datatypes, which are defined as classes. They are specified to table meta data using either the class itself, or an instance of the class. Creating an instance of the class allows you to specify parameters for the type, such as string length, numerical precision, etc. </del><ins>+<p>SQLAlchemy comes with a set of standard generic datatypes, which are defined as classes. </ins><span class="cx"> </p> </span><span class="cx"> <p>The standard set of generic types are:</p> </span><del>-<&|formatting.myt:code&> - # sqlalchemy.types package: </del><ins>+<&|formatting.myt:code, title="package sqlalchemy.types"&> </ins><span class="cx"> class String(TypeEngine): </span><span class="cx"> def __init__(self, length=None) </span><span class="cx"> </span><span class="cx"> class Integer(TypeEngine) </span><del>- </del><ins>+ + class SmallInteger(Integer) + </ins><span class="cx"> class Numeric(TypeEngine): </span><span class="cx"> def __init__(self, precision=10, length=2) </span><span class="cx"> </span><del>- class Float(TypeEngine): </del><ins>+ class Float(Numeric): </ins><span class="cx"> def __init__(self, precision=10) </span><span class="cx"> </span><span class="cx"> class DateTime(TypeEngine) </span><ins>+ + class Date(TypeEngine) + + class Time(TypeEngine) </ins><span class="cx"> </span><span class="cx"> class Binary(TypeEngine): </span><span class="cx"> def __init__(self, length=None) </span><span class="lines">@@ -31,10 +36,11 @@ </span><span class="cx"> </span><span class="cx"> # converts unicode strings to raw bytes </span><span class="cx"> # as bind params, raw bytes to unicode as </span><del>- # rowset values </del><ins>+ # rowset values, using the unicode encoding + # setting on the engine (defaults to 'utf-8') </ins><span class="cx"> class Unicode(String) </span><span class="cx"> </&> </span><del>-<p>More specific subclasses of these types are available, to allow finer grained control over types:</p> </del><ins>+<p>More specific subclasses of these types are available, which various database engines may choose to implement specifically, allowing finer grained control over types:</p> </ins><span class="cx"> <&|formatting.myt:code&> </span><span class="cx"> class FLOAT(Numeric) </span><span class="cx"> class TEXT(String) </span><span class="lines">@@ -50,14 +56,26 @@ </span><span class="cx"> class BOOLEAN(Boolean) </span><span class="cx"> </&> </span><span class="cx"> <p>When using a specific database engine, these types are adapted even further via a set of database-specific subclasses defined by the database engine.</p> </span><ins>+<p>There may eventually be more type objects that are defined for specific databases. An example of this would be Postgres' Array type. +</p> +<p>Type objects are specified to table meta data using either the class itself, or an instance of the class. Creating an instance of the class allows you to specify parameters for the type, such as string length, numerical precision, etc.:</p> +<&|formatting.myt:code&> + mytable = Table('mytable', engine, + # define type using a class + Column('my_id', Integer, primary_key=True), + + # define type using an object instance + Column('value', Number(7,4)) + ) </ins><span class="cx"> </&> </span><ins>+</&> </ins><span class="cx"> </span><span class="cx"> <&|doclib.myt:item, name="custom", description="Creating your Own Types" &> </span><del>-<p>Types also support pre-processing of query parameters as well as post-processing of result set data. You can make your own classes to perform these operations. They are specified by subclassing the desired type class as well as the special mixin TypeDecorator, which manages the adaptation of the underlying type to a database-specific type:</p> -<&|formatting.myt:code&> </del><ins>+<p>User-defined types can be created, to support either database-specific types, or customized pre-processing of query parameters as well as post-processing of result set data. You can make your own classes to perform these operations. They are specified by subclassing the desired type class:</p> +<&|formatting.myt:code, title="Basic Example"&> </ins><span class="cx"> import sqlalchemy.types as types </span><span class="cx"> </span><del>- class MyType(types.TypeDecorator, types.String): </del><ins>+ class MyType(types.String): </ins><span class="cx"> """basic type that decorates String, prefixes values with "PREFIX:" on </span><span class="cx"> the way in and strips it off on the way out.""" </span><span class="cx"> def convert_bind_param(self, value, engine): </span><span class="lines">@@ -65,6 +83,30 @@ </span><span class="cx"> def convert_result_value(self, value, engine): </span><span class="cx"> return value[7:] </span><span class="cx"> </&> </span><ins>+<p>A common desire is for a "pickle" type, which overrides a Binary object to provide pickling behavior: +<&|formatting.myt:code, title="Pickle Type"&> + import cPickle + + class PickleType(types.Binary): + def __init__(self, protocol=cPickle.HIGHEST_PROTOCOL): + """allows the pickle protocol to be specified""" + self.protocol = protocol + def convert_result_value(self, value, engine): + return cpickle.loads(super(PickleType, self).convert_result_value(value, engine), self.protocol) + def convert_bind_param(self, value, engine): + return super(PickleType, self).convert_bind_param(cpickle.dumps(value, self.protocol), engine) + def get_constructor_args(self): + return {'protocol':self.protocol} +</&> +<p>Which can be used like:</p> +<&|formatting.myt:code&> + mytable = Table('mytable', engine, + Column('id', Integer, primary_key=True), + Column('data', PickleType())) + + my_object = MyObject() + mytable.insert().execute(data=my_object) +</&> </ins><span class="cx"> <p>Another example, which illustrates a fully defined datatype. This just overrides the base type class TypeEngine:</p> </span><span class="cx"> <&|formatting.myt:code&> </span><span class="cx"> import sqlalchemy.types as types </span><span class="lines">@@ -78,9 +120,6 @@ </span><span class="cx"> return value </span><span class="cx"> def convert_result_value(self, value, engine): </span><span class="cx"> return value </span><del>- def adapt(self, typeobj): - """produces an adaptation of this object given a type which is a subclass of this object""" - return typeobj(self.precision) </del><span class="cx"> def adapt_args(self): </span><span class="cx"> """allows for the adaptation of this TypeEngine object into a new kind of type depending on its arguments.""" </span><span class="cx"> return self </span></span></pre></div> <a id="sqlalchemytrunklibsqlalchemytypespy"></a> <div class="modfile"><h4>Modified: sqlalchemy/trunk/lib/sqlalchemy/types.py (1196 => 1197)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/trunk/lib/sqlalchemy/types.py 2006-03-25 02:49:10 UTC (rev 1196) +++ sqlalchemy/trunk/lib/sqlalchemy/types.py 2006-03-25 15:25:29 UTC (rev 1197) </span><span class="lines">@@ -117,7 +117,7 @@ </span><span class="cx"> def get_constructor_args(self): </span><span class="cx"> return {'precision':self.precision, 'length':self.length} </span><span class="cx"> </span><del>-class Float(TypeEngine): </del><ins>+class Float(Numeric): </ins><span class="cx"> def __init__(self, precision = 10): </span><span class="cx"> self.precision = precision </span><span class="cx"> def get_constructor_args(self): </span></span></pre> </div> </div> </body> </html> |
