Added support for enforcing multiple, but consistent name styles for different name types inside a single module.

2 files changed, 129 insertions, 0 deletions

diff --git a/doc/index.rst b/doc/index.rst
index bc6f9d8..7b8725c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -13,6 +13,7 @@ https://bitbucket.org/logilab/pylint
    output
    message-control
    features
+   options
    extend
    ide-integration
    plugins
diff --git a/doc/options.rst b/doc/options.rst
new file mode 100644
index 0000000..ec17fb0
--- /dev/null
+++ b/doc/options.rst
@@ -0,0 +1,128 @@
+.. -*- coding: utf-8 -*-
+
+===============
+ Configuration 
+===============
+
+Naming Styles
+-------------
+
+PyLint recognizes a number of different name types internally. With a few
+exceptions, the type of the name is governed by the location the assignment to a
+name is found in, and not the type of object assigned.
+
+``module``
+   Module and package names, same as the file names.
+``const``
+   Module-level constants, any variable defined at module level that is not bound to a class object.
+``class``
+   Names in ``class`` statements, as well as names bound to class objects at module level.
+``function``
+   Functions, toplevel or nested in functions or methods.
+``method``
+   Methods, functions defined in class bodies. Includes static and class methods.
+``attr``
+   Attributes created on class instances inside methods.
+``argument``
+   Arguments to any function type, including lambdas.
+``variable``
+   Local variables in function scopes.
+``class-attribute``
+   Attributes defined in class bodies.
+``inlinevar``
+   Loop variables in list comprehensions and generator expressions.
+
+For each naming style, a separate regular expression matching valid names of
+this type can be defined. By default, the regular expressions will enforce PEP8
+names.
+
+Regular expressions for the names are anchored at the beginning, any anchor for
+the end must be supplied explicitly. Any name not matching the regular
+expression will lead to an instance of ``invalid-name``.
+
+
+.. option:: --module-rgx=<regex>
+
+   Default value: ``[a-z_][a-z0-9_]{2,30}$``
+
+.. option:: --const-rgx=<regex>
+
+   Default value: ``[a-z_][a-z0-9_]{2,30}$``
+
+.. option:: --class-rgx=<regex>
+
+   Default value: ``'[A-Z_][a-zA-Z0-9]+$``
+
+.. option:: --function-rgx=<regex>
+
+   Default value: ``[a-z_][a-z0-9_]{2,30}$``
+
+.. option:: --method-rgx=<regex>
+
+   Default value: ``[a-z_][a-z0-9_]{2,30}$``
+
+.. option:: --attr-rgx=<regex>
+
+   Default value: ``[a-z_][a-z0-9_]{2,30}$``
+
+.. option:: --argument-rgx=<regex>
+
+   Default value: ``[a-z_][a-z0-9_]{2,30}$``
+
+.. option:: --variable-rgx=<regex>
+
+   Default value: ``[a-z_][a-z0-9_]{2,30}$``
+
+.. option:: --class-attribute-rgx=<regex>
+
+   Default value: ``([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$``
+
+.. option:: --inlinevar-rgx=<regex>
+
+   Default value: ``[A-Za-z_][A-Za-z0-9_]*$``
+
+Multiple Naming Styles
+^^^^^^^^^^^^^^^^^^^^^^
+
+Large code bases that have been worked on for multiple years often exhibit an
+evolution in style as well. In some cases, modules can be in the same package,
+but still have different naming style based on the stratum they belong to.
+However, intra-module consistency should still be required, to make changes
+inside a single file easier. For this case, PyLint supports regular expression
+with several named capturing group. 
+
+The capturing group of the first valid match taints the module and enforces the
+same group to be triggered on every subsequent occurrence of this name.
+
+Consider the following (simplified) example::
+
+   pylint --function-rgx='(?:(?P<snake>[a-z_]+)|(?P<camel>_?[A-Z]+))$' sample.py
+
+The regular expression defines two naming styles, ``snake`` for snake-case
+names, and ``camel`` for camel-case names.
+
+In ``sample.py``, the function name on line 1 will taint the module and enforce
+the match of named group ``snake`` for the remainder of the module::
+
+   def trigger_snake_case(arg):
+      ...
+
+   def InvalidCamelCase(arg):
+      ...
+
+   def valid_snake_case(arg):
+    ...
+
+Because of this, the name on line 4 will trigger an ``invalid-name`` warning,
+even though the name matches the given regex.
+
+Matches named ``exempt`` or ``ignore`` can be used for non-tainting names, to
+prevent built-in or interface-dictated names to trigger certain naming styles.
+
+.. option:: --name-group=<name1:name2:...,...>
+
+   Default value: empty
+
+   Format: comma-separated groups of colon-separated names.
+
+   This option can be used to combine name styles. For example, ``function:method`` enforces that functions and methods use the same style, and a style triggered by either name type carries over to the other. This requires that the regular expression for the combined name types use the same group names.