deploy: c1cc529

Author: github-actions[bot]

.nojekyll

@@ -0,0 +1,255 @@
+# Cast
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+``` python
+from __future__ import annotations
+from nbdev.showdoc import *
+from fastcore.test import *
+from fastcore.nb_imports import *
+```
+
+This module contains some of `fastcore.dispatch`’s utility functions for
+type casting. We copy them over here as with `fasttransform`’s release
+those modules may be removed from fastcore.
+
+The functions here have not been changed, except for
+[`retain_type`](https://AnswerDotAI.github.io/fasttransform/cast.html#retain_type),
+which has the same functionality but now accepts the type hints as Plum
+dispatch provides them instead of `fastcore.dispatch`’s convention.
+
+## Type casting
+
+Some objects may have a `set_meta` method, such as
+[`fastai.torch_core.Tensor`](https://docs.fast.ai/torch_core.html#tensor.set_meta).
+When casting these to another type we want to preserve metadata.
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/AnswerDotAI/fasttransform/blob/main/fasttransform/cast.py#L19"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### retain_meta
+
+>  retain_meta (x, res, as_copy=False)
+
+*Call `res.set_meta(x)`, if it exists*
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/AnswerDotAI/fasttransform/blob/main/fasttransform/cast.py#L26"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### default_set_meta
+
+>  default_set_meta (x, as_copy=False)
+
+*Copy over `_meta` from `x` to `res`, if it’s missing*
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/AnswerDotAI/fasttransform/blob/main/fasttransform/cast.py#L36"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### cast
+
+>  cast (x, typ)
+
+*cast `x` to type `typ` (may also change `x` inplace)*
+
+This works both for plain python classes…
+
+``` python
+mk_class('_T1', 'a')   # mk_class is a fastai utility that constructs a class.
+class _T2(_T1): pass
+
+t = _T1(a=1)
+t2 = cast(t, _T2)        
+assert t2 is t            # t2 refers to the same object as t
+assert isinstance(t, _T2) # t also changed in-place
+assert isinstance(t2, _T2)
+
+test_eq_type(_T2(a=1), t2)
+```
+
+…as well as for arrays and tensors.
+
+``` python
+class _T1(ndarray): pass
+
+t = array([1])
+t2 = cast(t, _T1)
+test_eq(array([1]), t2)
+test_eq(_T1, type(t2))
+```
+
+## Retain type
+
+Retain type is a function that’s useful for postprocessing function
+outputs. They are used in the
+[`Transform`](https://AnswerDotAI.github.io/fasttransform/transform.html#transform)
+class.
+
+The conversion priorities are as follows:
+
+1.  the function’s return type annotation `ret_type`
+2.  if there’s no return type annotation (i.e. `ret_type=Any`) then it
+    will convert back to the input’s (`old`) type, but only if if it was
+    a subtype of the return value.
+3.  if the function has return type annotation of None (`ret_type=None`)
+    then no conversion will be done.
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/AnswerDotAI/fasttransform/blob/main/fasttransform/cast.py#L47"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### retain_type
+
+>  retain_type (new, old, ret_type=typing.Any, as_copy=False)
+
+*Cast `new` to `ret_type` if given, or `old`’s type if `new` is a
+superclass of `old`. No conversion is done if `ret_type=None`*
+
+### Return type annotation conversion
+
+We try and convert new to the return type if it’s given.
+
+``` python
+class FS(float):
+    def __repr__(self): return f'FS({float(self)})'
+```
+
+``` python
+test_eq(retain_type(1., 2., FS), FS(1.))
+```
+
+Even if it won’t work, we’ll let the exception be raised:
+
+``` python
+# Raise error if return type is not compatible with new
+try: retain_type("a", 2., FS)
+except ValueError as e: print(f"Expected error: {e}")
+```
+
+    Expected error: could not convert string to float: 'a'
+
+### Old type conversion
+
+If the return type is `Any` then new looks at old for conversion
+guidance.
+
+``` python
+test_eq(retain_type(1., FS(2.), Any), FS(1.))
+```
+
+But if new isn’t subclass of old, keep new:
+
+``` python
+test_eq(retain_type(FS(1.), 2.0, Any), FS(1.))
+test_eq(retain_type("a", 2.0, Any), "a")
+```
+
+No casting needed if new is already of type old. Then we return the
+original object.
+
+``` python
+x = FS(1.)
+test_is(retain_type(x, FS(2.), Any), x)
+```
+
+### Edge cases with None
+
+We dont convert at all if None is return type annotation:
+
+``` python
+test_eq(retain_type(1., FS(2.), NoneType), 1.)
+```
+
+None stays None:
+
+``` python
+test_eq(retain_type(None,FS(2.), Any), None)
+```
+
+If old was None then we just return new.
+
+``` python
+test_eq(retain_type(FS(1.), None, Any), FS(1.))
+```
+
+### Metadata retention
+
+If old has a \_meta attribute, its content is passed when casting new to
+the type of old. In the below example, only the attribute a, but not
+other_attr is kept, because other_attr is not in \_meta:
+
+``` python
+class _A():
+    set_meta = default_set_meta
+    def __init__(self, t): self.t=t
+
+class _B1(_A):
+    def __init__(self, t, a=1):
+        super().__init__(t)
+        self._meta = {'a':a}
+        self.other_attr = 'Hello' # will not be kept after casting.
+        
+x = _B1(1, a=2)
+b = _A(1)
+c = retain_type(b, old=x)
+test_eq(c._meta, {'a': 2})
+assert not getattr(c, 'other_attr', None)
+```
+
+## Retain types
+
+Cast each item of `new` to type of matching item in `old` if it’s a
+superclass.
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/AnswerDotAI/fasttransform/blob/main/fasttransform/cast.py#L58"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### retain_types
+
+>  retain_types (new, old=None, typs=None)
+
+*Cast each item of `new` to type of matching item in `old` if it’s a
+superclass*
+
+``` python
+class T(tuple): pass
+
+t1,t2 = retain_types((1,(1,(1,1))), (2,T((2,T((3,4))))))
+test_eq_type(t1, 1)
+test_eq_type(t2, T((1,T((1,1)))))
+
+t1,t2 = retain_types((1,(1,(1,1))), typs = {tuple: [int, {T: [int, {T: [int,int]}]}]})
+test_eq_type(t1, 1)
+test_eq_type(t2, T((1,T((1,1)))))
+```
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/AnswerDotAI/fasttransform/blob/main/fasttransform/cast.py#L73"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### explode_types
+
+>  explode_types (o)
+
+*Return the type of `o`, potentially in nested dictionaries for thing
+that are listy*
+
+``` python
+test_eq(explode_types((2,T((2,T((3,4)))))), {tuple: [int, {T: [int, {T: [int,int]}]}]})
+```