https://github.com/python/cpython/commit/4f826214b30ad50365f45bf07e4a02f34f8... commit: 4f826214b30ad50365f45bf07e4a02f34f897ab5 branch: main author: Furkan Onder <furkanonder@protonmail.com> committer: willingc <carolcode@willingconsulting.com> date: 2024-10-30T11:20:02-07:00 summary: gh-60712: Include the "object" type in the lists of documented types (GH-103036) * add test for the predefined object's attributes * Include the "object" type in the lists of documented types * remove 'or' from augment tuple * 📜🤖 Added by blurb_it. * Add cross-reference to news Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> * Fix format for the function parameter Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> * Add space Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> * add reference for the 'object' Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> * add reference for NotImplemented Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> * Change ref:`string <textseq>` as class:`str` Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> * remove hyphen from `newly-created` * Update Doc/reference/datamodel.rst 'dictionaries' to 'dict' Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> * Update predefined attribute types in testPredefinedAttrs * Change `universal type` as `top type` * Don't mention about the top type * Update the description of richcmpfuncs * Update Doc/library/stdtypes.rst Co-authored-by: Éric <merwok@netwok.org> * Revert: Hierarchy Section in Data Model Documentation * Revert to original explanations of __new__ and __init__ methods in datamodel.rst for improved clarity. * Update Doc/reference/datamodel.rst Co-authored-by: Éric <merwok@netwok.org> * Remove blank line Co-authored-by: Éric <merwok@netwok.org> * Use ref:`str <textseq>` instead of :class:`str Co-authored-by: Éric <merwok@netwok.org> * Revert changes the description of Other Built-in Types in stdtypes.rst * Update Doc/reference/datamodel.rst Co-authored-by: Éric <merwok@netwok.org> --------- Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Carol Willing <carolcode@willingconsulting.com> files: A Misc/NEWS.d/next/Documentation/2023-03-28-22-24-45.gh-issue-60712.So5uad.rst M Doc/library/functions.rst M Doc/reference/datamodel.rst M Lib/test/test_class.py diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 5c0efd21318f2c..03fc41fa793977 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1293,9 +1293,10 @@ are always available. They are listed here in alphabetical order. .. class:: object() - Return a new featureless object. :class:`object` is a base for all classes. - It has methods that are common to all instances of Python classes. This - function does not accept any arguments. + This is the ultimate base class of all other classes. It has methods + that are common to all instances of Python classes. When the constructor + is called, it returns a new featureless object. The constructor does not + accept any arguments. .. note:: diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index aceb95f2758e38..dfd1addf656a85 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2033,7 +2033,8 @@ Basic customization "informal" string representation of instances of that class is required. This is typically used for debugging, so it is important that the representation - is information-rich and unambiguous. + is information-rich and unambiguous. A default implementation is provided by the + :class:`object` class itself. .. index:: single: string; __str__() (object method) @@ -2043,10 +2044,10 @@ Basic customization .. method:: object.__str__(self) - Called by :func:`str(object) <str>` and the built-in functions - :func:`format` and :func:`print` to compute the "informal" or nicely + Called by :func:`str(object) <str>`, the default :meth:`__format__` implementation, + and the built-in function :func:`print`, to compute the "informal" or nicely printable string representation of an object. The return value must be a - :ref:`string <textseq>` object. + :ref:`str <textseq>` object. This method differs from :meth:`object.__repr__` in that there is no expectation that :meth:`__str__` return a valid Python expression: a more @@ -2063,7 +2064,8 @@ Basic customization .. index:: pair: built-in function; bytes Called by :ref:`bytes <func-bytes>` to compute a byte-string representation - of an object. This should return a :class:`bytes` object. + of an object. This should return a :class:`bytes` object. The :class:`object` + class itself does not provide this method. .. index:: single: string; __format__() (object method) @@ -2087,6 +2089,9 @@ Basic customization The return value must be a string object. + The default implementation by the :class:`object` class should be given + an empty *format_spec* string. It delegates to :meth:`__str__`. + .. versionchanged:: 3.4 The __format__ method of ``object`` itself raises a :exc:`TypeError` if passed any non-empty string. @@ -2129,6 +2134,12 @@ Basic customization ``(x<y or x==y)`` does not imply ``x<=y``. To automatically generate ordering operations from a single root operation, see :func:`functools.total_ordering`. + By default, the :class:`object` class provides implementations consistent + with :ref:`expressions-value-comparisons`: equality compares according to + object identity, and order comparisons raise :exc:`TypeError`. Each default + method may generate these results directly, but may also return + :data:`NotImplemented`. + See the paragraph on :meth:`__hash__` for some important notes on creating :term:`hashable` objects which support custom comparison operations and are usable as dictionary keys. @@ -2184,9 +2195,9 @@ Basic customization bucket). User-defined classes have :meth:`__eq__` and :meth:`__hash__` methods - by default; with them, all objects compare unequal (except with themselves) - and ``x.__hash__()`` returns an appropriate value such that ``x == y`` - implies both that ``x is y`` and ``hash(x) == hash(y)``. + by default (inherited from the :class:`object` class); with them, all objects compare + unequal (except with themselves) and ``x.__hash__()`` returns an appropriate + value such that ``x == y`` implies both that ``x is y`` and ``hash(x) == hash(y)``. A class that overrides :meth:`__eq__` and does not define :meth:`__hash__` will have its :meth:`__hash__` implicitly set to ``None``. When the @@ -2236,8 +2247,8 @@ Basic customization ``bool()``; should return ``False`` or ``True``. When this method is not defined, :meth:`~object.__len__` is called, if it is defined, and the object is considered true if its result is nonzero. If a class defines neither - :meth:`!__len__` nor :meth:`!__bool__`, all its instances are considered - true. + :meth:`!__len__` nor :meth:`!__bool__` (which is true of the :class:`object` + class itself), all its instances are considered true. .. _attribute-access: @@ -2259,6 +2270,7 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances. for ``self``; or :meth:`__get__` of a *name* property raises :exc:`AttributeError`). This method should either return the (computed) attribute value or raise an :exc:`AttributeError` exception. + The :class:`object` class itself does not provide this method. Note that if the attribute is found through the normal mechanism, :meth:`__getattr__` is not called. (This is an intentional asymmetry between @@ -2397,8 +2409,8 @@ method (a so-called *descriptor* class) appears in an *owner* class (the descriptor must be in either the owner's class dictionary or in the class dictionary for one of its parents). In the examples below, "the attribute" refers to the attribute whose name is the key of the property in the owner -class' :attr:`~object.__dict__`. - +class' :attr:`~object.__dict__`. The :class:`object` class itself does not +implement any of these protocols. .. method:: object.__get__(self, instance, owner=None) @@ -3090,6 +3102,7 @@ Emulating callable objects Called when the instance is "called" as a function; if this method is defined, ``x(arg1, arg2, ...)`` roughly translates to ``type(x).__call__(x, arg1, ...)``. + The :class:`object` class itself does not provide this method. .. _sequence-types: @@ -3097,10 +3110,11 @@ Emulating callable objects Emulating container types ------------------------- -The following methods can be defined to implement container objects. Containers -usually are :term:`sequences <sequence>` (such as :class:`lists <list>` or +The following methods can be defined to implement container objects. None of them +are provided by the :class:`object` class itself. Containers usually are +:term:`sequences <sequence>` (such as :class:`lists <list>` or :class:`tuples <tuple>`) or :term:`mappings <mapping>` (like -:class:`dictionaries <dict>`), +:term:`dictionaries <dictionary>`), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers *k* for which ``0 <= k < @@ -3460,6 +3474,7 @@ Typical uses of context managers include saving and restoring various kinds of global state, locking and unlocking resources, closing opened files, etc. For more information on context managers, see :ref:`typecontextmanager`. +The :class:`object` class itself does not provide the context manager methods. .. method:: object.__enter__(self) @@ -3709,6 +3724,8 @@ are awaitable. Must return an :term:`iterator`. Should be used to implement :term:`awaitable` objects. For instance, :class:`asyncio.Future` implements this method to be compatible with the :keyword:`await` expression. + The :class:`object` class itself is not awaitable and does not provide + this method. .. note:: @@ -3794,6 +3811,9 @@ its ``__anext__`` method. Asynchronous iterators can be used in an :keyword:`async for` statement. +The :class:`object` class itself does not provide these methods. + + .. method:: object.__aiter__(self) Must return an *asynchronous iterator* object. @@ -3840,6 +3860,8 @@ suspend execution in its ``__aenter__`` and ``__aexit__`` methods. Asynchronous context managers can be used in an :keyword:`async with` statement. +The :class:`object` class itself does not provide these methods. + .. method:: object.__aenter__(self) Semantically similar to :meth:`~object.__enter__`, the only diff --git a/Lib/test/test_class.py b/Lib/test/test_class.py index b88c4d16ba4ef4..7720cf157fa9ae 100644 --- a/Lib/test/test_class.py +++ b/Lib/test/test_class.py @@ -503,6 +503,56 @@ def __eq__(self, other): return 1 self.assertRaises(TypeError, hash, C2()) + def testPredefinedAttrs(self): + o = object() + + class Custom: + pass + + c = Custom() + + methods = ( + '__class__', '__delattr__', '__dir__', '__eq__', '__format__', + '__ge__', '__getattribute__', '__getstate__', '__gt__', '__hash__', + '__init__', '__init_subclass__', '__le__', '__lt__', '__ne__', + '__new__', '__reduce__', '__reduce_ex__', '__repr__', + '__setattr__', '__sizeof__', '__str__', '__subclasshook__' + ) + for name in methods: + with self.subTest(name): + self.assertTrue(callable(getattr(object, name, None))) + self.assertTrue(callable(getattr(o, name, None))) + self.assertTrue(callable(getattr(Custom, name, None))) + self.assertTrue(callable(getattr(c, name, None))) + + not_defined = [ + '__abs__', '__aenter__', '__aexit__', '__aiter__', '__anext__', + '__await__', '__bool__', '__bytes__', '__ceil__', + '__complex__', '__contains__', '__del__', '__delete__', + '__delitem__', '__divmod__', '__enter__', '__exit__', + '__float__', '__floor__', '__get__', '__getattr__', '__getitem__', + '__index__', '__int__', '__invert__', '__iter__', '__len__', + '__length_hint__', '__missing__', '__neg__', '__next__', + '__objclass__', '__pos__', '__rdivmod__', '__reversed__', + '__round__', '__set__', '__setitem__', '__trunc__' + ] + augment = ( + 'add', 'and', 'floordiv', 'lshift', 'matmul', 'mod', 'mul', 'pow', + 'rshift', 'sub', 'truediv', 'xor' + ) + not_defined.extend(map("__{}__".format, augment)) + not_defined.extend(map("__r{}__".format, augment)) + not_defined.extend(map("__i{}__".format, augment)) + for name in not_defined: + with self.subTest(name): + self.assertFalse(hasattr(object, name)) + self.assertFalse(hasattr(o, name)) + self.assertFalse(hasattr(Custom, name)) + self.assertFalse(hasattr(c, name)) + + # __call__() is defined on the metaclass but not the class + self.assertFalse(hasattr(o, "__call__")) + self.assertFalse(hasattr(c, "__call__")) def testSFBug532646(self): # Test for SF bug 532646 diff --git a/Misc/NEWS.d/next/Documentation/2023-03-28-22-24-45.gh-issue-60712.So5uad.rst b/Misc/NEWS.d/next/Documentation/2023-03-28-22-24-45.gh-issue-60712.So5uad.rst new file mode 100644 index 00000000000000..e401cc2535e389 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2023-03-28-22-24-45.gh-issue-60712.So5uad.rst @@ -0,0 +1,2 @@ +Include the :class:`object` type in the lists of documented types. +Change by Furkan Onder and Martin Panter.