# granite_storage.types

class granite_storage.types.StoredObjectRefType(*args: Any, **kwargs: Any)

  Bases: `TypeDecorator`

  cache_ok = True

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

    Added in version 1.4.14: - added the `cache_ok` flag to allow some configurability of caching for `TypeDecorator` classes.

    Added in version 1.4.28: - added the `ExternalType` mixin which generalizes the `cache_ok` flag to both the `TypeDecorator` and `UserDefinedType` classes.

    See also

    SQL Compilation Caching

  impl = JSON()
  process_bind_param(value: StoredObjectRef | dict[str, Any] | None, dialect: Any) → dict[str, Any] | None

    Receive a bound parameter value to be converted.

    Custom subclasses of `_types.TypeDecorator` should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

    The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

    Parameters:

      - value – Data to operate upon, of any type expected by this method in the subclass. Can be `None`.

      - dialect – the `Dialect` in use.

    See also

    Augmenting Existing Types

    `_types.TypeDecorator.process_result_value()`

  process_result_value(value: dict[str, Any] | None, dialect: Any) → StoredObjectRef | None

    Receive a result-row column value to be converted.

    Custom subclasses of `_types.TypeDecorator` should override this method to provide custom behaviors for data values being received in result rows coming from the database. This method is called at result fetching time and is passed the literal Python data value that’s extracted from a database result row.

    The operation could be anything desired to perform custom behavior, such as transforming or deserializing data.

    Parameters:

      - value – Data to operate upon, of any type expected by this method in the subclass. Can be `None`.

      - dialect – the `Dialect` in use.

    See also

    Augmenting Existing Types

    `_types.TypeDecorator.process_bind_param()`