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

[rhettinger]

BPO	36326
Nosy	@rhettinger, @serhiy-storchaka, @tirkarthi
PRs	python/cpython#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: ```python assignee = None closed_at = created_at = labels = ['3.8', 'type-feature', 'library'] title = 'Teach inpsect.getdoc() to read __slots__ with an optional data dictionary' updated_at = user = 'https://github.com/rhettinger' ``` bugs.python.org fields: ```python activity = actor = 'rhettinger' assignee = 'none' closed = True closed_date = closer = 'rhettinger' components = ['Library (Lib)'] creation = 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 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