Internal Docs¶
Here you can find:
How our development process works
How to contribute to the project
How to write new rules
How our internal API looks like
This information will also be helpful
if you would like to create your own flake8
plugin.
How to read this documentation¶
You will need to start from the glossary where we define the terms for this project.
Then move to the contributing guide where we specify all technical details about our workflow and tools.
Then you will be ready to dive into our “Creating a new rule tutorial”.
And finally you will need to go through the API reference to cover specific technical questions you will encounter.
Philosophy¶
Done is better than perfect
However, we pursue perfect software
False negatives over false positives
If you cannot sustain your promise - do not promise
Code must be written for people to read, and only incidentally for machines to execute
Value consistency over syntax-ish readability
Consistent code is more readable than inconsistent
Do not force people to choose, they will make mistakes
Made choices must be respected
Overview¶
This schema should give you a brief overview of what is happening inside our linter. This is a very simplified architecture that will help you to understand how all components are bound together.
Architecture overview.¶
High-level overview of our codebase:
We use a layered architecture that follows this contract:
[importlinter]
root_package = wemake_python_styleguide
include_external_packages = True
[importlinter:contract:layers]
name = Layered architecture of our linter
type = layers
containers =
wemake_python_styleguide
layers =
checker
formatter
transformations
presets
visitors
violations
logic
compat
options
constants
types
# TODO: provide independence contract for visitors
[importlinter:contract:violation-independence]
name = Independence contract for violations (all shall be free!)
type = independence
modules =
wemake_python_styleguide.violations.system
wemake_python_styleguide.violations.naming
wemake_python_styleguide.violations.complexity
wemake_python_styleguide.violations.consistency
wemake_python_styleguide.violations.best_practices
wemake_python_styleguide.violations.refactoring
wemake_python_styleguide.violations.oop
[importlinter:contract:flake8-independence]
name = Independence contract for flake8 API (all shall be free!)
type = independence
modules =
wemake_python_styleguide.checker
wemake_python_styleguide.formatter
[importlinter:contract:api-restrictions]
name = Forbids to import anything from dependencies
type = forbidden
source_modules =
wemake_python_styleguide
forbidden_modules =
# Std imports we don't like:
dataclasses
# Important direct and indirect dependencies:
flake8
flake8_quotes
pygments
pyflakes
isort
bandit
eradicate
pydocstyle
pycodestyle
mccabe
astor
astboom
tokelor
ignore_imports =
# These modules must import from flake8 to provide required API:
wemake_python_styleguide.checker -> flake8
wemake_python_styleguide.formatter -> flake8
wemake_python_styleguide.options.config -> flake8
# We disallow direct imports of our dependencies from anywhere, except:
wemake_python_styleguide.formatter -> pygments
wemake_python_styleguide.logic.source -> astor
wemake_python_styleguide.logic.tokens.strings -> flake8_quotes
[importlinter:contract:subapi-restrictions]
name = Forbids to import anything from our sub-API packages
type = forbidden
source_modules =
wemake_python_styleguide.visitors
wemake_python_styleguide.violations
wemake_python_styleguide.compat
wemake_python_styleguide.logic
forbidden_modules =
# Our sub-API parts:
wemake_python_styleguide.options
wemake_python_styleguide.transformations
wemake_python_styleguide.presets
[importlinter:contract:tests-restrictions]
name = Explicit import restrictions for tests
type = forbidden
source_modules =
wemake_python_styleguide
forbidden_modules =
tests
Contributing¶
This section will help you to know all the tools and terms we are using.
Creating a new rule¶
This tutorial will guide you through the whole process of creating new rules for this linter.
API Reference¶
Raw technical information with interface and types declarations, featuring architecture and composition of classes.