convert_to#

convert_to(obj, to_type: str, as_scitype: Optional[str] = None, store=None, store_behaviour: Optional[str] = None)[source]#

Convert object to a different machine representation, subject to scitype.

Parameters
objobject to convert - any type, should comply with mtype spec for as_scitype
to_typestr - the type to convert “obj” to, a valid mtype string

or list of str, this specifies admissible types for conversion to

valid mtype strings, with explanation, are in datatypes.MTYPE_REGISTER

as_scitypestr, optional - name of scitype the object “obj” is considered as

pre-specifying the scitype reduces the number of checks done in type inference valid scitype strings, with explanation, are in datatypes.SCITYPE_REGISTER default = inferred from mtype of obj, which is in turn inferred internally

storereference of storage for lossy conversions, default=None (no store)

is updated by side effect if not None and store_behaviour=”reset” or “update”

store_behaviourstr, optional, one of None (default), “reset”, “freeze”, “update”

“reset” - store is emptied and then updated from conversion “freeze” - store is read-only, may be read/used by conversion but not changed “update” - store is updated from conversion and retains previous contents None - automatic: “update” if store is empty and not None; “freeze”, otherwise

Returns
converted_objto_type - object obj, or obj converted to target mtype as follows:
case 1: mtype of obj is equal to to_type, or a list element of to_type

no conversion happens, converted_obj = obj

case 2: to_type is a str, and not equal to mtype of obj

converted_obj is obj converted to to_type

case 3: to_type is list of str, and mtype of obj is not in that list
converted_obj is converted to the first mtype in to_type

that is of same scitype as obj

case 4: if obj was None, converted_obj is also None

Raises
TypeError if machine type of input “obj” is not recognized
TypeError if to_type contains no mtype compatible with mtype of obj
KeyError if conversion that would be conducted is not implemented
TypeError or ValueError if inputs do not match specification