From ad4216b75f592766834329e3f587bce9e4cbc1b2 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 11 Sep 2018 13:04:18 +0300 Subject: [PATCH] Version 0.0.11 release --- CHANGELOG.md | 3 ++ README.md | 5 ++- docs/_pages/errors.rst | 16 +++++++- docs/_static/.gitkeep | 0 docs/conf.py | 7 ++++ docs/requirements.txt | 3 -- wemake_python_styleguide/errors/classes.py | 15 ++++--- wemake_python_styleguide/errors/complexity.py | 29 +++++++------ wemake_python_styleguide/errors/general.py | 41 ++++++++++--------- wemake_python_styleguide/errors/imports.py | 16 +++++--- wemake_python_styleguide/errors/modules.py | 6 +++ 11 files changed, 92 insertions(+), 49 deletions(-) create mode 100644 docs/_static/.gitkeep diff --git a/CHANGELOG.md b/CHANGELOG.md index 7956b6b1a..df1b99319 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ There are no new features introduced. - Introduced the concept of regression testing, see `test/fixtures/regression` - Removed `compat.py` +- Fixes some minor typos, problems, markup inside the docs +- Adds some new configuration to `sphinx` +- Changes `sphinx` docs structure a little bit ## Version 0.0.10 aka The Module Reaper diff --git a/README.md b/README.md index 4175e6eac..717839d9c 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,10 @@ Welcome to the most opinionated linter ever. `wemake-python-styleguide` is actually just a `flake8` plugin. -The main goal of this tool is to make our `python` code consistent. +The main goal of this tool is to make our `python` code +consistent and to fight the code complexity. -``` +```text The Zen of Python, by Tim Peters Beautiful is better than ugly. diff --git a/docs/_pages/errors.rst b/docs/_pages/errors.rst index 0b98ea69f..56e7908ce 100644 --- a/docs/_pages/errors.rst +++ b/docs/_pages/errors.rst @@ -1,20 +1,32 @@ Errors ------ -.. automodule:: wemake_python_styleguide.errors.base - :members: +General +~~~~~~~ .. automodule:: wemake_python_styleguide.errors.general :members: +Imports +~~~~~~~ + .. automodule:: wemake_python_styleguide.errors.imports :members: +Classes +~~~~~~~ + .. automodule:: wemake_python_styleguide.errors.classes :members: +Complexity +~~~~~~~~~~ + .. automodule:: wemake_python_styleguide.errors.complexity :members: +Modules +~~~~~~~ + .. automodule:: wemake_python_styleguide.errors.modules :members: diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/conf.py b/docs/conf.py index 533fe7792..20847499b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,6 +57,11 @@ autodoc_member_order = 'bysource' +autodoc_mock_imports = [ + 'flake8', + 'typing_extensions', +] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -177,6 +182,8 @@ # -- Extension configuration ------------------------------------------------- +napoleon_numpy_docstring = False + # -- Options for todo extension ---------------------------------------------- # If true, `todo` and `todoList` produce output, else they produce nothing. diff --git a/docs/requirements.txt b/docs/requirements.txt index 006de6b88..8c3249a53 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -6,6 +6,3 @@ sphinxcontrib-napoleon==0.6.1 sphinx_autodoc_typehints==1.3.0 recommonmark==0.4.0 m2r==0.1.15 - -# In app dependecies (required due to RtD does not support poetry): -flake8>=3.5,<3.6 diff --git a/wemake_python_styleguide/errors/classes.py b/wemake_python_styleguide/errors/classes.py index 861dffb4e..689b94588 100644 --- a/wemake_python_styleguide/errors/classes.py +++ b/wemake_python_styleguide/errors/classes.py @@ -1,12 +1,15 @@ # -*- coding: utf-8 -*- """ -These rules checks that ``class``es are defined correctly. +These rules checks that ``class`` definitions are correct. + +Note: + + Beautiful is better than ugly. + Explicit is better than implicit. + In the face of ambiguity, refuse the temptation to guess. + There should be one-- and preferably only one --obvious way to do it. -Beautiful is better than ugly. -Explicit is better than implicit. -In the face of ambiguity, refuse the temptation to guess. -There should be one-- and preferably only one --obvious way to do it. """ from wemake_python_styleguide.errors.base import ASTStyleViolation @@ -16,7 +19,7 @@ class StaticMethodViolation(ASTStyleViolation): """ This rule forbids to use ``@staticmethod`` decorator. - Use regular methods, ``classmethods``, or raw functions instead. + Use regular methods, ``classmethods`` or raw functions instead. Note: Returns Z300 as error code diff --git a/wemake_python_styleguide/errors/complexity.py b/wemake_python_styleguide/errors/complexity.py index e7369a768..bc4438620 100644 --- a/wemake_python_styleguide/errors/complexity.py +++ b/wemake_python_styleguide/errors/complexity.py @@ -8,9 +8,12 @@ 1. Complex code (there are a lof of complexity checks!) 2. Nested classes, functions -Simple is better than complex. -Complex is better than complicated. -Flat is better than nested. +Note: + + Simple is better than complex. + Complex is better than complicated. + Flat is better than nested. + """ from wemake_python_styleguide.errors.base import ASTStyleViolation @@ -24,7 +27,7 @@ class NestedFunctionViolation(ASTStyleViolation): However, there are some whitelisted names like, see ``NESTED_FUNCTIONS_WHITELIST`` for the whole list. - We also disallow to nest ``lambda``s. + We also disallow to nest ``lambda``. Example:: @@ -94,10 +97,10 @@ def second_function(argument): In this example we will count as locals only several variables: - 1. `first_var`, because it is assigned inside the function's body - 2. `second_var`, because it is assigned inside the function's body - 3. `argument`, because it is reassigned inside the function's body - 4. `third_var`, because it is assigned inside the function's body + 1. ``first_var``, because it is assigned inside the function's body + 2. ``second_var``, because it is assigned inside the function's body + 3. ``argument``, because it is reassigned inside the function's body + 4. ``third_var``, because it is assigned inside the function's body Please, note that `_` is a special case. It is not counted as a local variable. Since by design it means: do not count me as a real variable. @@ -117,7 +120,7 @@ class TooManyArgumentsViolation(ASTStyleViolation): """ This rule forbids to have too many arguments for a function or method. - This is an indecator of a bad desing. + This is an indicator of a bad desing. When function requires many arguments it shows that it is required to refactor this piece of code. @@ -134,10 +137,12 @@ class TooManyArgumentsViolation(ASTStyleViolation): class TooManyElifsViolation(ASTStyleViolation): """ - This rule forbids to use many `elif` branches. + This rule forbids to use many ``elif`` branches. - This rule is specifically important, becase many `elif` branches indicate - a complex flow in your design: you are reimplementing `switch` in python. + This rule is specifically important, + because many ``elif`` branches indicate + a complex flow in your design: + you are reimplementing ``switch`` in python. There are different design patters to use instead. diff --git a/wemake_python_styleguide/errors/general.py b/wemake_python_styleguide/errors/general.py index 05166d80b..f0517b2b1 100644 --- a/wemake_python_styleguide/errors/general.py +++ b/wemake_python_styleguide/errors/general.py @@ -1,19 +1,22 @@ # -*- coding: utf-8 -*- """ -These rules checks some general rules. +These rules check some general issues. Like: -1. Naming -2. Using some builtins -3. Using keywords -4. Working with exceptions +1. Incorrect naming +2. Using wrong builtins +3. Using wrong keywords +4. Working with exceptions "the bad way" + +Note: + + Beautiful is better than ugly. + Explicit is better than implicit. + In the face of ambiguity, refuse the temptation to guess. + There should be one-- and preferably only one --obvious way to do it. -Beautiful is better than ugly. -Explicit is better than implicit. -In the face of ambiguity, refuse the temptation to guess. -There should be one-- and preferably only one --obvious way to do it. """ from wemake_python_styleguide.errors.base import ASTStyleViolation @@ -44,7 +47,7 @@ class WrongKeywordViolation(ASTStyleViolation): class BareRiseViolation(ASTStyleViolation): """ - This rule forbids using bare `raise` keyword outside of `except` block. + This rule forbids using bare ``raise`` keyword outside of ``except`` block. This may be a serious error in your application, so we should prevent that. @@ -68,10 +71,10 @@ class BareRiseViolation(ASTStyleViolation): class RaiseNotImplementedViolation(ASTStyleViolation): """ - This rule forbids to use `NotImplemented` error. + This rule forbids to use ``NotImplemented`` error. These two errors have different use cases. - Use cases of `NotImplemented` is too limited to be generally available. + Use cases of ``NotImplemented`` is too limited to be generally available. Example:: @@ -206,11 +209,11 @@ class WrongModuleMetadataViolation(ASTStyleViolation): class FormattedStringViolation(ASTStyleViolation): """ - This rule forbids to use `f` strings. + This rule forbids to use ``f`` strings. - `f` strings looses context to often, they are hard to lint. - Also, they promote a bad practice: putting a logic into the template. - Use `.format()` instead. + ``f`` strings looses context too often and they are hard to lint. + Also, they promote a bad practice: putting your logic inside the template. + Use ``.format()`` instead. Example:: @@ -251,15 +254,15 @@ class EmptyModuleViolation(ASTStyleViolation): class InitModuleHasLogicViolation(ASTStyleViolation): """ - This rule forbids to have logic inside `__init__` module. + This rule forbids to have logic inside ``__init__`` module. - If you have logic inside the `__init__` module it means several things: + If you have logic inside the ``__init__`` module it means several things: 1. you are keeping some outdated stuff there, you need to refactor 2. you are placing this logic into the wrong file, just create another one 3. you are doing some dark magic, and you should not do that - However, we allow to have some contents inside the `__init__` module: + However, we allow to have some contents inside the ``__init__`` module: 1. comments, since they are dropped before AST comes in play 2. docs string, because sometimes it is required to state something diff --git a/wemake_python_styleguide/errors/imports.py b/wemake_python_styleguide/errors/imports.py index 0757cf621..49eb3ef00 100644 --- a/wemake_python_styleguide/errors/imports.py +++ b/wemake_python_styleguide/errors/imports.py @@ -1,12 +1,15 @@ # -*- coding: utf-8 -*- """ -These rules checks ``import``s to be defined correctly. +These rules checks ``import`` statements to be defined correctly. + +Note: + + Explicit is better than implicit. + Flat is better than nested. + Sparse is better than dense. + Readability counts. -Explicit is better than implicit. -Flat is better than nested. -Sparse is better than dense. -Readability counts. """ from wemake_python_styleguide.errors.base import ASTStyleViolation @@ -114,6 +117,9 @@ class SameAliasImportViolation(ASTStyleViolation): """ This rule forbids to use the same alias as the original name in imports. + Why would you even do this in the first place? + However, sometimes we see this error in the real code. + Example:: # Correct: diff --git a/wemake_python_styleguide/errors/modules.py b/wemake_python_styleguide/errors/modules.py index f3aa53376..dd281e236 100644 --- a/wemake_python_styleguide/errors/modules.py +++ b/wemake_python_styleguide/errors/modules.py @@ -4,6 +4,12 @@ These rules checks that modules are defined correctly. Please, take a note that these rules are not applied to packages. + +Things we check here: + +1. Naming +2. Contents: some modules must have contents, some must not + """ from wemake_python_styleguide.errors.base import SimpleStyleViolation