ENH: Implement Kleene logic for BooleanArray

asv_bench/benchmarks/boolean.py

@@ -0,0 +1,32 @@
+import numpy as np
+
+import pandas as pd
+
+
+class TimeLogicalOps:
+ def setup(self):
+ N = 10_000
+ left, right, lmask, rmask = np.random.randint(0, 2, size=(4, N)).astype("bool")
+ self.left = pd.arrays.BooleanArray(left, lmask)
+ self.right = pd.arrays.BooleanArray(right, rmask)
+
+ def time_or_scalar(self):
+ self.left | True
+ self.left | False
+
+ def time_or_array(self):
+ self.left | self.right
+
+ def time_and_scalar(self):
+ self.left & True
+ self.left & False
+
+ def time_and_array(self):
+ self.left & self.right
+
+ def time_xor_scalar(self):
+ self.left ^ True
+ self.left ^ False
+
+ def time_xor_array(self):
+ self.left ^ self.right

doc/source/index.rst.template

@@ -73,6 +73,7 @@ See the :ref:`overview` for more detail about what's in the library.
  * :doc:`user_guide/missing_data`
  * :doc:`user_guide/categorical`
  * :doc:`user_guide/integer_na`
+ * :doc:`user_guide/boolean`
  * :doc:`user_guide/visualization`
  * :doc:`user_guide/computation`
  * :doc:`user_guide/groupby`

doc/source/user_guide/boolean.rst

@@ -0,0 +1,79 @@
+.. currentmodule:: pandas
+
+.. ipython:: python
+ :suppress:
+
+ import pandas as pd
+ import numpy as np
+
+.. _boolean:
+
+**************************
+Nullable Boolean Data Type
+**************************
+
+.. versionadded:: 1.0.0
+
+.. _boolean.kleene:
+
+Kleene Logical Operations
+-------------------------
+
+:class:`arrays.BooleanArray` implements `Kleene Logic`_ (sometimes called three-value logic) for
+logical operations like ``&`` (and), ``|`` (or) and ``^`` (exclusive-or).
+
+This table demonstrates the results for every combination. These operations are symmetrical,
+so flipping the left- and right-hand side makes no difference in the result.
+
+================= =========
+Expression Result
+================= =========
+``True & True`` ``True``
+``True & False`` ``False``
+``True & NA`` ``NA``
+``False & False`` ``False``
+``False & NA`` ``False``
+``NA & NA`` ``NA``
+``True | True`` ``True``
+``True | False`` ``True``
+``True | NA`` ``True``
+``False | False`` ``False``
+``False | NA`` ``NA``
+``NA | NA`` ``NA``
+``True ^ True`` ``False``
+``True ^ False`` ``True``
+``True ^ NA`` ``NA``
+``False ^ False`` ``False``
+``False ^ NA`` ``NA``
+``NA ^ NA`` ``NA``
+================= =========
+
+When an ``NA`` is present in an operation, the output value is ``NA`` only if
+the result cannot be determined solely based on the other input. For example,
+``True | NA`` is ``True``, because both ``True | True`` and ``True | False``
+are ``True``. In that case, we don't actually need to consider the value
+of the ``NA``.
+
+On the other hand, ``True & NA`` is ``NA``. The result depends on whether
+the ``NA`` really is ``True`` or ``False``, since ``True & True`` is ``True``,
+but ``True & False`` is ``False``, so we can't determine the output.
+
+
+This differs from how ``np.nan`` behaves in logical operations. Pandas treated
+``np.nan`` is *always false in the output*.
+
+In ``or``
+
+.. ipython:: python
+
+ pd.Series([True, False, np.nan], dtype="object") | True
+ pd.Series([True, False, np.nan], dtype="boolean") | True
+
+In ``and``
+
+.. ipython:: python
+
+ pd.Series([True, False, np.nan], dtype="object") & True
+ pd.Series([True, False, np.nan], dtype="boolean") & True
+
+.. _Kleene Logic: https://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics

doc/source/user_guide/index.rst

@@ -30,6 +30,7 @@ Further information on any specific method can be obtained in the
  missing_data
  categorical
  integer_na
+ boolean
  visualization
  computation
  groupby

