Clarification in the __slots__ documentation

[kwsp]

Documentation

https://docs.python.org/3/reference/datamodel.html#notes-on-using-slots

One of the bulletpoints:

• Nonempty slots does not work for classes derived from “variable-length” built-in types such as int, bytes and tuple.

Points to clarify:

• What does "does not work" mean?
• Whats the set of "variable-length" built-in types? Is str one of them?

Linked PRs

• gh-100315: clarification to __slots__ docs. #102621
• [3.11] gh-100315: clarification to __slots__ docs. (GH-102621) #102687
• [3.10] gh-100315: clarification to __slots__ docs. (GH-102621) #102688

[AlexWaygood]

The interactive REPL is always useful for discovering some of the answers to questions like this:

>>> class Foo(int):
...   __slots__ = 'bar',
...   
Traceback (most recent call last):
  File "<string>", line 1, in <module>
TypeError: nonempty __slots__ not supported for subtype of 'int'
>>> class Foo(str):
...   __slots__ = 'bar',
...
>>>

For your first question, we could possibly change the wording to

• TypeError will be raised if nonempty slots are defined for a class derived from a “variable-length” built-in type such as int, bytes or tuple.

For your second question: I don't know what's being referred to by "variable-length builtin types", so I agree that the wording there is a little opaque.

[kumaraditya303]

You can check if any type is variable length or not from python with <type>.__itemsize__ != 0. As for what it means, variable length is a memory layout when data follows the object pointer in single block like tuple in contrast to list which stores items in a separate memory block.

[AlexWaygood]

As for what it means, variable length is a memory layout when data follows the object pointer in single block like tuple in contrast to list which stores items in a separate memory block.

Is this definition given anywhere in the documentation? If so, we could maybe link to it from the __slots__ docs here.

[AlexWaygood]

Looks like the best place to link to might be https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_itemsize. Hardly beginner-friendly, but probably better than no link at all (and I think it's good to keep the section on __slots__ in the datamodel terse).

[kumaraditya303]

Yeah, that's the best place I can find too.

[kwsp]

@kumaraditya303 I can't find __itemsize__ documented anywhere in the current documentation(docs search, duckduckgo). Could you please link any docs to __itemsize__? If its not available, could you tell me how you learnt about this, so we can add it to the docs?

[kumaraditya303]

I can't find itemsize documented anywhere in the current documentation(docs search, duckduckgo).

It is not documented as it is an internal implementation detail.

If its not available, could you tell me how you learnt about this, so we can add it to the docs?

Just read the source code, in this case it is typeobject.c which contains the logic for type objects and memory management but it is not beginner friendly. I know all this because I work in these areas of interpreter often.

[kwsp]

Looks like the best place to link to might be https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_itemsize. Hardly beginner-friendly, but probably better than no link at all (and I think it's good to keep the section on slots in the datamodel terse).

@AlexWaygood sounds good. I added this link to the docs in a PR.

[AlexWaygood]

Thanks for the PR @kwsp, and thanks for helping us figure this out @kumaraditya303! Fixed on 3.10-3.12.