如何在Sphinx中记录带有@dataclass注释的可调用类？

huangapple
go评论111阅读模式
英文:

How to document callable classes annotated with @dataclass in sphinx?

问题

I researched this topic and cannot see a clear solution. There is a similar SO question

My problem is that I have a class with attr.dataclass and typing_extensions.final annotations and I don't want them to be documented but I still want to describe the class from the point of how it would be called.

For instance,

  1. @final
  2. @dataclass(frozen=True, slots=True)
  3. class Casting(object):
  4.   
  5.   _int_converter_function = int
  6.   _float_converter_function = float
  8.   def __call__(self, casting, value_to_cast):
  9.     if casting['type'] == 'integer':
  10.         return self._int_converter_function(value_to_cast)
  11.     return self._float_converter_function(value_to_cast)

This is approximately equivalent to this (which is far away from being accurate):

  1. class Casting(object):
  2.   
  3.   def __init__(
  4.     self,
  5.     int_converter_function = int,
  6.     float_converter_function = float,
  7.   ):
  8.     self.int_converter_function = int_converter_function
  9.     self.float_converter_function = float_converter_function
  11.   def converter(self, casting, value):
  12.     self.value = value
  13.     yield
  14.     type = casting['type']
  15.     if type == 'integer':
  16.       yield self.int_converter_function(value)
  17.     else:
  18.       yield self.float_converter_function(value)

and with the latest it is clear that I can document each method with docstrings and in Sphinx do:

  1. .. autoclass:: package.Casting
  2.   :members:
  3.   .. automethod:: __init__(self, int_converter_function, float_converter_function)

How to do the same with annotations?

UPDATE:

I figured out that my questions should be more specific. I want to

  1. Eliminate dataclass completely from the doc but nevertheless, keep the class in the documentation. It messes classes so much that the docs are unreadable.

  2. Make a docstring on the __init__ but also keep it separate from the callable description. I left a comment.

Example of the doc:

  1.     """Cast one type of code to another.
  3.     Constructor arguments:
  5.         :param int_converter_function: function to convert to int
  6.  
  7.         :param float_converter_function: function to convert to float
  9.     Callable arguments:
  11.     :param casting: :term:`casting` object
  12.     :type casting: dict
  14.     :param value_to_cast: input value
  16.     :return: Casted value
  17.     
  18.     Example
  19.         >>> cast = Casting(int)
  20.         >>> cast({'type': 'integer'}, '123')
  21.         123
  22.         >>> cast({'type': 'decimal'}, '123.12')
  23.         Decimal('123.12')
  25.     """

UPDATE 2:

The full class as it is below:

  1.     # -*- coding: utf-8 -*-
  2.     
  3.     from attr import dataclass
  4.     from typing_extensions import final
  5.     
  6.     @final
  7.     @dataclass(frozen=True, slots=True)
  8.     class Casting(object):
  9.         """Cast one type of code to another.
  10.     
  11.         Constructor arguments:
  12.     
  13.             :param int_converter_function: function to convert to int
  14.     
  15.             :param float_converter_function: function to convert to float
  16.     
  17.         Callable arguments:
  18.     
  19.         :param casting: :term:`casting` object
  20.         :type casting: dict
  21.     
  22.         :param value_to_cast: input value
  23.     
  24.         :return: Casted value
  25.     
  26.         Example
  27.             >>> cast = Casting(int)
  28.             >>> cast({'type': 'integer'}, '123')
  29.             123
  30.             >>> cast({'type': 'decimal'}, '123.12')
  31.             Decimal('123.12')
  32.     
  33.         """
  34.     
  35.         _int_converter_function = int
  36.         _float_converter_function = float
  37.     
  38.         def __call__(self, casting, value_to_cast):
  39.             if casting['type'] == 'integer':
  40.                 return self._int_converter_function(value_to_cast)
  41.             return self._float_converter_function(value_to_cast)

I want to eliminate package.casting.dataclass from the doc.

英文:

I researched this topic and cannot see a clear solution. There is a similar SO question

My problem is that I have a class with attr.dataclass and typing_extensions.final annotations and I don't want them to be documented but I still want to describe the class from the point of how it would be called.

