From 19a786a751e5da3dc7993142c82da37981774579 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sat, 25 Mar 2006 15:25:29 +0000 Subject: [PATCH] update to types doc commented out 'tutorial' from docuemnt_base until its complete float extends numeric type --- doc/build/content/document_base.myt | 2 +- doc/build/content/types.myt | 65 +++++++++++++++++++++++------ lib/sqlalchemy/types.py | 2 +- 3 files changed, 54 insertions(+), 15 deletions(-) diff --git a/doc/build/content/document_base.myt b/doc/build/content/document_base.myt index f45a022e10..a1ccc6c610 100644 --- a/doc/build/content/document_base.myt +++ b/doc/build/content/document_base.myt @@ -3,7 +3,7 @@ <%python scope="global"> files = [ - 'tutorial', + #'tutorial', 'trailmap', 'pooling', 'dbengine', diff --git a/doc/build/content/types.myt b/doc/build/content/types.myt index 370222ff6c..3df5e75bb3 100644 --- a/doc/build/content/types.myt +++ b/doc/build/content/types.myt @@ -6,23 +6,28 @@

<&|doclib.myt:item, name="standard", description="Built-in Types" &> -

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. +

SQLAlchemy comes with a set of standard generic datatypes, which are defined as classes.

The standard set of generic types are:

-<&|formatting.myt:code&> - # sqlalchemy.types package: +<&|formatting.myt:code, title="package sqlalchemy.types"&> class String(TypeEngine): def __init__(self, length=None) class Integer(TypeEngine) - + + class SmallInteger(Integer) + class Numeric(TypeEngine): def __init__(self, precision=10, length=2) - class Float(TypeEngine): + class Float(Numeric): def __init__(self, precision=10) class DateTime(TypeEngine) + + class Date(TypeEngine) + + class Time(TypeEngine) class Binary(TypeEngine): def __init__(self, length=None) @@ -31,10 +36,11 @@ # converts unicode strings to raw bytes # as bind params, raw bytes to unicode as - # rowset values + # rowset values, using the unicode encoding + # setting on the engine (defaults to 'utf-8') class Unicode(String) -

More specific subclasses of these types are available, to allow finer grained control over types:

+

More specific subclasses of these types are available, which various database engines may choose to implement specifically, allowing finer grained control over types:

<&|formatting.myt:code&> class FLOAT(Numeric) class TEXT(String) @@ -50,14 +56,26 @@ class BLOB(Binary) class BOOLEAN(Boolean)

When using a specific database engine, these types are adapted even further via a set of database-specific subclasses defined by the database engine.

+

There may eventually be more type objects that are defined for specific databases. An example of this would be Postgres' Array type. +

+

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.:

+<&|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)) + ) + <&|doclib.myt:item, name="custom", description="Creating your Own Types" &> -

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:

-<&|formatting.myt:code&> +

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:

+<&|formatting.myt:code, title="Basic Example"&> import sqlalchemy.types as types - class MyType(types.TypeDecorator, types.String): + class MyType(types.String): """basic type that decorates String, prefixes values with "PREFIX:" on the way in and strips it off on the way out.""" def convert_bind_param(self, value, engine): @@ -65,6 +83,30 @@ class BOOLEAN(Boolean) def convert_result_value(self, value, engine): return value[7:] +

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} + +

Which can be used like:

+<&|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) +

Another example, which illustrates a fully defined datatype. This just overrides the base type class TypeEngine:

<&|formatting.myt:code&> import sqlalchemy.types as types @@ -78,9 +120,6 @@ class BOOLEAN(Boolean) return value def convert_result_value(self, value, engine): return value - def adapt(self, typeobj): - """produces an adaptation of this object given a type which is a subclass of this object""" - return typeobj(self.precision) def adapt_args(self): """allows for the adaptation of this TypeEngine object into a new kind of type depending on its arguments.""" return self diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py index 89fd3bd2c7..2aa67507d4 100644 --- a/lib/sqlalchemy/types.py +++ b/lib/sqlalchemy/types.py @@ -117,7 +117,7 @@ class Numeric(TypeEngine): def get_constructor_args(self): return {'precision':self.precision, 'length':self.length} -class Float(TypeEngine): +class Float(Numeric): def __init__(self, precision = 10): self.precision = precision def get_constructor_args(self): -- 2.47.2