Incorrect handling of cvar, ivar and vartype tags in sphynx-style

[pedropaulofb]

I would like to use cvar, ivar and vartype of the sphyx docstring syntax, however, docformatter is incorrectly handling them.

Expected:

    """Abstract base class representing a generic element within an OntoUML model.

    :ivar id: A unique identifier for the element, automatically generated upon instantiation.
    :vartype id: str
    :ivar created: Timestamp when the element was created, defaults to the current time.
    :vartype created: datetime
    :ivar modified: Timestamp when the element was last modified, can be None if not modified.
    :vartype modified: Optional[datetime]
    :ivar in_project: List of projects this element is part of. Direct modification is restricted.
    :vartype in_project: list[Project]
    """

Result:

    """Abstract base class representing a generic element within an OntoUML model.

    :ivar id: A unique identifier for the element, automatically generated upon instantiation. :vartype id: str :ivar
    created: Timestamp when the element was created, defaults to the current time. :vartype created: datetime :ivar
    modified: Timestamp when the element was last modified, can be None if not modified. :vartype modified:
    Optional[datetime] :ivar in_project: List of projects this element is part of. Direct modification is restricted.
    :vartype in_project: list[Project]
    """

Is there a workaround to solve this issue?

[electric-coder]

@pedropaulofb notice the warning in the Sphinx docs about the info field lists, for reference:

Note

In current release, all var, ivar and cvar are represented as “Variable”. There is no difference at all.

docformatter should be formatting the fields correctly.

[pedropaulofb]

@electric-coder, thank you for your answer and interest in helping me. As you can see in the examples I sent, at least to me this is not happening. Am I missing any config or is there something else I can try?

[electric-coder]

@pedropaulofb I'm using docformatter version 1.7.2 (check your version with docformatter --version).

I'm also using standard configurations to wrap in accordance with the python-black code style, so in my pyproject.toml I have:

[tool.docformatter]
black = true
wrap-descriptions = 88
wrap-summaries = 88

For me docformatter is wrapping the lines correctly, after I run it on your example I get:

def my_method(a, b):
    """Abstract base class representing a generic element within an OntoUML model.

    :ivar id: A unique identifier for the element, automatically generated upon
        instantiation.
    :vartype id: str
    :ivar created: Timestamp when the element was created, defaults to the current time.
    :vartype created: datetime
    :ivar modified: Timestamp when the element was last modified, can be None if not
        modified.
    :vartype modified: Optional[datetime]
    :ivar in_project: List of projects this element is part of. Direct modification is
        restricted.
    :vartype in_project: list[Project]
    """
    some_text = 1

So this result is correct. I think there was a bug in a previous docformatter version that's been resolved and might cause the problems you are describing, try updating to a more recent version or setting the .toml configs... Your example docstring also wasn't inserted in a class or function, so you should put it inside a correct pythonic scope.

[pedropaulofb]

Dear @electric-coder , thank you for your help! I have the following pyproject.toml configuration:

[tool.docformatter]
black = true
wrap-descriptions = 120
wrap-summaries = 120

My tests were performed in this file.

Indeed, when I used version 1.7.2, I got the expected results. When using version 1.7.5 the results were the ones I reported (i.e., the wrong ones). So I also tested versions 1.7.3 (got correct results) and 1.7.4 (got wrong results). Hence, we can conclude that it is a bug introduced in versions >= 1.7.4.

Could you please reproduce the test yourself?

[electric-coder]

@pedropaulofb I'm not a docformatter maintainer, just a user. I'm sure your tests are correct so I'll excuse myself from the extra work of installing an additional venv to reproduce them.

I think this issue is likely the same as #264

[pedropaulofb]

@electric-coder , It was not a problem! Thank you very much!

[finswimmer]

Hey,

this change seems to have introduce the problem described here and #264:

• https://github.com/PyCQA/docformatter/pull/254

The obvious solution would be to add all other fields mentioned in https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists to the regex. But is also the "correct" or most elegant one :thinking:

[finswimmer]

Ok, I gave it a try: https://github.com/PyCQA/docformatter/pull/295