For instance,

  1. @final
  2. @dataclass(frozen=True, slots=True)
  3. class Casting(object):
  4.   
  5.   _int_converter_function = int
  6.   _float_converter_function = float
  8.   def __call__(self, casting, value_to_cast):
  9.     if casting['type'] == 'integer':
  10.         return self._int_converter_function(value_to_cast)
  11.     return self._float_converter_function(value_to_cast)

This is approximately equivalent to this (which is far away from being accurate):

  1. class Casting(object):
  2.   
  3.   def __init__(
  4.     self,
  5.     int_converter_function = int,
  6.     float_converter_function = float,
  7.   ):
  8.     self.int_converter_function = int_converter_function
  9.     self.float_converter_function = float_converter_function
  11.   def converter(self, casting, value):
  12.     self.value = value
  13.     yield
  14.     type = casting['type']
  15.     if type == 'integer':
  16.       yield self.int_converter_function(value)
  17.     else:
  18.       yield self.float_converter_function(value)

and with the latest it is clear that I can document each method with docstrings and in Sphinx do:

  1. .. autoclass:: package.Casting
  2.   :members:
  3.   .. automethod:: __init__(self, int_converter_function, float_converter_function)

How to do the same with annotations?

UPDATE:

I figured out that my questions should be more specific. I want to

  1. Eliminate dataclass completely from the doc but nevertheless, keep the class in the documentation. It messes classes so much that the docs are unreadable.

  2. Make a docstring on the __init__ but also keep it separate from the callable description. I left a comment.

Example of the doc:

  1. """Cast one type of code to another.
  3. Constructor arguments:
  5.     :param int_converter_function: function to convert to int
  7.     :param float_converter_function: function to convert to float
  9. Callable arguments:
  11. :param casting: :term:`casting` object
  12. :type casting: dict
  14. :param value_to_cast: input value
  16. :return: Casted value
  18. Example
  19.     >>> cast = Casting(int)
  20.     >>> cast({'type': 'integer'}, '123')
  21.     123
  22.     >>> cast({'type': 'decimal'}, '123.12')
  23.     Decimal('123.12')
  25. """

UPDATE 2:

The full class as it is below:

  1. # -*- coding: utf-8 -*-
  3. from attr import dataclass
  4. from typing_extensions import final
  7. @final
  8. @dataclass(frozen=True, slots=True)
  9. class Casting(object):
  10.     """Cast one type of code to another.
  12.     Constructor arguments:
  14.         :param int_converter_function: function to convert to int
  16.         :param float_converter_function: function to convert to float
  18.     Callable arguments:
  20.     :param casting: :term:`casting` object
  21.     :type casting: dict
  23.     :param value_to_cast: input value
  25.     :return: Casted value
  27.     Example
  28.         >>> cast = Casting(int)
  29.         >>> cast({'type': 'integer'}, '123')
  30.         123
  31.         >>> cast({'type': 'decimal'}, '123.12')
  32.         Decimal('123.12')
  34.     """
  36.     _int_converter_function = int
  37.     _float_converter_function = float
  39.     def __call__(self, casting, value_to_cast):
  40.         if casting['type'] == 'integer':
  41.             return self._int_converter_function(value_to_cast)
  42.         return self._float_converter_function(value_to_cast)

如何在Sphinx中记录带有@dataclass注释的可调用类？

I want to eliminate package.casting.dataclass from the doc.

答案1

得分: 2

如 @mzjn 在评论中提到的，如果 automodule 配置正确，:exclude-members: dataclass 应该能够完成任务。

我犯了一个愚蠢的错误，很难追踪。如果你将 :exclude-members: 和 <name-of-module> 写在不同的行上，那么文件中的所有类都将被忽略。

与创建构造函数和可调用函数相关的另一部分看起来很不错，我将其提取到了单独的SO问题中。

英文:

As @mzjn mentioned in comments :exclude-members: dataclass should do the job if automodule configured correctly.

I made a dumb mistake that was hard to track. If you write :exclude-members: and &lt;name-of-module&gt; on the separate lines then all classes in the file will be ignored.

Another part related to make constructor and callable function looks pretty I extracted into separate SO question.

huangapple
  • 本文由 发表于 2020年1月3日 22:43:40
  • 转载请务必保留本文链接：https://go.coder-hub.com/59580517.html
  • callable-object
  • python
  • python-sphinx
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定