fix(datatypes): document "!" as meaning non-nullable, enable nullable arg for type hints

ibis/expr/api.py

@@ -239,6 +239,7 @@ def schema(
     >>> from ibis import schema, Schema
     >>> sc = schema([("foo", "string"), ("bar", "int64"), ("baz", "boolean")])
     >>> sc = schema(names=["foo", "bar", "baz"], types=["string", "int64", "boolean"])
+    >>> sc = schema({"nullable-str": "string", "non-nullable-str": "!string"})
     >>> sc = schema(dict(foo="string"))
     >>> sc = schema(Schema(dict(foo="string")))  # no-op
 

ibis/expr/datatypes/core.py

@@ -44,19 +44,22 @@ def dtype(value: Any, nullable: bool = True) -> DataType:
         pyarrow types.
     nullable
         Whether the type should be nullable. Defaults to True.
+        If `value` is a string prefixed by "!", the type is always non-nullable.
 
     Examples
     --------
     >>> import ibis
     >>> ibis.dtype("int32")
     Int32(nullable=True)
+    >>> ibis.dtype("!int32")
+    Int32(nullable=False)
     >>> ibis.dtype("array<float>")
     Array(value_type=Float64(nullable=True), length=None, nullable=True)
 
     DataType objects may also be created from Python types:
 
-    >>> ibis.dtype(int)
-    Int64(nullable=True)
+    >>> ibis.dtype(int, nullable=False)
+    Int64(nullable=False)
     >>> ibis.dtype(list[float])
     Array(value_type=Float64(nullable=True), length=None, nullable=True)
 
@@ -70,7 +73,7 @@ def dtype(value: Any, nullable: bool = True) -> DataType:
     if isinstance(value, DataType):
         return value
     else:
-        return DataType.from_typehint(value)
+        return DataType.from_typehint(value, nullable)
 
 
 @dtype.register(str)

ibis/expr/datatypes/tests/test_core.py

@@ -53,6 +53,19 @@ def test_dtype(spec, expected):
     assert dt.dtype(spec) == expected
 
 
+@pytest.mark.parametrize(
+    ("args", "expected"),
+    [
+        ((int,), dt.Int64(nullable=True)),
+        ((int, False), dt.Int64(nullable=False)),
+        (("!int",), dt.Int64(nullable=False)),
+        (("!int", True), dt.Int64(nullable=False)),  # "!" overrides `nullable`
+    ],
+)
+def test_nullable_dtype(args, expected):
+    assert dt.dtype(*args) == expected
+
+
 @pytest.mark.parametrize(
     ("klass", "expected"),
     [