Teach inpsect.getdoc() to read __slots__ with an optional data dictionary

[rhettinger]

BPO	36326
Nosy	@rhettinger, @serhiy-storchaka, @tirkarthi
PRs	bpo-36326: Let inspect.getdoc() find docstrings for __slots__ #12498

^{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-03-25.20:02:44.770>
created_at = <Date 2019-03-17.10:11:16.012>
labels = ['3.8', 'type-feature', 'library']
title = 'Teach inpsect.getdoc() to read __slots__ with an optional data dictionary'
updated_at = <Date 2019-03-25.20:02:44.770>
user = 'https://github.com/rhettinger'

bugs.python.org fields:

activity = <Date 2019-03-25.20:02:44.770>
actor = 'rhettinger'
assignee = 'none'
closed = True
closed_date = <Date 2019-03-25.20:02:44.770>
closer = 'rhettinger'
components = ['Library (Lib)']
creation = <Date 2019-03-17.10:11:16.012>
creator = 'rhettinger'
dependencies = []
files = []
hgrepos = []
issue_num = 36326
keywords = ['patch']
message_count = 4.0
messages = ['338125', '338127', '338397', '338821']
nosy_count = 3.0
nosy_names = ['rhettinger', 'serhiy.storchaka', 'xtreak']
pr_nums = ['12498']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue36326'
versions = ['Python 3.8']

[rhettinger]

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

[serhiy-storchaka]

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'

[rhettinger]

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.

[rhettinger]

New changeset d1e768a by Raymond Hettinger in branch 'master':
bpo-36326: Let inspect.getdoc() find docstrings for __slots__ (GH-12498)
d1e768a