class documentation

class IdentitySqlVariant(TypeDecorator):

View In Hierarchy

This type casts sql_variant columns in the identity_columns view to numeric. This is required because:

  • pyodbc does not support sql_variant
  • pymssql under python 2 return the byte representation of the number, int 1 is returned as "x01x00x00x00". On python 3 it returns the correct value as string.
Method column​_expression Given a SELECT column expression, return a wrapping SQL expression.
Class Variable cache​_ok Indicate if statements using this .ExternalType are "safe to cache".

Inherited from TypeDecorator:

Class ​Comparator A .TypeEngine.Comparator that is specific to .TypeDecorator.
Method __init__ Construct a .TypeDecorator.
Method bind​_expression Given a bind value (i.e. a .BindParameter instance), return a SQL expression which will typically wrap the given parameter.
Method bind​_processor Provide a bound value processing function for the given .Dialect.
Method coerce​_compared​_value Suggest a type for a 'coerced' Python value in an expression.
Method compare​_values Given two values, compare them for equality.
Method copy Produce a copy of this .TypeDecorator instance.
Method get​_dbapi​_type Return the DBAPI type object represented by this .TypeDecorator.
Method literal​_processor Provide a literal processing function for the given .Dialect.
Method load​_dialect​_impl Return a .TypeEngine object corresponding to a dialect.
Method process​_bind​_param Receive a bound parameter value to be converted.
Method process​_literal​_param Receive a literal parameter value to be rendered inline within a statement.
Method process​_result​_value Receive a result-row column value to be converted.
Method result​_processor Provide a result value processing function for the given .Dialect.
Method type​_engine Return a dialect-specific .TypeEngine instance for this .TypeDecorator.
Class Variable coerce​_to​_is​_types Specify those Python types which should be coerced at the expression level to "IS <constant>" when compared using == (and same for IS NOT in conjunction with !=).
Method __getattr__ Proxy all other undefined accessors to the underlying implementation.
Method __repr__ Undocumented
Method ​_gen​_dialect​_impl #todo
Method ​_set​_parent Support SchemaEventTarget
Method ​_set​_parent​_with​_dispatch Support SchemaEventTarget
Method ​_unwrapped​_dialect​_impl Return the 'unwrapped' dialect impl for this type.
Class Variable __visit​_name__ Undocumented
Class Variable ​_is​_type​_decorator Undocumented
Instance Variable impl Undocumented
Property ​_has​_bind​_expression memoized boolean, check if bind_expression is implemented.
Property ​_has​_bind​_processor memoized boolean, check if process_bind_param is implemented.
Property ​_has​_column​_expression memoized boolean, check if column_expression is implemented.
Property ​_has​_literal​_processor memoized boolean, check if process_literal_param is implemented.
Property ​_has​_result​_processor memoized boolean, check if process_result_value is implemented.
Property ​_type​_affinity #todo
Property comparator​_factory Undocumented
Property sort​_key​_function A sorting function that can be passed as the key to sorted.

Inherited from ExternalType (via TypeDecorator):

Property ​_static​_cache​_key Undocumented

Inherited from TypeEngine (via TypeDecorator):

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 compare​_against​_backend Compare this type against the given backend type.
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.
Static Method ​_to​_instance 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 ​_resolve​_for​_literal adjust this type given a literal Python value that will be stored in a bound parameter.
Method copy​_value Undocumented
Class Variable ​_is​_array Undocumented
Class Variable ​_is​_table​_value Undocumented
Class Variable ​_is​_tuple​_type Undocumented
Class Variable ​_isnull Undocumented
Class Variable ​_sqla​_type Undocumented
Property ​_generic​_type​_affinity Undocumented
Property ​_static​_cache​_key Undocumented
Property python​_type Return the Python type object expected to be returned by instances of this type, if known.

Inherited from Traversible (via TypeDecorator, TypeEngine):

Method get​_children Return immediate child .visitors.Traversible elements of this .visitors.Traversible.
Method __class​_getitem__ Undocumented
def column_expression(self, colexpr):

Given a SELECT column expression, return a wrapping SQL expression.

Note

This method is called during the SQL compilation phase of a statement, when rendering a SQL string. It is not called against specific values, and should not be confused with the _types.TypeDecorator.process_result_value method, which is the more typical method that processes the actual value returned in a result row subsequent to statement execution time.

Subclasses of _types.TypeDecorator can override this method to provide custom column expresion behavior for the type. This implementation will replace that of the underlying implementation type.

See the description of _types.TypeEngine.column_expression for a complete description of the method's use.

cache_ok: bool =

Indicate if statements using this .ExternalType are "safe to cache".

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object's class and selected elements from its state will be used as part of the cache key. For example, using a .TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the "choices" attribute becomes part of the cache key but "internal_only" does not, because there is no parameter named "internal_only".

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made "cacheable" by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    '''a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    '''

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self.lookup" ...

Where "lookup" is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn't be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a "cache dictionary" such as SQLAlchemy's statement cache, since Python dictionaries aren't hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the ".lookup" attribute:

class LookupType(UserDefinedType):
    '''a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    '''

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple(
            (key, lookup[key]) for key in sorted(lookup)
        )

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))
New in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for .TypeDecorator classes.
New in version 1.4.28: - added the .ExternalType mixin which generalizes the cache_ok flag to both the .TypeDecorator and .UserDefinedType classes.