ENH: add NA scalar for missing value indicator, use in StringArray.

pandas/__init__.py

@@ -68,6 +68,7 @@
     DatetimeTZDtype,
     StringDtype,
     # missing
+    NA,
     isna,
     isnull,
     notna,

pandas/core/api.py

@@ -45,6 +45,7 @@
 from pandas.core.indexes.period import Period, period_range
 from pandas.core.indexes.timedeltas import Timedelta, timedelta_range
 from pandas.core.indexing import IndexSlice
+from pandas.core.na_scalar import NA
 from pandas.core.reshape.reshape import get_dummies
 from pandas.core.series import Series
 from pandas.core.tools.datetimes import to_datetime

pandas/core/na_scalar.py

@@ -0,0 +1,112 @@
+import numbers
+
+
+def _create_binary_propagating_op(name):
+    def method(self, other):
+        if isinstance(other, numbers.Number) or other is NA or isinstance(other, str):
+            return NA
+
+        return NotImplemented
+
+    method.__name__ = name
+    return method
+
+
+def _create_unary_propagating_op(name):
+    def method(self):
+        return NA
+
+    method.__name__ = name
+    return method
+
+
+class NAType:
+
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if NAType._instance is None:
+            NAType._instance = object.__new__(cls, *args, **kwargs)
+        return NAType._instance
+
+    def __repr__(self) -> str:
+        return "NA"
+
+    def __str__(self) -> str:
+        return "NA"
+
+    def __bool__(self):
+        raise TypeError("boolean value of NA is ambiguous")
+
+    def __hash__(self):
+        return id(self)
+
+    # Binary arithmetic and comparison ops -> propagate
+
+    __add__ = _create_binary_propagating_op("__add__")
+    __radd__ = _create_binary_propagating_op("__radd__")
+    __sub__ = _create_binary_propagating_op("__sub__")
+    __rsub__ = _create_binary_propagating_op("__rsub__")
+    __mul__ = _create_binary_propagating_op("__mul__")
+    __rmul__ = _create_binary_propagating_op("__rmul__")
+    __matmul__ = _create_binary_propagating_op("__matmul__")
+    __rmatmul__ = _create_binary_propagating_op("__rmatmul__")
+    __truediv__ = _create_binary_propagating_op("__truediv__")
+    __rtruediv__ = _create_binary_propagating_op("__rtruediv__")
+    __floordiv__ = _create_binary_propagating_op("__floordiv__")
+    __rfloordiv__ = _create_binary_propagating_op("__rfloordiv__")
+    __mod__ = _create_binary_propagating_op("__mod__")
+    __rmod__ = _create_binary_propagating_op("__rmod__")
+    __divmod__ = _create_binary_propagating_op("__divmod__")
+    __rdivmod__ = _create_binary_propagating_op("__rdivmod__")
+    __pow__ = _create_binary_propagating_op("__pow__")
+    __rpow__ = _create_binary_propagating_op("__rpow__")
+
+    # __lshift__ = _create_binary_propagating_op("__add__")
+    # __rshift__ = _create_binary_propagating_op("__add__")
+
+    __eq__ = _create_binary_propagating_op("__eq__")
+    __ne__ = _create_binary_propagating_op("__ne__")
+    __le__ = _create_binary_propagating_op("__le__")
+    __lt__ = _create_binary_propagating_op("__lt__")
+    __gt__ = _create_binary_propagating_op("__gt__")
+    __ge__ = _create_binary_propagating_op("__ge__")
+
+    # Unary ops
+
+    __neg__ = _create_unary_propagating_op("__neg__")
+    __pos__ = _create_unary_propagating_op("__pos__")
+    __abs__ = _create_unary_propagating_op("__abs__")
+    __invert__ = _create_unary_propagating_op("__invert__")
+
+    # Logical ops using Kleene logic
+
+    def __and__(self, other):
+        if other is False:
+            return False
+        elif other is True or other is NA:
+            return NA
+        else:
+            return NotImplemented
+
+    __rand__ = __and__
+
+    def __or__(self, other):
+        if other is True:
+            return True
+        elif other is False or other is NA:
+            return NA
+        else:
+            return NotImplemented
+
+    __ror__ = __or__
+
+    def __xor__(self, other):
+        if other is False or other is True or other is NA:
+            return NA
+        return NotImplemented
+
+    __rxor__ = __xor__
+
+
+NA = NAType()

pandas/tests/scalar/test_na_scalar.py

@@ -0,0 +1,108 @@
+import numpy as np
+import pytest
+
+from pandas.core.na_scalar import NA
+
+
+def test_singleton():
+    assert NA is NA
+    new_NA = type(NA)()
+    assert new_NA is NA
+
+
+def test_repr():
+    assert repr(NA) == "NA"
+    assert str(NA) == "NA"
+
+
+def test_truthiness():
+    with pytest.raises(TypeError):
+        bool(NA)
+
+    with pytest.raises(TypeError):
+        not NA
+
+
+def test_hashable():
+    assert hash(NA) == hash(NA)
+    d = {NA: "test"}
+    assert d[NA] == "test"
+
+
+def test_arithmetic_ops(all_arithmetic_functions):
+    op = all_arithmetic_functions
+
+    for other in [NA, 1, 1.0, "a", np.int64(1), np.nan]:
+        if op.__name__ == "rmod" and isinstance(other, str):
+            continue
+        assert op(NA, other) is NA
+
+
+def test_comparison_ops():
+
+    for other in [NA, 1, 1.0, "a", np.int64(1), np.nan]:
+        assert (NA == other) is NA
+        assert (NA != other) is NA
+        assert (NA > other) is NA
+        assert (NA >= other) is NA
+        assert (NA < other) is NA
+        assert (NA <= other) is NA
+
+        if isinstance(other, np.int64):
+            # for numpy scalars we get a deprecation warning and False as result
+            # for equality or error for larger/lesser than
+            continue
+
+        assert (other == NA) is NA
+        assert (other != NA) is NA
+        assert (other > NA) is NA
+        assert (other >= NA) is NA
+        assert (other < NA) is NA
+        assert (other <= NA) is NA
+
+
+def test_unary_ops():
+    assert +NA is NA
+    assert -NA is NA
+    assert abs(NA) is NA
+    assert ~NA is NA
+
+
+def test_logical_and():
+
+    assert NA & True is NA
+    assert True & NA is NA
+    assert NA & False is False
+    assert False & NA is False
+    assert NA & NA is NA
+
+    with pytest.raises(TypeError):
+        NA & 5
+
+
+def test_logical_or():
+
+    assert NA | True is True
+    assert True | NA is True
+    assert NA | False is NA
+    assert False | NA is NA
+    assert NA | NA is NA
+
+    with pytest.raises(TypeError):
+        NA | 5
+
+
+def test_logical_xor():
+
+    assert NA ^ True is NA
+    assert True ^ NA is NA
+    assert NA ^ False is NA
+    assert False ^ NA is NA
+    assert NA ^ NA is NA
+
+    with pytest.raises(TypeError):
+        NA ^ 5
+
+
+def test_logical_not():
+    assert ~NA is NA