gh-102431: clarify constraints on arguments of logical_xxx methods

Author: skirpichev

Lib/_pydecimal.py

@@ -3388,7 +3388,11 @@ def _fill_logical(self, context, opa, opb):
         return opa, opb
 
     def logical_and(self, other, context=None):
-        """Applies an 'and' operation between self and other's digits."""
+        """Applies an 'and' operation between self and other's digits.
+
+        Both self and other should have zero sign and exponent,
+        and digits either 0 or 1.
+        """
         if context is None:
             context = getcontext()
 
@@ -3405,14 +3409,21 @@ def logical_and(self, other, context=None):
         return _dec_from_triple(0, result.lstrip('0') or '0', 0)
 
     def logical_invert(self, context=None):
-        """Invert all its digits."""
+        """Invert all its digits.
+
+        The self should have zero sign and exponent, and digits either 0 or 1.
+        """
         if context is None:
             context = getcontext()
         return self.logical_xor(_dec_from_triple(0,'1'*context.prec,0),
                                 context)
 
     def logical_or(self, other, context=None):
-        """Applies an 'or' operation between self and other's digits."""
+        """Applies an 'or' operation between self and other's digits.
+
+        Both self and other should have zero sign and exponent,
+        and digits either 0 or 1.
+        """
         if context is None:
             context = getcontext()
 
@@ -3429,7 +3440,11 @@ def logical_or(self, other, context=None):
         return _dec_from_triple(0, result.lstrip('0') or '0', 0)
 
     def logical_xor(self, other, context=None):
-        """Applies an 'xor' operation between self and other's digits."""
+        """Applies an 'xor' operation between self and other's digits.
+
+        Both self and other should have zero sign and exponent,
+        and digits either 0 or 1.
+        """
         if context is None:
             context = getcontext()
 
@@ -4752,7 +4767,8 @@ def logb(self, a):
     def logical_and(self, a, b):
         """Applies the logical operation 'and' between each operand's digits.
 
-        The operands must be both logical numbers.
+        Both operands should have zero sign and exponent, and
+        digits either 0 or 1.
 
         >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
         Decimal('0')
@@ -4779,7 +4795,8 @@ def logical_and(self, a, b):
     def logical_invert(self, a):
         """Invert all the digits in the operand.
 
-        The operand must be a logical number.
+        The operand should have zero sign and exponent, and digits
+        either 0 or 1.
 
         >>> ExtendedContext.logical_invert(Decimal('0'))
         Decimal('111111111')
@@ -4798,7 +4815,8 @@ def logical_invert(self, a):
     def logical_or(self, a, b):
         """Applies the logical operation 'or' between each operand's digits.
 
-        The operands must be both logical numbers.
+        Both operands should have zero sign and exponent, and digits
+        either 0 or 1.
 
         >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
         Decimal('0')
@@ -4825,7 +4843,8 @@ def logical_or(self, a, b):
     def logical_xor(self, a, b):
         """Applies the logical operation 'xor' between each operand's digits.
 
-        The operands must be both logical numbers.
+        Both operands should have zero sign and exponent, and digits
+        either 0 or 1.
 
         >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
         Decimal('0')

Modules/_decimal/docstrings.h

@@ -282,22 +282,26 @@ an infinity then Decimal('Infinity') is returned.\n\
 
 PyDoc_STRVAR(doc_logical_and,
 "logical_and($self, /, other, context=None)\n--\n\n\
-Return the digit-wise 'and' of the two (logical) operands.\n\
+Return the digit-wise 'and' of the two (logical) operands,\n\
+which both have zero sign and exponent, and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_logical_invert,
 "logical_invert($self, /, context=None)\n--\n\n\
-Return the digit-wise inversion of the (logical) operand.\n\
+Return the digit-wise inversion of the (logical) operand,\n\
+which has zero sign and exponent, and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_logical_or,
 "logical_or($self, /, other, context=None)\n--\n\n\
-Return the digit-wise 'or' of the two (logical) operands.\n\
+Return the digit-wise 'or' of the two (logical) operands,\n\
+which both have zero sign and exponent, and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_logical_xor,
 "logical_xor($self, /, other, context=None)\n--\n\n\
-Return the digit-wise 'exclusive or' of the two (logical) operands.\n\
+Return the digit-wise 'exclusive or' of the two (logical) operands,\n\
+which both have zero sign and exponent, and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_max,
@@ -702,22 +706,26 @@ Return the exponent of the magnitude of the operand's MSD.\n\
 
 PyDoc_STRVAR(doc_ctx_logical_and,
 "logical_and($self, x, y, /)\n--\n\n\
-Digit-wise and of x and y.\n\
+Digit-wise and of x and y, which both have zero sign\n\
+and exponent, and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_ctx_logical_invert,
 "logical_invert($self, x, /)\n--\n\n\
-Invert all digits of x.\n\
+Invert all digits of x, which has zero sign and exponent,\n\
+and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_ctx_logical_or,
 "logical_or($self, x, y, /)\n--\n\n\
-Digit-wise or of x and y.\n\
+Digit-wise or of x and y, which both have zero sign\n\
+and exponent, and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_ctx_logical_xor,
 "logical_xor($self, x, y, /)\n--\n\n\
-Digit-wise xor of x and y.\n\
+Digit-wise xor of x and y, which both have zero sign\n\
+and exponent, and digits either 0 or 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_ctx_max,