Publicity and privacy derived from modules seems wrong

[willfrey]

Based on the current implementation, the module _private.py here is considered public

publicpackage
├── __init__.py
├── _private.py  # D100 for no docstring
└── public.py

since publicpackage is considered public. With the current definition of a private module, it is impossible to have them under any public top-level package namespace. Should this be the case, though?

Furthermore, let's consider a single private module _module.py with the contents

# _module.py
def not_public():  # I get a D103 error.
    pass

The function not_public should not require a docstring because its only parent is private; however, pydocstyle _module.py would still yield a D103 error.

I will note that I can get around this by defining __all__ to be empty, which is more explicit and probably a good practice even inside of a private module. That is, I can change _module.py to contain

# _module.py
__all__ = []  # Export nothing.

def not_public():  # No more D103!
    passs

and I won't get the D103 error anymore. That being said, this still isn't the behavior outlined in the documentation.

It'd be nice to not get yelled at by pydocstyle while I'm working on an idea inside of a private submodule of my public package!

Thank you!

[sigmavirus24]

Out of curiousity, if you run pydocstyle publicpackage does it flag the module/function?

[willfrey]

Yes, it does.

Supposing I have the same directory tree as in my first content with an empty __init__.py, a function public defined in public.py, and a function not_public defined in _private.py, then running pydocstyle publicpackage reports

Given the directory tree from my initial comment and assuming that the contents of publicpackage/public.py and publicpackage/_private.py are respectively

# public.py
def public():
   pass

# _private.py
def not_public():
    pass

then running pydocstyle publicpackage gives me

$ pydocstyle publicpackage
publicpackage/public.py:1 at module level:
        D100: Missing docstring in public module
publicpackage/public.py:1 in public function `public`:
        D103: Missing docstring in public function
publicpackage/__init__.py:1 at module level:
        D104: Missing docstring in public package
publicpackage/_private.py:1 at module level:
        D100: Missing docstring in public module
publicpackage/_private.py:1 in public function `not_public`:
        D103: Missing docstring in public function

[Nurdok]

The public / private determination for modules shouldn't care about packages. What I suspect is happening here is that this Module method:

    def is_public(self):
        return not self.name.startswith('_') or self.name.startswith('__')

gets a fully qualified self.name and thus is affected by the root package where pydocstyle is run. It should only take the module name for the check.

@willfrey, would you like to try this fix yourself and send a PR?

[willfrey]

Sure!

[sqwishy]

gets a fully qualified self.name and thus is affected by the root package where pydocstyle is run

This is the case.

I don't believe there is a pull request for this yet. Is that correct?

On a related note, is there a way to ignore D100: Missing docstring in public module for a specific module (not a command line argument) in the mean time?

[willfrey]

Not yet. I'll be getting to this soon!

…

On Wed, Jul 25, 2018 at 7:33 PM sqwishy ***@***.***> wrote: gets a fully qualified self.name and thus is affected by the root package where pydocstyle is run This is the case. I don't believe there is a pull request for this yet. Is that correct? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#323 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ANJVKWUy2JomqjmJjSY_fMazD2F8QGeqks5uKQBVgaJpZM4Uz9ow> .

-- -Will Frey

[Julian]

For anyone else blocked by this, you might want pydocstyle --match='(?!(test_|_)).*\.py' in the meantime until this is fixed.

(Note that that regex also excludes __init__.pys, but if you're like me and insist those should be empty, you probably are OK with that. If you're not, then you might want pydocstyle --match='(?!(test_|_[^_])).*\.py').