8

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)

Example of docs

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

6
  • I'm not sure what the problem is, but have you seen this question? stackoverflow.com/q/51125415/407651 Commented Jan 4, 2020 at 11:33
  • @mzjn I updated the question, so it reflects more accurately the issue I have. Commented Jan 6, 2020 at 14:45
  • @mzjn Indeed, you are right. I adjusted the code, so it would be more understandable and less abstract as well. Commented Jan 6, 2020 at 15:23
  • @mzjn I did 2nd update, hopefully, it will clear things and it makes sense for you. Commented Jan 8, 2020 at 8:57
  • 1
    When using automodule, I can reproduce the problem with getting "dataclass" documentation in the output. This can be fixed by using :exclude-members: dataclass. Commented Jan 10, 2020 at 15:05

1 Answer 1

3

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 <name-of-module> 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.

Sign up to request clarification or add additional context in comments.

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.