The __slots__ documentation in the datamodel needs improvement.

For example:

> When inheriting from a class without __slots__, the __dict__ attribute of that class will always be accessible, so a __slots__ definition in the subclass is meaningless.

The __slots__ definition for such a subclass is not meaningless: other slots declared will still be used, and the __dict__ will not be instantiated unless it is looked for (although this may be an implementation detail).

> The action of a __slots__ declaration is limited to the class where it is defined. As a result, subclasses will have a __dict__ unless they also define __slots__ (which must only contain names of any additional slots).

That's not quite right either. The action of a __slots__ declaration is not entirely limited to the class where it is defined. They can have implications for multiple inheritance, and child classes will have access to those slots.

I have some changes I'd like to make to the entire section on __slots__, and I'll be providing a pull request soon.

I've been working on this section quite a lot, trying to improve the flow of content (which in the prior revision is a bit of a mish-mash of information in the "Notes on using __slots__ section") - I intend to move some of that information into the exposition/introduction.

I have also been reviewing my changes and actively working on it with a volunteer at the PyCon sprints, Joshua Goldin. Will submit a pull request soon, tonight or tomorrow morning.

As much as possible, please stick with the existing terse style of the data model docs.  They tend to be concise, direct, and very light on examples.  They don't serve as a tutorial, faq, or cover programming patterns or advice.

Looking at the PR, I don't think most of these changes should be made.

I created a new PR based on rhettinger's feedback (which on consideration was quite correct) with a fresh branch from master. 

Terseness is retained, and I think this revision makes the documentation more correct and complete. The rewording makes the behavior more clear (IMHO).

No example code is needed for this revision, so I didn't give any, but one or two class definitions might be desirable.

Feedback is quite welcome!

Overall this looks good.  Please do fix the one review comment.

New changeset 2b44e302ec3079363c4d5c875677945953705c58 by Raymond Hettinger (Aaron Hall, MBA) in branch 'master':
bpo-30449 Terse slots (#1819)
https://github.com/python/cpython/commit/2b44e302ec3079363c4d5c875677945953705c58

Can __slots__ be assigned a string?  If so, what are the consequences?  I find the current docs lack clarity.  For example from the docs for 3.7.0a3:

https://docs.python.org/3.7/reference/datamodel.html#slots

>  3.3.2.4. __slots__
>
>  [snip]
>
>  object.__slots__
>    This class variable can be assigned a string,
>    iterable, or sequence of strings [snip]

However, "3.3.2.4.1. Notes on using __slots__" does not discuss what happens when a string is assigned to __slots__.

The "notes" section does discuss assigning a "sequence of strings" to __slots__.

The "notes" section also says: "Any non-string iterable may be assigned to __slots__."

Based on quick experimentation, it appears that the string must be a single identifier.  I get a TypeError if I try to assign "foo bar" to __slots__.  The consequence of a string appears to be that only a single slot is created.  It would be nice if this was stated clearly in the docs.

The docs for 2.7 seem similar to version 3.7.0a3.  So maybe all versions of the docs could be improved regarding the specifics of what happens when you assign a string to __slots__.

mpb, I think the docs with respect to strings are fine as-is.  Sometimes if too much detail is put in, it makes the docs harder to read and understand (i.e. it gets in the way of our primary purpose).

@rhettinger

I disagree (but you're the boss).  If a function can take type X as a parameter, I believe docs should also say what the expected behavior is when you call the function and pass it type X, especially when type X is fundamentally different from every other type the function accepts.  (And yes, __slots__ is not a function, but I still find the metaphor apt.) 
 Cheers!

It looks like this documentation patch was applied to master.  Does it need to be backported to 3.6 and 2.7 for the issue to be closed?  Thanks!

Mariatta,

Do you think this one needs to be backported?  You had originally added the labels on the pull request, then removed them.  I wasn't sure if that was needed before being able to close this.

Thanks!

Yes I think we can backport this to 3.6 and 2.7.

We can't auto backport to 2.7 because of conflict.
Aaron can you prepare the backport PR?

New changeset 6eab93cfe5ee08a6168e5bb69474e461cc7ac535 by Mariatta (Miss Islington (bot)) in branch '3.6':
bpo-30449: Improve __slots__ documentation (GH-1819)
https://github.com/python/cpython/commit/6eab93cfe5ee08a6168e5bb69474e461cc7ac535