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

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

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,

@final
@dataclass(frozen=True, slots=True)
class Casting(object):
  
  _int_converter_function = int
  _float_converter_function = float

  def __call__(self, casting, value_to_cast):
    if casting['type'] == 'integer':
        return self._int_converter_function(value_to_cast)
    return self._float_converter_function(value_to_cast)

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

class Casting(object):
  
  def __init__(
    self,
    int_converter_function = int,
    float_converter_function = float,
  ):
    self.int_converter_function = int_converter_function
    self.float_converter_function = float_converter_function

  def converter(self, casting, value):
    self.value = value
    yield
    type = casting['type']
    if type == 'integer':
      yield self.int_converter_function(value)
    else:
      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:

.. autoclass:: package.Casting
  :members:
  .. 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:

    """Cast one type of code to another.

    Constructor arguments:

        :param int_converter_function: function to convert to int
 
        :param float_converter_function: function to convert to float

    Callable arguments:

    :param casting: :term:`casting` object
    :type casting: dict

    :param value_to_cast: input value

    :return: Casted value
    
    Example
        >>> cast = Casting(int)
        >>> cast({'type': 'integer'}, '123')
        123
        >>> cast({'type': 'decimal'}, '123.12')
        Decimal('123.12')

    """

UPDATE 2:

The full class as it is below:

    # -*- coding: utf-8 -*-
    
    from attr import dataclass
    from typing_extensions import final
    
    @final
    @dataclass(frozen=True, slots=True)
    class Casting(object):
        """Cast one type of code to another.
    
        Constructor arguments:
    
            :param int_converter_function: function to convert to int
    
            :param float_converter_function: function to convert to float
    
        Callable arguments:
    
        :param casting: :term:`casting` object
        :type casting: dict
    
        :param value_to_cast: input value
    
        :return: Casted value
    
        Example
            >>> cast = Casting(int)
            >>> cast({'type': 'integer'}, '123')
            123
            >>> cast({'type': 'decimal'}, '123.12')
            Decimal('123.12')
    
        """
    
        _int_converter_function = int
        _float_converter_function = float
    
        def __call__(self, casting, value_to_cast):
            if casting['type'] == 'integer':
                return self._int_converter_function(value_to_cast)
            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,

@final
@dataclass(frozen=True, slots=True)
class Casting(object):
  
  _int_converter_function = int
  _float_converter_function = float

  def __call__(self, casting, value_to_cast):
    if casting['type'] == 'integer':
        return self._int_converter_function(value_to_cast)
    return self._float_converter_function(value_to_cast)

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

class Casting(object):
  
  def __init__(
    self,
    int_converter_function = int,
    float_converter_function = float,
  ):
    self.int_converter_function = int_converter_function
    self.float_converter_function = float_converter_function

  def converter(self, casting, value):
    self.value = value
    yield
    type = casting['type']
    if type == 'integer':
      yield self.int_converter_function(value)
    else:
      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:

.. autoclass:: package.Casting
  :members:
  .. 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:

"""Cast one type of code to another.

Constructor arguments:

    :param int_converter_function: function to convert to int

    :param float_converter_function: function to convert to float

Callable arguments:

:param casting: :term:`casting` object
:type casting: dict

:param value_to_cast: input value

:return: Casted value

Example
    >>> cast = Casting(int)
    >>> cast({'type': 'integer'}, '123')
    123
    >>> cast({'type': 'decimal'}, '123.12')
    Decimal('123.12')

"""

UPDATE 2:

The full class as it is below:

# -*- coding: utf-8 -*-

from attr import dataclass
from typing_extensions import final


@final
@dataclass(frozen=True, slots=True)
class Casting(object):
    """Cast one type of code to another.

    Constructor arguments:

        :param int_converter_function: function to convert to int

        :param float_converter_function: function to convert to float

    Callable arguments:

    :param casting: :term:`casting` object
    :type casting: dict

    :param value_to_cast: input value

    :return: Casted value

    Example
        >>> cast = Casting(int)
        >>> cast({'type': 'integer'}, '123')
        123
        >>> cast({'type': 'decimal'}, '123.12')
        Decimal('123.12')

    """

    _int_converter_function = int
    _float_converter_function = float

    def __call__(self, casting, value_to_cast):
        if casting['type'] == 'integer':
            return self._int_converter_function(value_to_cast)
        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
匿名

发表评论

匿名网友

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

确定