class PickleType(TypeDecorator):
Holds Python objects, which are serialized using pickle.
PickleType builds upon the Binary type to apply Python's pickle.dumps() to incoming objects, and pickle.loads() on the way out, allowing any pickleable Python object to be stored as a serialized binary field.
To allow ORM change events to propagate for elements associated
with .PickleType
, see :ref:`mutable_toplevel`.
Method | __init__ |
Construct a PickleType. |
Method | bind_processor |
Provide a bound value processing function for the given .Dialect . |
Method | compare_values |
Given two values, compare them for equality. |
Method | result_processor |
Provide a result value processing function for the given .Dialect . |
Instance Variable | impl |
Undocumented |
Method | __reduce__ |
Undocumented |
Class Variable | cache_ok |
Indicate if statements using this .ExternalType are "safe to cache". |
Instance Variable | comparator |
Undocumented |
Instance Variable | pickler |
Undocumented |
Instance Variable | protocol |
Undocumented |
Inherited from TypeDecorator
:
Class | Comparator |
A .TypeEngine.Comparator that is specific to .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 | 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 | 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 | 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 |
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 |
sqlalchemy.types.TypeDecorator.__init__
Parameters | |
protocol | defaults to pickle.HIGHEST_PROTOCOL. |
pickler | defaults to cPickle.pickle or pickle.pickle if cPickle is not available. May be any object with pickle-compatible dumps and loads methods. |
comparator | a 2-arg callable predicate used to compare values of this type. If left as None, the Python "equals" operator is used to compare values. |
impl | A binary-storing
New in version 1.4.20.
|
Provide a bound value processing function for the
given .Dialect
.
This is the method that fulfills the .TypeEngine
contract for bound value conversion which normally occurs via
the _types.TypeEngine.bind_processor
method.
Note
User-defined subclasses of _types.TypeDecorator
should
not implement this method, and should instead implement
_types.TypeDecorator.process_bind_param
so that the "inner"
processing provided by the implementing type is maintained.
Parameters | |
dialect | Dialect instance in use. |
Given two values, compare them for equality.
By default this calls upon .TypeEngine.compare_values
of the underlying "impl", which in turn usually
uses the Python equals operator ==.
This function is used by the ORM to compare an original-loaded value with an intercepted "changed" value, to determine if a net change has occurred.
Provide a result value processing function for the given
.Dialect
.
This is the method that fulfills the .TypeEngine
contract for bound value conversion which normally occurs via
the _types.TypeEngine.result_processor
method.
Note
User-defined subclasses of _types.TypeDecorator
should
not implement this method, and should instead implement
_types.TypeDecorator.process_result_value
so that the
"inner" processing provided by the implementing type is maintained.
Parameters | |
dialect | Dialect instance in use. |
coltype | A SQLAlchemy data type |
bool
=
sqlalchemy.types.ExternalType.cache_ok
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))))
.TypeDecorator
classes..ExternalType
mixin which
generalizes the cache_ok flag to both the .TypeDecorator
and .UserDefinedType
classes.See Also