feat(api): add ibis.dtype top-level API

ibis-project · Aug 2, 2023 · 867e5f1 · 867e5f1
1 parent 39b7a24
commit 867e5f1
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 0 deletions.
diff --git a/docs/reference/expressions/top_level.md b/docs/reference/expressions/top_level.md
@@ -13,6 +13,7 @@ These methods and objects are available directly in the `ibis` module.
 ::: ibis.deferred
 ::: ibis.desc
 ::: ibis.difference
+::: ibis.dtype
 ::: ibis.get_backend
 ::: ibis.expr.types.Value.greatest
 ::: ibis.ifelse

diff --git a/ibis/expr/api.py b/ibis/expr/api.py
@@ -59,6 +59,7 @@
     'decompile',
     'deferred',
     'difference',
+    'dtype',
     'e',
     'Expr',
     'geo_area',
@@ -163,6 +164,7 @@
 )
 
 
+dtype = dt.dtype
 infer_dtype = dt.infer
 infer_schema = sch.infer
 

diff --git a/ibis/expr/datatypes/core.py b/ibis/expr/datatypes/core.py
@@ -41,6 +41,19 @@ def dtype(value: Any, nullable: bool = True) -> DataType:
     Int32(nullable=True)
     >>> ibis.dtype("array<float>")
     Array(value_type=Float64(nullable=True), nullable=True)
+
+    DataType objects may also be created from Python types:
+
+    >>> ibis.dtype(int)
+    Int64(nullable=True)
+    >>> ibis.dtype(list[float])
+    Array(value_type=Float64(nullable=True), nullable=True)
+
+    Or other type systems, like numpy/pandas/pyarrow types:
+
+    >>> import pyarrow as pa
+    >>> ibis.dtype(pa.int32())
+    Int32(nullable=True)
     """
     if isinstance(value, DataType):
         return value