[issue30449] Improve __slots__ datamodel documentation

[Cheryl Sabella]

Change by Cheryl Sabella :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Mariatta Wijaya]

Mariatta Wijaya  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Mariatta Wijaya]

Mariatta Wijaya  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[miss-islington]

Change by miss-islington :


--
keywords: +patch
pull_requests: +5590
stage: backport needed -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Mariatta Wijaya via Python-bugs-list]

Change by Mariatta Wijaya :


--
stage: patch review -> backport needed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Mariatta Wijaya]

Mariatta Wijaya  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Cheryl Sabella]

Cheryl Sabella  added the comment:

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!

--
nosy: +Mariatta

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Raymond Hettinger]

Change by Raymond Hettinger :


--
assignee: rhettinger -> 

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Cheryl Sabella]

Cheryl Sabella  added the comment:

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!

--
nosy: +csabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[mpb]

mpb  added the comment:

@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!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[mpb]

mpb  added the comment:

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__.

--
nosy: +mpb

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Raymond Hettinger]

Raymond Hettinger added the 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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Raymond Hettinger]

Raymond Hettinger added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
assignee: docs@python -> rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Aaron Hall]

Aaron Hall added the comment:

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!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Aaron Hall]

Changes by Aaron Hall :


--
pull_requests: +1905

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Raymond Hettinger]

Raymond Hettinger added the comment:

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.

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


--
versions: +Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


--
stage:  -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Roundup Robot]

Changes by Roundup Robot :


--
pull_requests: +1889

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Aaron Hall]

Aaron Hall added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30449] Improve __slots__ datamodel documentation

[Aaron Hall]

New submission from Aaron Hall:

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.

--
assignee: docs@python
components: Documentation
messages: 294305
nosy: Aaron Hall, docs@python
priority: normal
severity: normal
status: open
title: Improve __slots__ datamodel documentation
versions: Python 2.7, Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com