8000 gh-60712: Include the "object" type in the lists of documented types … · python/cpython@4f82621 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4f82621

Browse files
furkanonderblurb-it[bot]CAM-Gerlachterryjreedymerwok
authored
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>
1 parent 6f512c6 commit 4f82621

File tree

4 files changed

+93
-18
lines changed

4 files changed

+93
-18
lines changed

‎Doc/library/functions.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1293,9 +1293,10 @@ are always available. They are listed here in alphabetical order.
12931293

12941294
.. class:: object()
12951295

1296-
Return a new featureless object. :class:`object` is a base for all classes.
1297-
It has methods that are common to all instances of Python classes. This
1298-
function does not accept any arguments.
1296+
This is the ultimate base class of all other classes. It has methods
1297+
that are common to all instances of Python classes. When the constructor
1298+
is called, it returns a new featureless object. The constructor does not
1299+
accept any arguments.
12991300

13001301
.. note::
13011302

‎Doc/reference/datamodel.rst

Lines changed: 37 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2033,7 +2033,8 @@ Basic customization
20332033
"informal" string representation of instances of that class is required.
20342034

20352035
This is typically used for debugging, so it is important that the representation
2036-
is information-rich and unambiguous.
2036+
is information-rich and unambiguous. A default implementation is provided by the
2037+
:class:`object` class itself.
20372038

20382039
.. index::
20392040
single: string; __str__() (object method)
@@ -2043,10 +2044,10 @@ Basic customization
20432044

20442045
.. method:: object.__str__(self)
20452046

2046-
Called by :func:`str(object) <str>` and the built-in functions
2047-
:func:`format` and :func:`print` to compute the "informal" or nicely
2047+
Called by :func:`str(object) <str>`, the default :meth:`__format__` implementation,
2048+
and the built-in function :func:`print`, to compute the "informal" or nicely
20482049
printable string representation of an object. The return value must be a
2049-
:ref:`string <textseq>` object.
2050+
:ref:`str <textseq>` object.
20502051

20512052
This method differs from :meth:`object.__repr__` in that there is no
20522053
expectation that :meth:`__str__` return a valid Python expression: a more
@@ -2063,7 +2064,8 @@ Basic customization
20632064
.. index:: pair: built-in function; bytes
20642065

20652066
Called by :ref:`bytes <func-bytes>` to compute a byte-string representation
2066-
of an object. This should return a :class:`bytes` object.
2067+
of an object. This should return a :class:`bytes` object. The :class:`object`
2068+
class itself does not provide this method.
20672069

20682070
.. index::
20692071
single: string; __format__() (object method)
@@ -2087,6 +2089,9 @@ Basic customization
20872089

20882090
The return value must be a string object.
20892091

2092+
The default implementation by the :class:`object` class should be given
2093+
an empty *format_spec* string. It delegates to :meth:`__str__`.
2094+
20902095
.. versionchanged:: 3.4
20912096
The __format__ method of ``object`` itself raises a :exc:`TypeError`
20922097
if passed any non-empty string.
@@ -2129,6 +2134,12 @@ Basic customization
21292134
``(x<y or x==y)`` does not imply ``x<=y``. To automatically generate ordering
21302135
operations from a single root operation, see :func:`functools.total_ordering`.
21312136

2137+
By default, the :class:`object` class provides implementations consistent
2138+
with :ref:`expressions-value-comparisons`: equality compares according to
2139+
object identity, and order comparisons raise :exc:`TypeError`. Each default
2140+
method may generate these results directly, but may also return
2141+
:data:`NotImplemented`.
2142+
21322143
See the paragraph on :meth:`__hash__` for
21332144
some important notes on creating :term:`hashable` objects which support
21342145
custom comparison operations and are usable as dictionary keys.
@@ -2184,9 +2195,9 @@ Basic customization
21842195
bucket).
21852196

