diff options
Diffstat (limited to 'lib/sqlalchemy')
| -rw-r--r-- | lib/sqlalchemy/dialects/drizzle/mysqldb.py | 7 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/mysqldb.py | 39 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/oursql.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/oracle/cx_oracle.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/sqlite/pysqlite.py | 17 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/__init__.py | 91 | ||||
| -rw-r--r-- | lib/sqlalchemy/events.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/exc.py | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/__init__.py | 20 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/collections.py | 21 | ||||
| -rw-r--r-- | lib/sqlalchemy/types.py | 186 |
11 files changed, 220 insertions, 174 deletions
diff --git a/lib/sqlalchemy/dialects/drizzle/mysqldb.py b/lib/sqlalchemy/dialects/drizzle/mysqldb.py index dcf02609e..01116fa93 100644 --- a/lib/sqlalchemy/dialects/drizzle/mysqldb.py +++ b/lib/sqlalchemy/dialects/drizzle/mysqldb.py @@ -13,10 +13,11 @@ Connect string format:: drizzle+mysqldb://<user>:<password>@<host>[:<port>]/<dbname> -Character Sets --------------- +Unicode +------- -Drizzle is all utf8 all the time. +Drizzle accommodates Python ``unicode`` objects directly and +uses the ``utf8`` encoding in all cases. Known Issues ------------- diff --git a/lib/sqlalchemy/dialects/mysql/mysqldb.py b/lib/sqlalchemy/dialects/mysql/mysqldb.py index 1b0ea85cb..044b9110a 100644 --- a/lib/sqlalchemy/dialects/mysql/mysqldb.py +++ b/lib/sqlalchemy/dialects/mysql/mysqldb.py @@ -19,35 +19,38 @@ Connect string format:: mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname> -Character Sets --------------- +Unicode +------- -Many MySQL server installations default to a ``latin1`` encoding for client -connections. All data sent through the connection will be converted into -``latin1``, even if you have ``utf8`` or another character set on your tables +MySQLdb will accommodate Python ``unicode`` objects if the +``use_unicode=1`` parameter, or the ``charset`` parameter, +is passed as a connection argument. + +Without this setting, many MySQL server installations default to +a ``latin1`` encoding for client connections, which has the effect +of all data being converted into ``latin1``, even if you have ``utf8`` +or another character set configured on your tables and columns. With versions 4.1 and higher, you can change the connection character set either through server configuration or by including the -``charset`` parameter in the URL used for ``create_engine``. The ``charset`` -option is passed through to MySQL-Python and has the side-effect of also -enabling ``use_unicode`` in the driver by default. For regular encoded -strings, also pass ``use_unicode=0`` in the connection arguments:: +``charset`` parameter. The ``charset`` +parameter as received by MySQL-Python also has the side-effect of +enabling ``use_unicode=1``:: + + # set client encoding to utf8; all strings come back as unicode + create_engine('mysql+mysqldb:///mydb?charset=utf8') - # set client encoding to utf8; all strings come back as unicode - create_engine('mysql+mysqldb:///mydb?charset=utf8') +Manually configuring ``use_unicode=0`` will cause MySQL-python to +return encoded strings:: - # set client encoding to utf8; all strings come back as utf8 str - create_engine('mysql+mysqldb:///mydb?charset=utf8&use_unicode=0') + # set client encoding to utf8; all strings come back as utf8 str + create_engine('mysql+mysqldb:///mydb?charset=utf8&use_unicode=0') Known Issues ------------- MySQL-python version 1.2.2 has a serious memory leak related to unicode conversion, a feature which is disabled via ``use_unicode=0``. -Using a more recent version of MySQL-python is recommended. The -recommended connection form with SQLAlchemy is:: - - engine = create_engine('mysql://scott:tiger@localhost/test?charset=utf8&use_unicode=0', pool_recycle=3600) - +It is strongly advised to use the latest version of MySQL-Python. """ diff --git a/lib/sqlalchemy/dialects/mysql/oursql.py b/lib/sqlalchemy/dialects/mysql/oursql.py index 2678d9dc9..25273a619 100644 --- a/lib/sqlalchemy/dialects/mysql/oursql.py +++ b/lib/sqlalchemy/dialects/mysql/oursql.py @@ -17,8 +17,8 @@ Connect string format:: mysql+oursql://<user>:<password>@<host>[:<port>]/<dbname> -Character Sets --------------- +Unicode +------- oursql defaults to using ``utf8`` as the connection charset, but other encodings may be used instead. Like the MySQL-Python driver, unicode support diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index 29d9e2ab0..078136f70 100644 --- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py +++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py @@ -50,6 +50,8 @@ Unicode cx_oracle 5 fully supports Python unicode objects. SQLAlchemy will pass all unicode strings directly to cx_oracle, and additionally uses an output handler so that all string based result values are returned as unicode as well. +Generally, the ``NLS_LANG`` environment variable determines the nature +of the encoding to be used. Note that this behavior is disabled when Oracle 8 is detected, as it has been observed that issues remain when passing Python unicodes to cx_oracle with Oracle 8. diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py index c8739f242..ad8d5c6f9 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py @@ -173,15 +173,14 @@ way. Unicode ------- -In contrast to SQLAlchemy's active handling of date and time types for pysqlite, pysqlite's -default behavior regarding Unicode is that all strings are returned as Python unicode objects -in all cases. So even if the :class:`~sqlalchemy.types.Unicode` type is -*not* used, you will still always receive unicode data back from a result set. It is -**strongly** recommended that you do use the :class:`~sqlalchemy.types.Unicode` type -to represent strings, since it will raise a warning if a non-unicode Python string is -passed from the user application. Mixing the usage of non-unicode objects with returned unicode objects can -quickly create confusion, particularly when using the ORM as internal data is not -always represented by an actual database result string. +The pysqlite driver only returns Python ``unicode`` objects in result sets, never +plain strings, and accommodates ``unicode`` objects within bound parameter +values in all cases. Regardless of the SQLAlchemy string type in use, +string-based result values will by Python ``unicode`` in Python 2. +The :class:`.Unicode` type should still be used to indicate those columns that +require unicode, however, so that non-``unicode`` values passed inadvertently +will emit a warning. Pysqlite will emit an error if a non-``unicode`` string +is passed containing non-ASCII characters. """ diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 0d091bb11..1835d8a07 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -137,31 +137,31 @@ def create_engine(*args, **kwargs): :ref:`connections_toplevel` - :param assert_unicode: Deprecated. A warning is raised in all cases when a non-Unicode - object is passed when SQLAlchemy would coerce into an encoding - (note: but **not** when the DBAPI handles unicode objects natively). - To suppress or raise this warning to an - error, use the Python warnings filter documented at: - http://docs.python.org/library/warnings.html + :param assert_unicode: Deprecated. This flag + sets an engine-wide default value for + the ``assert_unicode`` flag on the + :class:`.String` type - see that + type for further details. :param connect_args: a dictionary of options which will be passed directly to the DBAPI's ``connect()`` method as - additional keyword arguments. - - :param convert_unicode=False: if set to True, all - String/character based types will convert Python Unicode values to raw - byte values sent to the DBAPI as bind parameters, and all raw byte values to - Python Unicode coming out in result sets. This is an - engine-wide method to provide Unicode conversion across the - board for those DBAPIs that do not accept Python Unicode objects - as input. For Unicode conversion on a column-by-column level, use - the ``Unicode`` column type instead, described in :ref:`types_toplevel`. Note that - many DBAPIs have the ability to return Python Unicode objects in - result sets directly - SQLAlchemy will use these modes of operation - if possible and will also attempt to detect "Unicode returns" - behavior by the DBAPI upon first connect by the - :class:`.Engine`. When this is detected, string values in - result sets are passed through without further processing. + additional keyword arguments. See the example + at :ref:`custom_dbapi_args`. + + :param convert_unicode=False: if set to True, sets + the default behavior of ``convert_unicode`` on the + :class:`.String` type to ``True``, regardless + of a setting of ``False`` on an individual + :class:`.String` type, thus causing all :class:`.String` + -based columns + to accommodate Python ``unicode`` objects. This flag + is useful as an engine-wide setting when using a + DBAPI that does not natively support Python + ``unicode`` objects and raises an error when + one is received (such as pyodbc with FreeTDS). + + See :class:`.String` for further details on + what this flag indicates. :param creator: a callable which returns a DBAPI connection. This creation function will be passed to the underlying @@ -184,9 +184,50 @@ def create_engine(*args, **kwargs): :ref:`dbengine_logging` for information on how to configure logging directly. - :param encoding='utf-8': the encoding to use for all Unicode - translations, both by engine-wide unicode conversion as well as - the ``Unicode`` type object. + :param encoding: Defaults to ``utf-8``. This is the string + encoding used by SQLAlchemy for string encode/decode + operations which occur within SQLAlchemy, **outside of + the DBAPI.** Most modern DBAPIs feature some degree of + direct support for Python ``unicode`` objects, + what you see in Python 2 as a string of the form + ``u'some string'``. For those scenarios where the + DBAPI is detected as not supporting a Python ``unicode`` + object, this encoding is used to determine the + source/destination encoding. It is **not used** + for those cases where the DBAPI handles unicode + directly. + + To properly configure a system to accommodate Python + ``unicode`` objects, the DBAPI should be + configured to handle unicode to the greatest + degree as is appropriate - see + the notes on unicode pertaining to the specific + target database in use at :ref:`dialect_toplevel`. + + Areas where string encoding may need to be accommodated + outside of the DBAPI include zero or more of: + + * the values passed to bound parameters, corresponding to + the :class:`.Unicode` type or the :class:`.String` type + when ``convert_unicode`` is ``True``; + * the values returned in result set columns corresponding + to the :class:`.Unicode` type or the :class:`.String` + type when ``convert_unicode`` is ``True``; + * the string SQL statement passed to the DBAPI's + ``cursor.execute()`` method; + * the string names of the keys in the bound parameter + dictionary passed to the DBAPI's ``cursor.execute()`` + as well as ``cursor.setinputsizes()`` methods; + * the string column names retrieved from the DBAPI's + ``cursor.description`` attribute. + + When using Python 3, the DBAPI is required to support + *all* of the above values as Python ``unicode`` objects, + which in Python 3 are just known as ``str``. In Python 2, + the DBAPI does not specify unicode behavior at all, + so SQLAlchemy must make decisions for each of the above + values on a per-DBAPI basis - implementations are + completely inconsistent in their behavior. :param execution_options: Dictionary execution options which will be applied to all connections. See diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py index eee2a7557..adfbd1966 100644 --- a/lib/sqlalchemy/events.py +++ b/lib/sqlalchemy/events.py @@ -312,7 +312,7 @@ class PoolEvents(event.Events): The ``_ConnectionFairy`` which manages the connection for the span of the current checkout. - If you raise an ``exc.DisconnectionError``, the current + If you raise a :class:`~sqlalchemy.exc.DisconnectionError`, the current connection will be disposed and a fresh connection retrieved. Processing of all checkout listeners will abort and restart using the new connection. diff --git a/lib/sqlalchemy/exc.py b/lib/sqlalchemy/exc.py index d375807b2..57ddb11ef 100644 --- a/lib/sqlalchemy/exc.py +++ b/lib/sqlalchemy/exc.py @@ -63,7 +63,10 @@ class DisconnectionError(SQLAlchemyError): """A disconnect is detected on a raw DB-API connection. This error is raised and consumed internally by a connection pool. It can - be raised by a ``PoolListener`` so that the host pool forces a disconnect. + be raised by the :meth:`.PoolEvents.checkout` event + so that the host pool forces a retry; the exception will be caught + three times in a row before the pool gives up and raises + :class:`~sqlalchemy.exc.InvalidRequestError` regarding the connection attempt. """ diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 4c6d30d32..ec4f39fdf 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -427,11 +427,8 @@ def relationship(argument, secondary=None, **kwargs): * ``dynamic`` - the attribute will return a pre-configured :class:`~sqlalchemy.orm.query.Query` object for all read operations, onto which further filtering operations can be - applied before iterating the results. The dynamic - collection supports a limited set of mutation operations, - allowing ``append()`` and ``remove()``. Changes to the - collection will not be visible until flushed - to the database, where it is then refetched upon iteration. + applied before iterating the results. See + the section :ref:`dynamic_relationship` for more details. * True - a synonym for 'select' @@ -627,19 +624,12 @@ def dynamic_loader(argument, **kw): dynamic_loader(SomeClass) - # vs. + # is the same as relationship(SomeClass, lazy="dynamic") - A :func:`relationship` that is "dynamic" features the behavior - that read operations return an active :class:`.Query` object which - reads from the database when accessed. Items may be appended to the - attribute via ``append()``, or removed via ``remove()``; changes will be - persisted to the database during a :meth:`Sesion.flush`. However, no other - Python list or collection mutation operations are available. - - All arguments accepted by :func:`relationship` are - accepted here, other than ``lazy`` which is fixed at ``dynamic``. + See the section :ref:`dynamic_relationship` for more details + on dynamic loading. """ kw['lazy'] = 'dynamic' diff --git a/lib/sqlalchemy/orm/collections.py b/lib/sqlalchemy/orm/collections.py index 7ac70fe5a..d605d849b 100644 --- a/lib/sqlalchemy/orm/collections.py +++ b/lib/sqlalchemy/orm/collections.py @@ -122,7 +122,7 @@ __instrumentation_mutex = util.threading.Lock() def column_mapped_collection(mapping_spec): """A dictionary-based collection type with column-based keying. - Returns a MappedCollection factory with a keying function generated + Returns a :class:`.MappedCollection` factory with a keying function generated from mapping_spec, which may be a Column or a sequence of Columns. The key value must be immutable for the lifetime of the object. You @@ -153,7 +153,7 @@ def column_mapped_collection(mapping_spec): def attribute_mapped_collection(attr_name): """A dictionary-based collection type with attribute-based keying. - Returns a MappedCollection factory with a keying based on the + Returns a :class:`.MappedCollection` factory with a keying based on the 'attr_name' attribute of entities in the collection, where ``attr_name`` is the string name of the attribute. @@ -169,7 +169,7 @@ def attribute_mapped_collection(attr_name): def mapped_collection(keyfunc): """A dictionary-based collection type with arbitrary keying. - Returns a MappedCollection factory with a keying function generated + Returns a :class:`.MappedCollection` factory with a keying function generated from keyfunc, a callable that takes an entity and returns a key value. The key value must be immutable for the lifetime of the object. You @@ -201,10 +201,6 @@ class collection(object): @collection.removes_return() def popitem(self): ... - Decorators can be specified in long-hand for Python 2.3, or with - the class-level dict attribute '__instrumentation__'- see the source - for details. - """ # Bundled as a class solely for ease of use: packaging, doc strings, # importability. @@ -474,7 +470,7 @@ class CollectionAdapter(object): to the underlying Python collection, and emits add/remove events for entities entering or leaving the collection. - The ORM uses an CollectionAdapter exclusively for interaction with + The ORM uses :class:`.CollectionAdapter` exclusively for interaction with entity collections. The usage of getattr()/setattr() is currently to allow injection @@ -664,14 +660,11 @@ def bulk_replace(values, existing_adapter, new_adapter): instances in ``existing_adapter`` not present in ``values`` will have remove events fired upon them. - values - An iterable of collection member instances + :param values: An iterable of collection member instances - existing_adapter - A CollectionAdapter of instances to be replaced + :param existing_adapter: A :class:`.CollectionAdapter` of instances to be replaced - new_adapter - An empty CollectionAdapter to load with ``values`` + :param new_adapter: An empty :class:`.CollectionAdapter` to load with ``values`` """ diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py index 136de147e..1ad1280f5 100644 --- a/lib/sqlalchemy/types.py +++ b/lib/sqlalchemy/types.py @@ -962,53 +962,55 @@ class String(Concatenable, TypeEngine): :param length: optional, a length for the column for use in DDL statements. May be safely omitted if no ``CREATE TABLE`` will be issued. Certain databases may require a - *length* for use in DDL, and will raise an exception when - the ``CREATE TABLE`` DDL is issued. Whether the value is + ``length`` for use in DDL, and will raise an exception when + the ``CREATE TABLE`` DDL is issued if a ``VARCHAR`` + with no length is included. Whether the value is interpreted as bytes or characters is database specific. - :param convert_unicode: defaults to False. If True, the - type will do what is necessary in order to accept - Python Unicode objects as bind parameters, and to return - Python Unicode objects in result rows. This may - require SQLAlchemy to explicitly coerce incoming Python - unicodes into an encoding, and from an encoding - back to Unicode, or it may not require any interaction - from SQLAlchemy at all, depending on the DBAPI in use. - - When SQLAlchemy performs the encoding/decoding, - the encoding used is configured via - :attr:`~sqlalchemy.engine.base.Dialect.encoding`, which - defaults to `utf-8`. - - The "convert_unicode" behavior can also be turned on - for all String types by setting - :attr:`sqlalchemy.engine.base.Dialect.convert_unicode` - on create_engine(). - - To instruct SQLAlchemy to perform Unicode encoding/decoding - even on a platform that already handles Unicode natively, - set convert_unicode='force'. This will incur significant - performance overhead when fetching unicode result columns. - - :param assert_unicode: Deprecated. A warning is raised in all cases - when a non-Unicode object is passed when SQLAlchemy would coerce - into an encoding (note: but **not** when the DBAPI handles unicode - objects natively). To suppress or raise this warning to an error, - use the Python warnings filter documented at: - http://docs.python.org/library/warnings.html + :param convert_unicode: When set to ``True``, the + :class:`.String` type will assume that + input is to be passed as Python ``unicode`` objects, + and results returned as Python ``unicode`` objects. + If the DBAPI in use does not support Python unicode + (which is fewer and fewer these days), SQLAlchemy + will encode/decode the value, using the + value of the ``encoding`` parameter passed to + :func:`.create_engine` as the encoding. + + When using a DBAPI that natively supports Python + unicode objects, this flag generally does not + need to be set. For columns that are explicitly + intended to store non-ASCII data, the :class:`.Unicode` + or :class:`UnicodeText` + types should be used regardless, which feature + the same behavior of ``convert_unicode`` but + also indicate an underlying column type that + directly supports unicode, such as ``NVARCHAR``. + + For the extremely rare case that Python ``unicode`` + is to be encoded/decoded by SQLAlchemy on a backend + that does natively support Python ``unicode``, + the value ``force`` can be passed here which will + cause SQLAlchemy's encode/decode services to be + used unconditionally. + + :param assert_unicode: Deprecated. A warning is emitted + when a non-``unicode`` object is passed to the + :class:`.Unicode` subtype of :class:`.String`, + or the :class:`.UnicodeText` subtype of :class:`.Text`. + See :class:`.Unicode` for information on how to + control this warning. :param unicode_error: Optional, a method to use to handle Unicode - conversion errors. Behaves like the 'errors' keyword argument to - the standard library's string.decode() functions. This flag - requires that `convert_unicode` is set to `"force"` - otherwise, + conversion errors. Behaves like the ``errors`` keyword argument to + the standard library's ``string.decode()`` functions. This flag + requires that ``convert_unicode`` is set to ``force`` - otherwise, SQLAlchemy is not guaranteed to handle the task of unicode conversion. Note that this flag adds significant performance overhead to row-fetching operations for backends that already return unicode objects natively (which most DBAPIs do). This - flag should only be used as an absolute last resort for reading - strings from a column with varied or corrupted encodings, - which only applies to databases that accept invalid encodings - in the first place (i.e. MySQL. *not* PG, Sqlite, etc.) + flag should only be used as a last resort for reading + strings from a column with varied or corrupted encodings. """ if unicode_error is not None and convert_unicode != 'force': @@ -1109,37 +1111,57 @@ class Text(String): __visit_name__ = 'text' class Unicode(String): - """A variable length Unicode string. - - The ``Unicode`` type is a :class:`.String` which converts Python - ``unicode`` objects (i.e., strings that are defined as - ``u'somevalue'``) into encoded bytestrings when passing the value - to the database driver, and similarly decodes values from the - database back into Python ``unicode`` objects. - - It's roughly equivalent to using a ``String`` object with - ``convert_unicode=True``, however - the type has other significances in that it implies the usage - of a unicode-capable type being used on the backend, such as NVARCHAR. - This may affect what type is emitted when issuing CREATE TABLE - and also may effect some DBAPI-specific details, such as type - information passed along to ``setinputsizes()``. - - When using the ``Unicode`` type, it is only appropriate to pass - Python ``unicode`` objects, and not plain ``str``. If a - bytestring (``str``) is passed, a runtime warning is issued. If - you notice your application raising these warnings but you're not - sure where, the Python ``warnings`` filter can be used to turn - these warnings into exceptions which will illustrate a stack - trace:: + """A variable length Unicode string type. + + The :class:`.Unicode` type is a :class:`.String` subclass + that assumes input and output as Python ``unicode`` data, + and in that regard is equivalent to the usage of the + ``convert_unicode`` flag with the :class:`.String` type. + However, unlike plain :class:`.String`, it also implies an + underlying column type that is explicitly supporting of non-ASCII + data, such as ``NVARCHAR`` on Oracle and SQL Server. + This can impact the output of ``CREATE TABLE`` statements + and ``CAST`` functions at the dialect level, and can + also affect the handling of bound parameters in some + specific DBAPI scenarios. + + The encoding used by the :class:`.Unicode` type is usually + determined by the DBAPI itself; most modern DBAPIs + feature support for Python ``unicode`` objects as bound + values and result set values, and the encoding should + be configured as detailed in the notes for the target + DBAPI in the :ref:`dialect_toplevel` section. + + For those DBAPIs which do not support, or are not configured + to accommodate Python ``unicode`` objects + directly, SQLAlchemy does the encoding and decoding + outside of the DBAPI. The encoding in this scenario + is determined by the ``encoding`` flag passed to + :func:`.create_engine`. + + When using the :class:`.Unicode` type, it is only appropriate + to pass Python ``unicode`` objects, and not plain ``str``. + If a plain ``str`` is passed under Python 2, a warning + is emitted. If you notice your application emitting these warnings but + you're not sure of the source of them, the Python + ``warnings`` filter, documented at + http://docs.python.org/library/warnings.html, + can be used to turn these warnings into exceptions + which will illustrate a stack trace:: import warnings warnings.simplefilter('error') - Bytestrings sent to and received from the database are encoded - using the dialect's - :attr:`~sqlalchemy.engine.base.Dialect.encoding`, which defaults - to `utf-8`. + For an application that wishes to pass plain bytestrings + and Python ``unicode`` objects to the ``Unicode`` type + equally, the bytestrings must first be decoded into + unicode. The recipe at :ref:`coerce_to_unicode` illustrates + how this is done. + + See also: + + :class:`.UnicodeText` - unlengthed textual counterpart + to :class:`.Unicode`. """ @@ -1147,17 +1169,11 @@ class Unicode(String): def __init__(self, length=None, **kwargs): """ - Create a Unicode-converting String type. - - :param length: optional, a length for the column for use in - DDL statements. May be safely omitted if no ``CREATE - TABLE`` will be issued. Certain databases may require a - *length* for use in DDL, and will raise an exception when - the ``CREATE TABLE`` DDL is issued. Whether the value is - interpreted as bytes or characters is database specific. - - :param \**kwargs: passed through to the underlying ``String`` - type. + Create a :class:`.Unicode` object. + + Parameters are the same as that of :class:`.String`, + with the exception that ``convert_unicode`` + defaults to ``True``. """ kwargs.setdefault('convert_unicode', True) @@ -1165,13 +1181,14 @@ class Unicode(String): super(Unicode, self).__init__(length=length, **kwargs) class UnicodeText(Text): - """An unbounded-length Unicode string. + """An unbounded-length Unicode string type. See :class:`.Unicode` for details on the unicode behavior of this object. - Like ``Unicode``, usage the ``UnicodeText`` type implies a - unicode-capable type being used on the backend, such as NCLOB. + Like :class:`.Unicode`, usage the :class:`.UnicodeText` type implies a + unicode-capable type being used on the backend, such as + ``NCLOB``, ``NTEXT``. """ @@ -1181,12 +1198,9 @@ class UnicodeText(Text): """ Create a Unicode-converting Text type. - :param length: optional, a length for the column for use in - DDL statements. May be safely omitted if no ``CREATE - TABLE`` will be issued. Certain databases may require a - *length* for use in DDL, and will raise an exception when - the ``CREATE TABLE`` DDL is issued. Whether the value is - interpreted as bytes or characters is database specific. + Parameters are the same as that of :class:`.Text`, + with the exception that ``convert_unicode`` + defaults to ``True``. """ kwargs.setdefault('convert_unicode', True) |