From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 18 Oct 2012 16:30:50 +0000 (-0400)
Subject: - add a section on how to render types, #78
X-Git-Tag: rel_0_4_1~10
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=89498d6263acd33fd452144895cac099fafd8f68;p=thirdparty%2Fsqlalchemy%2Falembic.git

- add a section on how to render types, #78
---

diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index 584d71e6..a90209a8 100644
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -572,6 +572,38 @@ Autogenerate can't currently, but will *eventually* detect:
 * Index additions, removals - not yet implemented.
 * Sequence additions, removals - not yet implemented.
 
+Rendering Custom Types in Autogenerate
+--------------------------------------
+
+Note that the methodology Alembic uses to generate SQLAlchemy type constructs
+as Python code is plain old ``__repr__()``.   SQLAlchemy's built-in types
+for the most part have a ``__repr__()`` that faithfully renders a
+Python-compatible constructor call, but there are some exceptions, particularly
+in those cases when a constructor accepts arguments that aren't compatible
+with ``__repr__()``, such as a pickling function.
+
+When building a custom type that will be rendered into a migration script,
+it is often necessary to explicitly give the type a ``__repr__()`` that will
+faithfully reproduce the constructor for that type::
+
+  from sqlalchemy.types import UserDefinedType
+
+  class MySpecialType(UserDefinedType):
+      def __init__(self, precision = 8):
+          self.precision = precision
+
+      def get_col_spec(self):
+          return "MYTYPE(%s)" % self.precision
+
+      def __repr__(self):
+          return "MySpecialType(%d)" % self.precision
+
+The above custom type includes a ``__repr__()`` that will render ``MySpecialType``
+with the appropriate construction.   Sometimes ``__repr__()`` is needed
+with semi-custom types such as those which derive from
+:class:`~sqlalchemy.types.TypeDecorator` as well.
+
+
 Generating SQL Scripts (a.k.a. "Offline Mode")
 ==============================================