sqlalchemy.types.String

class documentation

class String(Concatenable, TypeEngine):

Known subclasses: sqlalchemy.types.CHAR, sqlalchemy.types.Enum, sqlalchemy.types.Text, sqlalchemy.types.Unicode, sqlalchemy.types.VARCHAR, sqlalchemy.databases.firebird._StringType, sqlalchemy.dialects.mysql.types._StringType, sqlalchemy.dialects.oracle.cx_oracle._OracleString

View In Hierarchy

The base for all string and character types.

In SQL, corresponds to VARCHAR. Can also take Python unicode objects and encode to the database's encoding in bind params (and the reverse for result sets.)

The length field is usually required when the String type is used within a CREATE TABLE statement, as VARCHAR requires a length on most databases.

Method	`__init__`	Create a string-holding type.
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
Class Variable	`__visit_name__`	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:

Class Comparator Undocumented

Inherited from TypeEngine:

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 TypeEngine):

Method	`get_children`	Return immediate child `.visitors.Traversible` elements of this `.visitors.Traversible`.
Method	`__class_getitem__`	Undocumented

@util.deprecated_params(convert_unicode=('1.3', 'The :paramref:`.String.convert_unicode` parameter is deprecated and will be removed in a future release. All modern DBAPIs now support Python Unicode directly and this parameter is unnecessary.'), unicode_error=('1.3', 'The :paramref:`.String.unicode_errors` parameter is deprecated and will be removed in a future release. This parameter is unnecessary for modern Python DBAPIs and degrades performance significantly.'))
def __init__(self, length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False):

overridden in sqlalchemy.dialects.mysql.types.CHAR, sqlalchemy.dialects.mysql.types.TEXT, sqlalchemy.dialects.mysql.types.VARCHAR, sqlalchemy.types.Enum, sqlalchemy.types.Unicode, sqlalchemy.types.UnicodeText, sqlalchemy.databases.firebird._StringType, sqlalchemy.dialects.firebird.CHAR, sqlalchemy.dialects.firebird.VARCHAR, sqlalchemy.dialects.mysql.types._StringType

Create a string-holding type.

Parameters
length	optional, a length for the column for use in DDL and CAST expressions. 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 if a `VARCHAR` with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation	Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.: >>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
convert_unicode	When set to `True`, the `.String` type will assume that input is to be passed as Python Unicode objects under Python 2, and results returned as Python Unicode objects. In the rare circumstance that the DBAPI does not support Python unicode under Python 2, SQLAlchemy will use its own encoder/decoder functionality on strings, referring to the value of the :paramref:`_sa.create_engine.encoding` parameter parameter passed to `_sa.create_engine` as the encoding. 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 string value `"force"` can be passed here which will cause SQLAlchemy's encode/decode services to be used unconditionally. Note SQLAlchemy's unicode-conversion flags and features only apply to Python 2; in Python 3, all string objects are Unicode objects. For this reason, as well as the fact that virtually all modern DBAPIs now support Unicode natively even under Python 2, the :paramref:`.String.convert_unicode` flag is inherently a legacy feature. Note In the vast majority of cases, the `.Unicode` or `.UnicodeText` datatypes should be used for a `_schema.Column` that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database side as well as set up the correct Unicode behaviors under Python 2. See Also :paramref:`_sa.create_engine.convert_unicode` - `_engine.Engine`-wide parameter
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, requires that :paramref:`.String.convert_unicode` is set to `"force"`
_warn_on_bytestring	Undocumented
_expect_unicode	Undocumented

def bind_processor(self, dialect):

overrides sqlalchemy.types.TypeEngine.bind_processor

overridden in sqlalchemy.dialects.mysql.enumerated.SET, sqlalchemy.types.Enum

Return a conversion function for processing bind values.

Returns a callable which will receive a bind parameter value as the sole positional argument and will return a value to send to the DB-API.

If processing is not necessary, the method should return None.

Note

This method is only called relative to a dialect specific type object, which is often private to a dialect in use and is not the same type object as the public facing one, which means it's not feasible to subclass a .types.TypeEngine class in order to provide an alternate _types.TypeEngine.bind_processor method, unless subclassing the _types.UserDefinedType class explicitly.

To provide alternate behavior for _types.TypeEngine.bind_processor, implement a _types.TypeDecorator class and provide an implementation of _types.TypeDecorator.process_bind_param.

Parameters
dialect	Dialect instance in use.
coltype	DBAPI coltype argument received in cursor.description.