classification
Title: Missing documentation for setting module __class__ attribute
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: 22986 32225 Superseder:
Assigned To: docs@python Nosy List: cheryl.sabella, docs@python, ncoghlan, njs
Priority: normal Keywords: patch

Created on 2016-07-13 01:32 by ncoghlan, last changed 2018-01-27 02:46 by ncoghlan. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 5320 merged cheryl.sabella, 2018-01-25 15:38
PR 5321 merged cheryl.sabella, 2018-01-25 15:51
Messages (9)
msg270285 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2016-07-13 01:32
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 #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.
msg307930 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-12-10 00:02
Hi Nick,

I started looking at this issue for documenting #22986 and then found #24912 and #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 #24991 should be continued or should the documentation mentioned in this issue still be done?

Thanks!
msg307936 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-12-10 00:41
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 #24991 is a fairly different topic - I've added an extra comment there that should help clarify the actual question/proposal.
msg310643 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-01-24 22:51
Nick, 

It looks like #32225 took care of this documentation change, so I think this can be closed?  Thanks!
msg310656 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-01-25 05:39
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.
msg310681 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-01-25 15:52
Thanks Nick.  I've made the PRs for the versionadded and to add __class__ to the 3.6 docs.
msg310833 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-01-27 02:40
New changeset 85527cf50a9a4eecaca4022f7c6cb9e0bae1fa5f by Nick Coghlan (Cheryl Sabella) in branch 'master':
bpo-27505: Add change notes in module attribute docs (GH-5320)
https://github.com/python/cpython/commit/85527cf50a9a4eecaca4022f7c6cb9e0bae1fa5f
msg310834 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-01-27 02:45
New changeset 8f68cb7db37322cfeeb8338e78474e5f25d930c5 by Nick Coghlan (Cheryl Sabella) in branch '3.6':
[3.6] bpo-27505: Retrofit module __class__ documentation from 3.7 (GH-5321)
https://github.com/python/cpython/commit/8f68cb7db37322cfeeb8338e78474e5f25d930c5
msg310835 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-01-27 02:46
Thanks for the PRs!
History
Date User Action Args
2018-01-27 02:46:58ncoghlansetstatus: open -> closed
resolution: fixed
messages: + msg310835

stage: patch review -> resolved
2018-01-27 02:45:27ncoghlansetmessages: + msg310834
2018-01-27 02:40:54ncoghlansetmessages: + msg310833
2018-01-25 15:53:44cheryl.sabellasetstage: needs patch -> patch review
2018-01-25 15:52:52cheryl.sabellasetstage: patch review -> needs patch
messages: + msg310681
versions: + Python 3.7, - Python 3.5
2018-01-25 15:51:56cheryl.sabellasetpull_requests: + pull_request5166
2018-01-25 15:38:30cheryl.sabellasetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request5165
2018-01-25 05:39:01ncoghlansetmessages: + msg310656
2018-01-24 22:51:17cheryl.sabellasetmessages: + msg310643
2017-12-10 00:41:24ncoghlansetdependencies: + Implement PEP 562: module __getattr__ and __dir__
messages: + msg307936
2017-12-10 00:02:21cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg307930
2016-07-13 01:32:13ncoghlansetdependencies: + Improved handling of __class__ assignment
2016-07-13 01:32:01ncoghlancreate