21862197
User-defined classes have :meth:`__eq__` and :meth:`__hash__` methods
2187-
by default; with them, all objects compare unequal (except with themselves)
2188-
and ``x.__hash__()`` returns an appropriate value such that ``x == y``
2189-
implies both that ``x is y`` and ``hash(x) == hash(y)``.
2198+
by default (inherited from the :class:`object` class); with them, all objects compare
2199+
unequal (except with themselves) and ``x.__hash__()`` returns an appropriate
2200+
value such that ``x == y`` implies both that ``x is y`` and ``hash(x) == hash(y)``.
21902201

21912202
A class that overrides :meth:`__eq__` and does not define :meth:`__hash__`
21922203
will have its :meth:`__hash__` implicitly set to ``None``. When the
@@ -2236,8 +2247,8 @@ Basic customization
22362247
``bool()``; should return ``False`` or ``True``. When this method is not
22372248
defined, :meth:`~object.__len__` is called, if it is defined, and the object is
22382249
considered true if its result is nonzero. If a class defines neither
2239-
:meth:`!__len__` nor :meth:`!__bool__`, all its instances are considered
2240-
true.
2250+
:meth:`!__len__` nor :meth:`!__bool__` (which is true of the :class:`object`
2251+
class itself), all its instances are considered true.
22412252

22422253

22432254
.. _attribute-access:
@@ -2259,6 +2270,7 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
22592270
for ``self``; or :meth:`__get__` of a *name* property raises
22602271
:exc:`AttributeError`). This method should either return the (computed)
22612272
attribute value or raise an :exc:`AttributeError` exception.
2273+
The :class:`object` class itself does not provide this method.
22622274

22632275
Note that if the attribute is found through the normal mechanism,
22642276
: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
23972409
descriptor must be in either the owner's class dictionary or in the class
23982410
dictionary for one of its parents). In the examples below, "the attribute"
23992411
refers to the attribute whose name is the key of the property in the owner
2400-
class' :attr:`~object.__dict__`.
2401-
2412+
class' :attr:`~object.__dict__`. The :class:`object` class itself does not
2413+
implement any of these protocols.
24022414

24032415
.. method:: object.__get__(self, instance, owner=None)
24042416

@@ -3090,17 +3102,19 @@ Emulating callable objects
30903102

30913103
Called when the instance is "called" as a function; if this method is defined,
30923104
``x(arg1, arg2, ...)`` roughly translates to ``type(x).__call__(x, arg1, ...)``.
3105+
The :class:`object` class itself does not provide this method.
30933106

30943107

30953108
.. _sequence-types:
30963109

30973110
Emulating container types
30983111
-------------------------
30993112

3100-
The following methods can be defined to implement container objects. Containers
3101-
usually are :term:`sequences <sequence>` (such as :class:`lists <list>` or
3113+
The following methods can be defined to implement container objects. None of them
3114+
are provided by the :class:`object` class itself. Containers usually are
3115+
:term:`sequences <sequence>` (such as :class:`lists <list>` or
31023116
:class:`tuples <tuple>`) or :term:`mappings <mapping>` (like
3103-
:class:`dictionaries <dict>`),
3117+
:term:`dictionaries <dictionary>`),
31043118
but can represent other containers as well. The first set of methods is used
31053119
either to emulate a sequence or to emulate a mapping; the difference is that for
31063120
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
34603474
global state, locking and unlocking resources, closing opened files, etc.
34613475

34623476
For more information on context managers, see :ref:`typecontextmanager`.
3477+
The :class:`object` class itself does not provide the context manager methods.
34633478

34643479

34653480
.. method:: object.__enter__(self)
@@ -3709,6 +3724,8 @@ are awaitable.
37093724
Must return an :term:`iterator`. Should be used to implement
37103725
:term:`awaitable` objects. For instance, :class:`asyncio.Future` implements
37113726
this method to be compatible with the :keyword:`await` expression.
3727+
The :class:`object` class itself is not awaitable and does not provide
3728+
this method.
37123729