pandas/core/arrays/boolean.py

@@ -184,6 +184,9 @@ class BooleanArray(ExtensionArray, ExtensionOpsMixin):
  represented by 2 numpy arrays: a boolean array with the data and
  a boolean array with the mask (True indicating missing).
 
+ BooleanArray implements Kleene logic (sometimes called three-value
+ logic) for logical operations. See :ref:`boolean.kleene` for more.
+
  To construct an BooleanArray from generic array-like input, use
  :func:`pandas.array` specifying ``dtype="boolean"`` (see examples
  below).
@@ -283,7 +286,7 @@ def __getitem__(self, item):
 
  def _coerce_to_ndarray(self, dtype=None, na_value: "Scalar" = libmissing.NA):
  """
- Coerce to an ndarary of object dtype or bool dtype (if force_bool=True).
+ Coerce to an ndarray of object dtype or bool dtype (if force_bool=True).
 
  Parameters
  ----------
@@ -565,33 +568,40 @@ def logical_method(self, other):
  # Rely on pandas to unbox and dispatch to us.
  return NotImplemented
 
+ assert op.__name__ in {"or_", "ror_", "and_", "rand_", "xor", "rxor"}
  other = lib.item_from_zerodim(other)
+ other_is_booleanarray = isinstance(other, BooleanArray)
+ other_is_scalar = lib.is_scalar(other)
  mask = None
 
- if isinstance(other, BooleanArray):
+ if other_is_booleanarray:
  other, mask = other._data, other._mask
  elif is_list_like(other):
  other = np.asarray(other, dtype="bool")
  if other.ndim > 1:
  raise NotImplementedError(
  "can only perform ops with 1-d structures"
  )
- if len(self) != len(other):
- raise ValueError("Lengths must match to compare")
  other, mask = coerce_to_array(other, copy=False)
+ elif isinstance(other, np.bool_):
+ other = other.item()
+
+ if other_is_scalar and not (other is libmissing.NA or lib.is_bool(other)):
+ raise TypeError(
+ "'other' should be pandas.NA or a bool. Got {} instead.".format(
+ type(other).__name__
+ )
+ )
 
- # numpy will show a DeprecationWarning on invalid elementwise
- # comparisons, this will raise in the future
- with warnings.catch_warnings():
- warnings.filterwarnings("ignore", "elementwise", FutureWarning)
- with np.errstate(all="ignore"):
- result = op(self._data, other)
+ if not other_is_scalar and len(self) != len(other):
+ raise ValueError("Lengths must match to compare")
 
- # nans propagate
- if mask is None:
- mask = self._mask
- else:
- mask = self._mask | mask
+ if op.__name__ in {"or_", "ror_"}:
+ result, mask = ops.kleene_or(self._data, other, self._mask, mask)
+ elif op.__name__ in {"and_", "rand_"}:
+ result, mask = ops.kleene_and(self._data, other, self._mask, mask)
+ elif op.__name__ in {"xor", "rxor"}:
+ result, mask = ops.kleene_xor(self._data, other, self._mask, mask)
 
  return BooleanArray(result, mask)
 

pandas/core/ops/__init__.py

@@ -39,6 +39,7 @@
  _op_descriptions,
 )
 from pandas.core.ops.invalid import invalid_comparison # noqa:F401
+from pandas.core.ops.mask_ops import kleene_and, kleene_or, kleene_xor # noqa: F401
 from pandas.core.ops.methods import ( # noqa:F401
  add_flex_arithmetic_methods,
  add_special_arithmetic_methods,

pandas/core/ops/dispatch.py

@@ -189,6 +189,9 @@ def maybe_dispatch_ufunc_to_dunder_op(
  "ge",
  "remainder",
  "matmul",
+ "or",
+ "xor",
+ "and",
  }
  aliases = {
  "subtract": "sub",
@@ -204,6 +207,9 @@ def maybe_dispatch_ufunc_to_dunder_op(
  "less_equal": "le",
  "greater": "gt",
  "greater_equal": "ge",
+ "bitwise_or": "or",
+ "bitwise_and": "and",
+ "bitwise_xor": "xor",
  }
 
  # For op(., Array) -> Array.__r{op}__