classification
Title: Teach inpsect.getdoc() to read __slots__ with an optional data dictionary
Type: enhancement Stage: resolved
Components: Library (Lib) Versions: Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: rhettinger, serhiy.storchaka, xtreak
Priority: normal Keywords: patch

Created on 2019-03-17 10:11 by rhettinger, last changed 2019-03-25 20:02 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 12498 merged rhettinger, 2019-03-22 21:11
Messages (4)
msg338125 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-03-17 10:11
The __slots__ variable already works with dictionaries.  The values are simply ignored. 

I propose teaching help() to read those optional dictionaries to give better information on member objects (much like we already have with property objects).

This is inspired by data dictionaries for database tables.

The pydoc implementation would be somewhat easy.  Roughly this:

   for name in data_descriptors:
       print(f' |  {name}'
       if isinstance(slots, dict) and name in slots:
           print(f' |      {slots[name]}')
       print(' |')


==== Example ====================================================

>>> class Bicycle:

       __slots__ = dict(
           category = 'Primary use: road, cross-over, or hybrid',
           model = 'Unique six digit vendor-supplied code',
           size = 'Rider size: child, small, medium, large, extra-large',
           price = 'Manufacturer suggested retail price', 
       )

>>> help(Bicycle)
Help on class Bicycle in module __main__:

class Bicycle(builtins.object)
 |  Data descriptors defined here:
 |  
 |  category
 |      Primary use: road, cross-over, or hybrid
 |  
 |  model
 |      Unique six digit vendor-supplied code
 |  
 |  price
 |      Rider size: child, small, medium, large, extra-large
 |  
 |  size
 |      Manufacturer suggested retail price
msg338127 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-03-17 12:50
I am not sure that this is the best application of dict as __slots__. Maybe use dict for specifying default values? Currently slots are not compatible with class-level values used as fallbacks.

Following the pattern for namedtuple attributes, docstrings for slots could be specified as:

class Bicycle:
       __slots__ = 'category', 'model', 'size', 'price'

Bicycle.category.__doc__ = 'Primary use: road, cross-over, or hybrid'
Bicycle.model.__doc__ = 'Unique six digit vendor-supplied code'
Bicycle.size.__doc__ = 'Rider size: child, small, medium, large, extra-large'
Bicycle.price.__doc__ = 'Manufacturer suggested retail price'
msg338397 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-03-19 18:55
The direct assignments to __doc__ are reasonable for named tuples because there usually isn't any code between the factory function call and the __doc__ assignments.  For other classes, the technique is awkward because it widely separates the initial field name iterable from the corresponding docstrings.

Setting default values is responsibility of the __new__ or __init__ methods. It doesn't make sense to use a __slots__ dictionary for this purpose as well.
msg338821 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-03-25 20:01
New changeset d1e768a67707bf7bb426c1537e1a764e89eaff78 by Raymond Hettinger in branch 'master':
bpo-36326: Let inspect.getdoc() find docstrings for __slots__ (GH-12498)
https://github.com/python/cpython/commit/d1e768a67707bf7bb426c1537e1a764e89eaff78
History
Date User Action Args
2019-03-25 20:02:44rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-03-25 20:01:18rhettingersetmessages: + msg338821
2019-03-22 21:12:50rhettingersettitle: Build-out help() to read __slots__ with an optional data dictionary -> Teach inpsect.getdoc() to read __slots__ with an optional data dictionary
2019-03-22 21:11:33rhettingersetkeywords: + patch
stage: patch review
pull_requests: + pull_request12448
2019-03-19 18:55:45rhettingersetmessages: + msg338397
2019-03-17 12:50:22serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg338127
2019-03-17 10:24:58xtreaksetnosy: + xtreak
2019-03-17 10:11:16rhettingercreate