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

Activity

1. rhettinger commented on Mar 17, 2019

   

   rhettinger

   on Mar 17, 2019

   ContributorAuthor

   More actions

   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
2. rhettinger

   added

   3.8 (EOL)end of lifeend of life

   stdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directory

   type-featureA feature request or enhancementA feature request or enhancement

   on Mar 17, 2019
3. serhiy-storchaka commented on Mar 17, 2019

   

   serhiy-storchaka

   on Mar 17, 2019

   Member

   More actions

   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'
4. rhettinger commented on Mar 19, 2019

   

   rhettinger

   on Mar 19, 2019

   ContributorAuthor

   More actions

   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.
5. rhettinger

   changed the title [-]Build-out help() to read __slots__ with an optional data dictionary[/-] [+]Teach inpsect.getdoc() to read __slots__ with an optional data dictionary[/+] on Mar 22, 2019
6. rhettinger commented on Mar 25, 2019

   

   rhettinger

   on Mar 25, 2019

   ContributorAuthor

   More actions

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

   closed this as completedon Mar 25, 2019
8. ezio-melotti

   transferred this issue fromon Apr 10, 2022