Merge pull request #222 from Nurdok/feature/private-modules

Modules starting with a single leading underscore are considered private

Author: Nurdok

docs/error_codes.rst

@@ -16,3 +16,9 @@ check only error codes that are part of the `PEP257
 
 All of the above error codes are checked for by default except for D203,
 D212, D213 and D404.
+
+
+Publicity
+---------
+
+.. include:: snippets/publicity.rst

docs/release_notes.rst

@@ -23,6 +23,9 @@ New Features
 Bug Fixes
 
 * Made parser more robust to bad source files (#168, #214)
+* Modules are now considered private if their name starts with a single
+  underscore. This is a bugfix where "public module" (D100) was reported
+  regardless of module name (#199, #222).
 
 1.1.1 - October 4th, 2016
 -------------------------

docs/snippets/publicity.rst

@@ -0,0 +1,41 @@
+The D1xx group of errors deals with missing docstring in public constructs:
+modules, classes, methods, etc. It is important to note how publicity is
+determined and what its effects are.
+
+
+How publicity is determined
+===========================
+
+Publicity for all constructs is determined as follows: a construct is
+considered *public* if -
+
+1. Its immediate parent is public *and*
+2. Its name does not contain a single leading underscore.
+
+A construct's immediate parent is the construct that contains it. For example,
+a method's parent is a class object. A class' parent is usually a module, but
+might also be a function, method, etc. A module can either have no parent, or
+it can have a parent that is a package.
+
+In order for a construct to be considered public, its immediate parent must
+also be public. Since this definition is recursive, it means that *all* of its
+parents need to be public. The corollary is that if a construct is considered
+private, then all of its descendants are also considered private. For example,
+a class called ``_Foo`` is considered private. A method ``bar`` in ``_Foo`` is
+also considered private since its parent is a private class, even though its
+name does not begin with a single underscore.
+
+
+How publicity affects error reports
+===================================
+
+The immediate effect of a construct being determined as private is that no
+D1xx errors will be reported for it (or its children, as the previous section
+explains). A private method, for instance, will not generate a D102 error, even
+if it has no docstring.
+
+However, it is important to note that while docstring are optional for private
+construct, they are still required to adhere to your style guide. So if a
+private module `_foo.py` does not have a docstring, it will not generate a
+D100 error, but if it *does* have a docstring, that docstring might generate
+other errors.

src/pydocstyle/parser.py

@@ -103,11 +103,14 @@ class Module(Definition):
     _fields = ('name', '_source', 'start', 'end', 'decorators', 'docstring',
                'children', 'parent', '_all', 'future_imports',
                'skipped_error_codes')
-    is_public = True
     _nest = staticmethod(lambda s: {'def': Function, 'class': Class}[s])
     module = property(lambda self: self)
     all = property(lambda self: self._all)
 
+    @property
+    def is_public(self):
+        return not self.name.startswith('_') or self.name.startswith('__')
+
     def __str__(self):
         return 'at module level'
 

src/tests/parser_test.py

@@ -276,3 +276,18 @@ def test_raise_from():
     parser = Parser()
     code = CodeSnippet("raise ValueError() from None")
     parser.parse(code, 'file_path')
+
+
+def test_module_publicity():
+    """Test that a module that has a single leading underscore is private."""
+    parser = Parser()
+    code = CodeSnippet("")
+
+    module = parser.parse(code, "filepath")
+    assert module.is_public
+
+    module = parser.parse(code, "_filepath")
+    assert not module.is_public
+
+    module = parser.parse(code, "__filepath")
+    assert module.is_public