D1XX rules don't work when functions are imported into a public file

[AKuederle]

trafficstars

The D1XX rules check if docstrings for public functions/classes exist. However, I think they are missing a common pattern of defining "public objects". Namely, defining them in "private" (aka leading underscore) files and then importing them into a top-level __init__.

# mypackage/__init__.py
from mypackage._methods implement my_function

__all__ = ["my_function"]

# mypackage/_methods.py

def my_function():
   pass

In this case, I would expect ruff to identify my_function as a public function, as it is imported in a public module (and even added to __all__).

[MichaReiser]

Thanks for reporting this common pattern that ruff doesn't support today (to my knowledge)

I'm unfamiliar with the implementation but I assume that this isn't working as expected because Ruff only supports single-file analysis today and your example requires aggregating knowing about the import and __all__ export of my_function in the __init__.py file while lining the _methods.py file.

[AKuederle]

Thus makes sense! And I understand that this would be a considerable effort then to fix this...

I think a potential workaround would be to make it configurable, if files with a leading underscore should lead to all objects inside to be considered non-public. For a project structure like I outlined above, having ruff treat the _methods file "just" like a normal file would make these rules at least usable for these types of setups

On Tue, 5 Sept 2023, 22:45 Micha Reiser, @.***> wrote:

I'm unfamiliar with the implementation but I assume that this isn't working as expected because Ruff only supports single-file analysis today and your example requires aggregating knowing about the import and all export of my_function in the init.py file while lining the _methods.py file.

— Reply to this email directly, view it on GitHub https://github.com/astral-sh/ruff/issues/7154#issuecomment-1707287776, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACSHBOZGJWSFW2MGJXW4EYTXY6FOBANCNFSM6AAAAAA4LY3NGQ . You are receiving this because you authored the thread.Message ID: @.***>

[KRunchPL]

I fully agree with the previous comment. I follow this pattern in many projects.

Moreover, the configuration to disable treating _files as private (and disabling D1XX rules in them) would be not only a workaround. It is not uncommon in bigger projects, requiring docstring for "internally public" entities (not starting with _, but being in _ module or package).

With this flag it would be still pretty easy to disable those rules for specific file(s), while without the support there is currently no way to enable it when needed. Thus it would make the tool much more flexible.