37133730
.. note::
37143731

< EF5E div class="d-flex flex-row">
@@ -3794,6 +3811,9 @@ its ``__anext__`` method.
37943811

37953812
Asynchronous iterators can be used in an :keyword:`async for` statement.
37963813

3814+
The :class:`object` class itself does not provide these methods.
3815+
3816+
37973817
.. method:: object.__aiter__(self)
37983818

37993819
Must return an *asynchronous iterator* object.
@@ -3840,6 +3860,8 @@ suspend execution in its ``__aenter__`` and ``__aexit__`` methods.
38403860

38413861
Asynchronous context managers can be used in an :keyword:`async with` statement.
38423862

3863+
The :class:`object` class itself does not provide these methods.
3864+
38433865
.. method:: object.__aenter__(self)
38443866

38453867
Semantically similar to :meth:`~object.__enter__`, the only

‎Lib/test/test_class.py

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,56 @@ def __eq__(self, other): return 1
503503

504504
self.assertRaises(TypeError, hash, C2())
505505

506+
def testPredefinedAttrs(self):
507+
o = object()
508+
509+
class Custom:
510+
pass
511+
512+
c = Custom()
513+
514+
methods = (
515+
'__class__', '__delattr__', '__dir__', '__eq__', '__format__',
516+
'__ge__', '__getattribute__', '__getstate__', '__gt__', '__hash__',
517+
'__init__', '__init_subclass__', '__le__', '__lt__', '__ne__',
518+
'__new__', '__reduce__', '__reduce_ex__', '__repr__',
519+
'__setattr__', '__sizeof__', '__str__', '__subclasshook__'
520+
)
521+
for name in methods:
522+
with self.subTest(name):
523+
self.assertTrue(callable(getattr(object, name, None)))
524+
self.assertTrue(callable(getattr(o, name, None)))
525+
self.assertTrue(callable(getattr(Custom, name, None)))
526+
self.assertTrue(callable(getattr(c, name, None)))
527+
528+
not_defined = [
529+
'__abs__', '__aenter__', '__aexit__', '__aiter__', '__anext__',
530+
'__await__', '__bool__', '__bytes__', '__ceil__',
531+
'__complex__', '__contains__', '__del__', '__delete__',
532+
'__delitem__', '__divmod__', '__enter__', '__exit__',
533+
'__float__', '__floor__', '__get__', '__getattr__', '__getitem__',
534+
'__index__', '__int__', '__invert__', '__iter__', '__len__',
535+
'__length_hint__', '__missing__', '__neg__', '__next__',
536+
'__objclass__', '__pos__', '__rdivmod__', '__reversed__',
537+
'__round__', '__set__', '__setitem__', '__trunc__'
538+
]
539+
augment = (
540+
'add', 'and', 'floordiv', 'lshift', 'matmul', 'mod', 'mul', 'pow',
541+
'rshift', 'sub', 'truediv', 'xor'
542+
)
543+
not_defined.extend(map("__{}__".format, augment))
544+
not_defined.extend(map("__r{}__".format, augment))
545+
not_defined.extend(map("__i{}__".format, augment))
546+
for name in not_defined:
547+
with self.subTest(name):
548+
self.assertFalse(hasattr(object, name))
549+
self.assertFalse(hasattr(o, name))
550+
self.assertFalse(hasattr(Custom, name))
551+
self.assertFalse(hasattr(c, name))
552+
553+
# __call__() is defined on the metaclass but not the class
554+
self.assertFalse(hasattr(o, "__call__"))
555+
self.assertFalse(hasattr(c, "__call__"))
506556

507557
def testSFBug532646(self):
508558
# Test for SF bug 532646

‎Misc/NEWS.d/next/Documentation/2023-03-28-22-24-45.gh-issue-60712.So5uad.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Include the :class:`object` type in the lists of documented types.
2+
Change by Furkan Onder and Martin Panter.

0 commit comments

Comments
 (0)
0