gh-102431: clarify constraints on arguments of logical_xxx methods

Lib/_pydecimal.py

@@ -3317,7 +3317,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()
 
@@ -3334,14 +3338,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()
 
@@ -3358,7 +3369,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()
 
@@ -4681,7 +4696,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')
@@ -4708,7 +4724,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')
@@ -4727,7 +4744,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')
@@ -4754,7 +4772,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')

Misc/NEWS.d/next/Library/2023-03-21-10-59-40.gh-issue-102431.eUDnf4.rst

@@ -0,0 +1,2 @@
+Clarify constraints for "logical" arguments in methods of
+:class:`decimal.Context`.

Modules/_decimal/docstrings.h

@@ -295,22 +295,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,
@@ -715,23 +719,91 @@ 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\
-\n");
+Applies the logical operation \'and\' between each operand\'s digits.\n\n\
+Both operands should have zero sign and exponent, and\n\
+digits either 0 or 1.\n\n\
+>>> ExtendedContext.logical_and(Decimal(\'0\'), Decimal(\'0\'))\n\
+Decimal(\'0\')\n\
+>>> ExtendedContext.logical_and(Decimal(\'0\'), Decimal(\'1\'))\n\
+Decimal(\'0\')\n\
+>>> ExtendedContext.logical_and(Decimal(\'1\'), Decimal(\'0\'))\n\
+Decimal(\'0\')\n\
+>>> ExtendedContext.logical_and(Decimal(\'1\'), Decimal(\'1\'))\n\
+Decimal(\'1\')\n\
+>>> ExtendedContext.logical_and(Decimal(\'1100\'), Decimal(\'1010\'))\n\
+Decimal(\'1000\')\n\
+>>> ExtendedContext.logical_and(Decimal(\'1111\'), Decimal(\'10\'))\n\
+Decimal(\'10\')\n\
+>>> ExtendedContext.logical_and(110, 1101)\n\
+Decimal(\'100\')\n\
+>>> ExtendedContext.logical_and(Decimal(110), 1101)\n\
+Decimal(\'100\')\n\
+>>> ExtendedContext.logical_and(110, Decimal(1101))\n\
+Decimal(\'100\')\n");
 
 PyDoc_STRVAR(doc_ctx_logical_invert,
 "logical_invert($self, x, /)\n--\n\n\
-Invert all digits of x.\n\
-\n");
+Invert all the digits in the operand.\n\n\
+The operand should have zero sign and exponent, and digits\n\
+either 0 or 1.\n\n\
+>>> ExtendedContext.logical_invert(Decimal(\'0\'))\n\
+Decimal(\'111111111\')\n\
+>>> ExtendedContext.logical_invert(Decimal(\'1\'))\n\
+Decimal(\'111111110\')\n\
+>>> ExtendedContext.logical_invert(Decimal(\'111111111\'))\n\
+Decimal(\'0\')\n\
+>>> ExtendedContext.logical_invert(Decimal(\'101010101\'))\n\
+Decimal(\'10101010\')\n\
+>>> ExtendedContext.logical_invert(1101)\n\
+Decimal(\'111110010\')\n");
 
 PyDoc_STRVAR(doc_ctx_logical_or,
 "logical_or($self, x, y, /)\n--\n\n\
-Digit-wise or of x and y.\n\
-\n");
+Applies the logical operation \'or\' between each operand\'s digits.\n\n\
+Both operands should have zero sign and exponent, and digits\n\
+either 0 or 1.\n\n\
+>>> ExtendedContext.logical_or(Decimal(\'0\'), Decimal(\'0\'))\n\
+Decimal(\'0\')\n\
+>>> ExtendedContext.logical_or(Decimal(\'0\'), Decimal(\'1\'))\n\
+Decimal(\'1\')\n\
+>>> ExtendedContext.logical_or(Decimal(\'1\'), Decimal(\'0\'))\n\
+Decimal(\'1\')\n\
+>>> ExtendedContext.logical_or(Decimal(\'1\'), Decimal(\'1\'))\n\
+Decimal(\'1\')\n\
+>>> ExtendedContext.logical_or(Decimal(\'1100\'), Decimal(\'1010\'))\n\
+Decimal(\'1110\')\n\
+>>> ExtendedContext.logical_or(Decimal(\'1110\'), Decimal(\'10\'))\n\
+Decimal(\'1110\')\n\
+>>> ExtendedContext.logical_or(110, 1101)\n\
+Decimal(\'1111\')\n\
+>>> ExtendedContext.logical_or(Decimal(110), 1101)\n\
+Decimal(\'1111\')\n\
+>>> ExtendedContext.logical_or(110, Decimal(1101))\n\
+Decimal(\'1111\')\n");
 
 PyDoc_STRVAR(doc_ctx_logical_xor,
 "logical_xor($self, x, y, /)\n--\n\n\
-Digit-wise xor of x and y.\n\
-\n");
+Applies the logical operation \'xor\' between each operand\'s digits.\n\n\
+Both operands should have zero sign and exponent, and digits\n\
+either 0 or 1.\n\n\
+>>> ExtendedContext.logical_xor(Decimal(\'0\'), Decimal(\'0\'))\n\
+Decimal(\'0\')\n\
+>>> ExtendedContext.logical_xor(Decimal(\'0\'), Decimal(\'1\'))\n\
+Decimal(\'1\')\n\
+>>> ExtendedContext.logical_xor(Decimal(\'1\'), Decimal(\'0\'))\n\
+Decimal(\'1\')\n\
+>>> ExtendedContext.logical_xor(Decimal(\'1\'), Decimal(\'1\'))\n\
+Decimal(\'0\')\n\
+>>> ExtendedContext.logical_xor(Decimal(\'1100\'), Decimal(\'1010\'))\n\
+Decimal(\'110\')\n\
+>>> ExtendedContext.logical_xor(Decimal(\'1111\'), Decimal(\'10\'))\n\
+Decimal(\'1101\')\n\
+>>> ExtendedContext.logical_xor(110, 1101)\n\
+Decimal(\'1011\')\n\
+>>> ExtendedContext.logical_xor(Decimal(110), 1101)\n\
+Decimal(\'1011\')\n\
+>>> ExtendedContext.logical_xor(110, Decimal(1101))\n\
+Decimal(\'1011\')\n");
 
 PyDoc_STRVAR(doc_ctx_max,
 "max($self, x, y, /)\n--\n\n\