class Unicode(String):
Known subclasses: sqlalchemy.types.NCHAR
, sqlalchemy.types.NVARCHAR
, sqlalchemy.databases.mssql._MSUnicode
, sqlalchemy.dialects.oracle.cx_oracle._OracleUnicodeStringCHAR
, sqlalchemy.dialects.sybase.UNICHAR
, sqlalchemy.dialects.sybase.UNIVARCHAR
A variable length Unicode string type.
The .Unicode
type is a .String
subclass that assumes
input and output strings that may contain non-ASCII characters, and for
some backends implies an underlying column type that is explicitly
supporting of non-ASCII data, such as NVARCHAR on Oracle and SQL
Server. This will impact the output of CREATE TABLE statements and
CAST functions at the dialect level, and also in some cases will
indicate different behavior in the DBAPI itself in how it handles bound
parameters.
The character encoding used by the .Unicode
type that is used to
transmit and receive data to the database is usually determined by the
DBAPI itself. All modern DBAPIs accommodate non-ASCII strings but may have
different methods of managing database encodings; if necessary, this
encoding should be configured as detailed in the notes for the target DBAPI
in the :ref:`dialect_toplevel` section.
In modern SQLAlchemy, use of the .Unicode
datatype does not
typically imply any encoding/decoding behavior within SQLAlchemy itself.
Historically, when DBAPIs did not support Python unicode objects under
Python 2, SQLAlchemy handled unicode encoding/decoding services itself
which would be controlled by the flag :paramref:`.String.convert_unicode`;
this flag is deprecated as it is no longer needed for Python 3.
When using Python 2, data that is passed to columns that use the
.Unicode
datatype must be of type unicode, and not str
which in Python 2 is equivalent to bytes. In Python 3, all data
passed to columns that use the .Unicode
datatype should be
of type str. See the flag :paramref:`.String.convert_unicode` for
more discussion of unicode encode/decode behavior under Python 2.
Warning
Some database backends, particularly SQL Server with pyodbc,
are known to have undesirable behaviors regarding data that is noted
as being of NVARCHAR type as opposed to VARCHAR, including
datatype mismatch errors and non-use of indexes. See the section
on .DialectEvents.do_setinputsizes
for background on working
around unicode character issues for backends like SQL Server with
pyodbc as well as cx_Oracle.
See Also
.UnicodeText
- unlengthed textual counterpart
to .Unicode
.
:paramref:`.String.convert_unicode`
.DialectEvents.do_setinputsizes
Method | __init__ |
Create a .Unicode object. |
Class Variable | __visit_name__ |
Undocumented |
Inherited from String
:
Method | bind_processor |
Return a conversion function for processing bind values. |
Method | get_dbapi_type |
Return the corresponding type object from the underlying DB-API, if any. |
Method | literal_processor |
Return a conversion function for processing literal values that are to be rendered directly without using binds. |
Method | result_processor |
Return a conversion function for processing result row values. |
Constant | RETURNS_BYTES |
Undocumented |
Constant | RETURNS_CONDITIONAL |
Undocumented |
Constant | RETURNS_UNICODE |
Undocumented |
Constant | RETURNS_UNKNOWN |
Undocumented |
Class Method | _warn_deprecated_unicode |
Undocumented |
Instance Variable | _expect_unicode |
Undocumented |
Instance Variable | _expect_unicode_error |
Undocumented |
Instance Variable | _warn_on_bytestring |
Undocumented |
Instance Variable | collation |
Undocumented |
Instance Variable | length |
Undocumented |
Property | python_type |
Return the Python type object expected to be returned by instances of this type, if known. |
Inherited from Concatenable
(via String
):
Class | Comparator |
Undocumented |
Inherited from TypeEngine
(via String
):
Class | Comparator |
Base class for custom comparison operations defined at the type level. See .TypeEngine.comparator_factory . |
Method | adapt |
Produce an "adapted" form of this type, given an "impl" class to work with. |
Method | as_generic |
Return an instance of the generic type corresponding to this type using heuristic rule. The method may be overridden if this heuristic rule is not sufficient. |
Method | bind_expression |
Given a bind value (i.e. a .BindParameter instance), return a SQL expression in its place. |
Method | coerce_compared_value |
Suggest a type for a 'coerced' Python value in an expression. |
Method | column_expression |
Given a SELECT column expression, return a wrapping SQL expression. |
Method | compare_against_backend |
Compare this type against the given backend type. |
Method | compare_values |
Compare two values for equality. |
Method | compile |
Produce a string-compiled form of this .TypeEngine . |
Method | dialect_impl |
Return a dialect-specific implementation for this .TypeEngine . |
Method | evaluates_none |
Return a copy of this type which has the .should_evaluate_none flag set to True. |
Method | with_variant |
Produce a new type object that will utilize the given type when applied to the dialect of the given name. |
Class Variable | hashable |
Flag, if False, means values from this type aren't hashable. |
Class Variable | should_evaluate_none |
If True, the Python constant None is considered to be handled explicitly by this type. |
Class Variable | sort_key_function |
A sorting function that can be passed as the key to sorted. |
Static Method | _to_instance |
Undocumented |
Method | __repr__ |
Undocumented |
Method | __str__ |
Undocumented |
Method | _cached_bind_processor |
Return a dialect-specific bind processor for this type. |
Method | _cached_custom_processor |
Undocumented |
Method | _cached_literal_processor |
Return a dialect-specific literal processor for this type. |
Method | _cached_result_processor |
Return a dialect-specific result processor for this type. |
Method | _compare_type_affinity |
Undocumented |
Method | _default_dialect |
Undocumented |
Method | _dialect_info |
Return a dialect-specific registry which caches a dialect-specific implementation, bind processing function, and one or more result processing functions. |
Method | _gen_dialect_impl |
Undocumented |
Method | _resolve_for_literal |
adjust this type given a literal Python value that will be stored in a bound parameter. |
Method | _unwrapped_dialect_impl |
Return the 'unwrapped' dialect impl for this type. |
Method | copy |
Undocumented |
Method | copy_value |
Undocumented |
Class Variable | _is_array |
Undocumented |
Class Variable | _is_table_value |
Undocumented |
Class Variable | _is_tuple_type |
Undocumented |
Class Variable | _is_type_decorator |
Undocumented |
Class Variable | _isnull |
Undocumented |
Class Variable | _sqla_type |
Undocumented |
Property | _generic_type_affinity |
Undocumented |
Property | _has_bind_expression |
memoized boolean, check if bind_expression is implemented. |
Property | _has_column_expression |
memoized boolean, check if column_expression is implemented. |
Property | _static_cache_key |
Undocumented |
Property | _type_affinity |
Return a rudimental 'affinity' value expressing the general class of type. |
Inherited from Traversible
(via String
, TypeEngine
):
Method | get_children |
Return immediate child .visitors.Traversible elements of this .visitors.Traversible . |
Method | __class_getitem__ |
Undocumented |
sqlalchemy.types.String.__init__
Create a .Unicode
object.
Parameters are the same as that of .String
,
with the exception that convert_unicode
defaults to True.
str
=
sqlalchemy.types.String.__visit_name__
sqlalchemy.types.NCHAR
, sqlalchemy.types.NVARCHAR
, sqlalchemy.dialects.sybase.UNICHAR
, sqlalchemy.dialects.sybase.UNIVARCHAR
Undocumented