classification
Title: Improve __slots__ datamodel documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: Aaron Hall, Mariatta, cheryl.sabella, docs@python, mpb, rhettinger
Priority: normal Keywords: patch

Created on 2017-05-24 01:01 by Aaron Hall, last changed 2019-02-15 23:36 by cheryl.sabella. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 1806 closed python-dev, 2017-05-25 00:30
PR 1819 merged Aaron Hall, 2017-05-25 21:43
PR 5815 merged miss-islington, 2018-02-22 17:28
Messages (14)
msg294305 - (view) Author: Aaron Hall (Aaron Hall) * Date: 2017-05-24 01:01
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.
msg294310 - (view) Author: Aaron Hall (Aaron Hall) * Date: 2017-05-24 02:25
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.
msg294429 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-05-25 03:50
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.
msg294515 - (view) Author: Aaron Hall (Aaron Hall) * Date: 2017-05-25 21:58
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!
msg294521 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-05-26 02:14
Overall this looks good.  Please do fix the one review comment.
msg294532 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-05-26 05:33
New changeset 2b44e302ec3079363c4d5c875677945953705c58 by Raymond Hettinger (Aaron Hall, MBA) in branch 'master':
bpo-30449 Terse slots (#1819)
https://github.com/python/cpython/commit/2b44e302ec3079363c4d5c875677945953705c58
msg309213 - (view) Author: mpb (mpb) Date: 2017-12-30 03:15
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__.
msg309274 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-12-31 10:56
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).
msg309293 - (view) Author: mpb (mpb) Date: 2017-12-31 17:41
@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!
msg311470 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-02 00:02
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!
msg312569 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-22 14:42
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!
msg312571 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-02-22 17:25
Yes I think we can backport this to 3.6 and 2.7.
msg312572 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-02-22 17:32
We can't auto backport to 2.7 because of conflict.
Aaron can you prepare the backport PR?
msg312574 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-02-22 17:37
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
History
Date User Action Args
2019-02-15 23:36:05cheryl.sabellasetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-02-22 17:37:43Mariattasetmessages: + msg312574
2018-02-22 17:32:08Mariattasetmessages: + msg312572
2018-02-22 17:28:00miss-islingtonsetkeywords: + patch
stage: backport needed -> patch review
pull_requests: + pull_request5590
2018-02-22 17:25:35Mariattasetstage: patch review -> backport needed
2018-02-22 17:25:28Mariattasetmessages: + msg312571
2018-02-22 14:42:22cheryl.sabellasetnosy: + Mariatta
messages: + msg312569
2018-02-02 10:00:41rhettingersetassignee: rhettinger ->
2018-02-02 00:02:18cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg311470
2017-12-31 17:41:41mpbsetmessages: + msg309293
2017-12-31 10:56:12rhettingersetmessages: + msg309274
2017-12-30 03:15:32mpbsetnosy: + mpb
messages: + msg309213
2017-05-26 05:33:28rhettingersetmessages: + msg294532
2017-05-26 02:14:13rhettingersetassignee: docs@python -> rhettinger
2017-05-26 02:14:05rhettingersetmessages: + msg294521
2017-05-25 21:58:29Aaron Hallsetmessages: + msg294515
2017-05-25 21:43:51Aaron Hallsetpull_requests: + pull_request1905
2017-05-25 03:50:05rhettingersetnosy: + rhettinger
messages: + msg294429
2017-05-25 01:06:04Mariattasetversions: + Python 3.5
2017-05-25 01:04:58Mariattasetstage: patch review
2017-05-25 00:30:54python-devsetpull_requests: + pull_request1889
2017-05-24 02:25:57Aaron Hallsetmessages: + msg294310
2017-05-24 01:01:47Aaron Hallcreate