Missing documentation for setting module __class__ attribute

[ncoghlan]

BPO	27505
Nosy	@ncoghlan, @njsmith, @csabella
PRs	bpo-27505: Add version_added to docs for module attributes #5320 [3.6] bpo-27505: Retrofit module __class__ documentation from 3.7 #5321
Dependencies	bpo-22986: Improved handling of class assignment bpo-32225: Implement PEP 562: module getattr and dir

^{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 2018-01-27.02:46:58.983>
created_at = <Date 2016-07-13.01:32:01.924>
labels = ['type-feature', '3.7', 'docs']
title = 'Missing documentation for setting module __class__ attribute'
updated_at = <Date 2018-01-27.02:46:58.982>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2018-01-27.02:46:58.982>
actor = 'ncoghlan'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-01-27.02:46:58.983>
closer = 'ncoghlan'
components = ['Documentation']
creation = <Date 2016-07-13.01:32:01.924>
creator = 'ncoghlan'
dependencies = ['22986', '32225']
files = []
hgrepos = []
issue_num = 27505
keywords = ['patch']
message_count = 9.0
messages = ['270285', '307930', '307936', '310643', '310656', '310681', '310833', '310834', '310835']
nosy_count = 4.0
nosy_names = ['ncoghlan', 'njs', 'docs@python', 'cheryl.sabella']
pr_nums = ['5320', '5321']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue27505'
versions = ['Python 3.6', 'Python 3.7']

[ncoghlan]

Python 3.5 added the ability to set module __class__ attributes by way of http://bugs.python.org/issue22986

However, this isn't covered in the What's New guide or anywhere else in the documentation, and even in the NEWS file it appears under the cryptic title "Issue bpo-22986: Allow changing an object’s __class__ between a dynamic type and static type in some cases." for 3.5.0a1

This should be documented somewhere (perhaps in the data model section of the language reference?) and an example given of using the feature to emit DeprecationWarning for access to a particular module level attribute.

It should also be mentioned in the Python 3.5 What's New documentation.

[csabella]

Hi Nick,

I started looking at this issue for documenting bpo-22986 and then found bpo-24912 and bpo-24991. Has anything changed in the code since 2015 that would make these issues (this one and 24991) obsolete? It seems there were a lot of ideas flying around, but I couldn't find other tickets (and the code is still in place for 22986 and 24912). If these haven't been superseded, do you think the discussion on bpo-24991 should be continued or should the documentation mentioned in this issue still be done?

Thanks!

[ncoghlan]

This is still a valid docs issue, although PEP-562's module __getattr__ and __dir__ will provide a simpler alternative for most of the cases that previously required setting the __class__ attribute: https://www.python.org/dev/peps/pep-0562/

So I've added https://bugs.python.org/issue32225 as a dependency for this issue, as it will likely make sense to figure out a good docs structure for those changes first, and then see if there's any work left to do specifically for this issue: https://bugs.python.org/issue32225#msg307935

Issue bpo-24991 is a fairly different topic - I've added an extra comment there that should help clarify the actual question/proposal.

[csabella]

Nick,

It looks like bpo-32225 took care of this documentation change, so I think this can be closed? Thanks!

[ncoghlan]

I think the only thing missing for the 3.7 docs now would be a pair of "versionchanged" notes indicating that __class__ has been settable since 3.5, while module level __dir__ and __getattr__ support is new in 3.7.

It would also be desirable to add the __class__ docs to the 3.6 maintenance branch.

[csabella]

Thanks Nick. I've made the PRs for the versionadded and to add __class__ to the 3.6 docs.

[ncoghlan]

New changeset 85527cf by Nick Coghlan (Cheryl Sabella) in branch 'master':
bpo-27505: Add change notes in module attribute docs (GH-5320)
85527cf

[ncoghlan]

New changeset 8f68cb7 by Nick Coghlan (Cheryl Sabella) in branch '3.6':
[3.6] bpo-27505: Retrofit module __class__ documentation from 3.7 (GH-5321)
8f68cb7

[ncoghlan]

Thanks for the PRs!