Documentation

Problem

The short documentation shown by help()/pydoc makes object.__sizeof__() and sys.getsizeof() look almost equivalent, even though they may return different values in practice.

For example, their short descriptions currently read very similarly:

• sys.getsizeof():

  Return the size of object in bytes.

• object.__sizeof__():

  "Size of object in memory, in bytes."

From these short descriptions, a user can reasonably assume that both functions report the same value.

Why this is confusing

In practice, they can differ.

sys.getsizeof() may return a larger value than obj.__sizeof__(), because it is not just a direct alias for __sizeof__(). The full documentation for sys.getsizeof() explains the extra behavior, but that distinction is not obvious from the short help output.

This makes the following kind of session surprising:

import sys

class A:
    pass

obj = A()

print(obj.__sizeof__())
print(sys.getsizeof(obj))

A user who relies on help() or short docstrings may expect the first two values to match, but they may not.

Suggestion

It may be helpful to clarify this distinction in the short documentation, so that it is visible without referring to the full documentation.

In particular, it could clarify that:

• sys.getsizeof() may include additional overhead beyond the value returned by __sizeof__()

Linked PRs

• gh-146086: Clarify sys.getsizeof() docstring regarding additional overhead #146087