Skip to content

Improve __slots__ datamodel documentation #74634

Closed
Closed
Improve __slots__ datamodel documentation#74634
Labels
3.7 (EOL)end of lifedocsDocumentation in the Doc dir

Description

@aaronchall
aaronchall
mannequin
opened on May 24, 2017
BPO 30449
Nosy @rhettinger, @aaronchall, @Mariatta, @csabella
PRs
  • bpo-30449: Improve __slots__ documentation #1806
  • bpo-30449 Terse slots #1819
  • [3.6] bpo-30449 Terse slots (GH-1819) #5815
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
closed_at = <Date 2019-02-15.23:36:05.333>
created_at = <Date 2017-05-24.01:01:47.039>
labels = ['3.7', 'docs']
title = 'Improve __slots__ datamodel documentation'
updated_at = <Date 2019-02-15.23:36:05.333>
user = 'https://github.com/aaronchall'

    bugs.python.org fields:

    activity = <Date 2019-02-15.23:36:05.333>
actor = 'cheryl.sabella'
assignee = 'none'
closed = True
closed_date = <Date 2019-02-15.23:36:05.333>
closer = 'cheryl.sabella'
components = ['Documentation']
creation = <Date 2017-05-24.01:01:47.039>
creator = 'Aaron Hall'
dependencies = []
files = []
hgrepos = []
issue_num = 30449
keywords = ['patch']
message_count = 14.0
messages = ['294305', '294310', '294429', '294515', '294521', '294532', '309213', '309274', '309293', '311470', '312569', '312571', '312572', '312574']
nosy_count = 6.0
nosy_names = ['rhettinger', 'docs@python', 'mpb', 'Aaron Hall', 'Mariatta', 'cheryl.sabella']
pr_nums = ['1806', '1819', '5815']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue30449'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7']

    Activity

    1. aaronchall commented on May 24, 2017

      @aaronchall
      aaronchallmannequin
      on May 24, 2017
      MannequinAuthor

      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.

    2. aaronchall
      assigned
      docspython
      on May 24, 2017
    3. aaronchall
      added
      3.7 (EOL)end of life
      docsDocumentation in the Doc dir
      on May 24, 2017

    4. aaronchall commented on May 24, 2017

      @aaronchall
      aaronchallmannequin
      on May 24, 2017
      MannequinAuthor

      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.

    5. rhettinger commented on May 25, 2017

      @rhettinger
      rhettinger
      on May 25, 2017
      Contributor

      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.

    6. aaronchall commented on May 25, 2017

      @aaronchall
      aaronchallmannequin
      on May 25, 2017
      MannequinAuthor

      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!

    7. rhettinger commented on May 26, 2017

      @rhettinger
      rhettinger
      on May 26, 2017
      Contributor

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

    8. rhettinger
      assigned
      rhettinger
      and unassigned
      docspython
      on May 26, 2017

    9. rhettinger commented on May 26, 2017

      @rhettinger
      rhettinger
      on May 26, 2017
      Contributor

      New changeset 2b44e30 by Raymond Hettinger (Aaron Hall, MBA) in branch 'master':
      bpo-30449 Terse slots (bpo-1819)
      2b44e30

    10. mpb commented on Dec 30, 2017

      @mpb
      mpbmannequin
      on Dec 30, 2017
      Mannequin

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

    11. rhettinger commented on Dec 31, 2017

      @rhettinger
      rhettinger
      on Dec 31, 2017
      Contributor

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

    12. mpb commented on Dec 31, 2017

      @mpb
      mpbmannequin
      on Dec 31, 2017
      Mannequin

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

    13. csabella commented on Feb 2, 2018

      @csabella
      csabella
      on Feb 2, 2018
      Contributor

      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!

    14. rhettinger
      removed their assignment
      on Feb 2, 2018

    15. csabella commented on Feb 22, 2018

      @csabella
      csabella
      on Feb 22, 2018
      Contributor

      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!

    16. Mariatta commented on Feb 22, 2018

      @Mariatta
      Mariatta
      on Feb 22, 2018
      Member

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

    17. Mariatta commented on Feb 22, 2018

      @Mariatta
      Mariatta
      on Feb 22, 2018
      Member

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

    18. Mariatta commented on Feb 22, 2018

      @Mariatta
      Mariatta
      on Feb 22, 2018
      Member

      New changeset 6eab93c by Mariatta (Miss Islington (bot)) in branch '3.6':
      bpo-30449: Improve __slots__ documentation (GH-1819)
      6eab93c

    19. csabella
      closed this as completedon Feb 15, 2019
    20. ezio-melotti
      transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    No one assigned

      Labels

      3.7 (EOL)end of lifedocsDocumentation in the Doc dir

      Projects

      No projects

        Milestone

        No milestone

        Relationships

        None yet

        Development

        No branches or pull requests

        Issue actions