From 0656a562142ce6a478210720fb8baa6ac71e2ddb Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Mon, 15 Aug 2011 14:27:19 +0300 Subject: [PATCH] #12204: document that str.upper().isupper() might be False and add a note about cased characters. --- Doc/library/stdtypes.rst | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 83c3bed5b9c..2a9f6405c93 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -54,7 +54,7 @@ following values are considered false: * instances of user-defined classes, if the class defines a :meth:`__bool__` or :meth:`__len__` method, when that method returns the integer zero or - :class:`bool` value ``False``. [#]_ + :class:`bool` value ``False``. [1]_ .. index:: single: true @@ -261,7 +261,7 @@ Python fully supports mixed arithmetic: when a binary arithmetic operator has operands of different numeric types, the operand with the "narrower" type is widened to that of the other, where integer is narrower than floating point, which is narrower than complex. Comparisons between numbers of mixed type use -the same rule. [#]_ The constructors :func:`int`, :func:`float`, and +the same rule. [2]_ The constructors :func:`int`, :func:`float`, and :func:`complex` can be used to produce numbers of a specific type. All numeric types (except complex) support the following operations, sorted by @@ -852,7 +852,7 @@ them is inefficient. Most sequence types support the following operations. The ``in`` and ``not in`` operations have the same priorities as the comparison operations. The ``+`` and ``*`` operations have the same priority as the corresponding numeric operations. -[#]_ Additional methods are provided for :ref:`typesseq-mutable`. +[3]_ Additional methods are provided for :ref:`typesseq-mutable`. This table lists the sequence operations sorted in ascending priority (operations in the same box have the same priority). In the table, *s* and *t* @@ -1137,10 +1137,8 @@ functions based on regular expressions. .. method:: str.islower() - Return true if all cased characters in the string are lowercase and there is at - least one cased character, false otherwise. Cased characters are those with - general category property being one of "Lu", "Ll", or "Lt" and lowercase characters - are those with general category property "Ll". + Return true if all cased characters [4]_ in the string are lowercase and + there is at least one cased character, false otherwise. .. method:: str.isnumeric() @@ -1180,10 +1178,8 @@ functions based on regular expressions. .. method:: str.isupper() - Return true if all cased characters in the string are uppercase and there is at - least one cased character, false otherwise. Cased characters are those with - general category property being one of "Lu", "Ll", or "Lt" and uppercase characters - are those with general category property "Lu". + Return true if all cased characters [4]_ in the string are uppercase and + there is at least one cased character, false otherwise. .. method:: str.join(iterable) @@ -1203,7 +1199,8 @@ functions based on regular expressions. .. method:: str.lower() - Return a copy of the string converted to lowercase. + Return a copy of the string with all the cased characters [4]_ converted to + lowercase. .. method:: str.lstrip([chars]) @@ -1404,7 +1401,10 @@ functions based on regular expressions. .. method:: str.upper() - Return a copy of the string converted to uppercase. + Return a copy of the string with all the cased characters [4]_ converted to + uppercase. Note that ``str.upper().isupper()`` might be ``False`` if ``s`` + contains uncased characters or if the Unicode category of the resulting + character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, titlecase). .. method:: str.zfill(width) @@ -1444,7 +1444,7 @@ specifications in *format* are replaced with zero or more elements of *values*. The effect is similar to the using :c:func:`sprintf` in the C language. If *format* requires a single argument, *values* may be a single non-tuple -object. [#]_ Otherwise, *values* must be a tuple with exactly the number of +object. [5]_ Otherwise, *values* must be a tuple with exactly the number of items specified by the format string, or a single mapping object (for example, a dictionary). @@ -2808,13 +2808,16 @@ The following attributes are only supported by :term:`new-style class`\ es. .. rubric:: Footnotes -.. [#] Additional information on these special methods may be found in the Python +.. [1] Additional information on these special methods may be found in the Python Reference Manual (:ref:`customization`). -.. [#] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and +.. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and similarly for tuples. -.. [#] They must have since the parser can't tell the type of the operands. +.. [3] They must have since the parser can't tell the type of the operands. -.. [#] To format only a tuple you should therefore provide a singleton tuple whose only +.. [4] Cased characters are those with general category property being one of + "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase). + +.. [5] To format only a tuple you should therefore provide a singleton tuple whose only element is the tuple to be formatted.