owned this note
owned this note
Published
Linked with GitHub
Auto-formatters
---------------
Autoformatters are very simple tools to do just a one thing:
reformat some basic stuff in your code like quotes, commas, and line length.
The difference between a linter and auto-formatter is huge:
- auto-formatters pretties your code a little bit
- linters force you to write beautiful and correct code
For example, auto-formatters won't tell you that your code is too complex.
When your linter will (in case it is a good linter).
Autoformatters are also useless
when dealing with rewriting actually bad code.
Like code with bad variable names, unreachable branches,
statements that have no effect.
We in ``wemake.services`` believe that these kind of tools are not required,
because a good linter will just not let your badly formatted code pass the CI,
so there would be no junk to reformat!
All code is perfectly formatted all the time.
Rely on strict linters, not auto-formatters.
However, if you still want to use some autoformatter
together with ``wemake-python-styleguide``
we have made some research to help you!
autopep8
--------
`autopep8 <https://github.com/hhatto/autopep8>`_ is the best choice
for ``wemake-python-styleguide`` users.
Is officially supported in way
that all code written inside ``wemake-python-styleguide`` is tested
to be valid ``autopep8`` code. But, **not the other way around**.
Since ``wemake-python-styleguide`` is the strictest linter
it cannot be pleased by outputs of ``autopep8`` in 100% of cases all by itself.
Most likely, you will need to refactor a little bit more manually (brainly!)
to please ``wemake-python-styleguide`` after ``autopep8`` formatting is done.
There are also plugins for IDEs to run ``autopep8`` on safe:
- https://code.visualstudio.com/docs/python/editing
There's also an awesome tool `pyformat <https://github.com/myint/pyformat>`_
that wraps ``autopep8``,
`autoflake <https://github.com/myint/autoflake>`_,
`docformatter <https://github.com/myint/docformatter>`_,
and `unify <https://github.com/myint/unify>`_.
isort
-----
``isort`` is a great tool to sort your imports.
We already use it to validate that your imports are correct.
We recommend to use ``isort`` and officially
and support it in a way that all
valid ``wemake-python-styleguide`` code is valid ``isort`` code.
But, **not the other way around**.
You might be required to refactor your code manually after ``isort``
reformat to make ``wemake-python-styleguide`` happy.
``isort`` can also `be invoked <https://github.com/timothycrosley/isort#using-isort>`_
as a command line tool to fix all your import problems for you.
We recommend to run ``isort`` after ``autopep8``. They are also compatible.
There are also plugins for IDEs to run ``isort`` on safe:
- https://github.com/timothycrosley/isort/wiki/isort-Plugins
- https://code.visualstudio.com/docs/python/editing
You can find the configuration we use in ``setup.cfg`` in this repository.
add-trailing-comma
------------------
In case you use ``autopep8`` we also recommend
to use `add-trailing-comma <https://github.com/asottile/add-trailing-comma>`_
to format your enumerations, calls, and multiline definitions beautifully.
It is compatible to ``wemake-python-styleguide``.
With ``pyformat``, ``isort``, and ``add-trailing-comma``
you will get more features as in ``black``.
yapf
----
This a very complex autoformatter written by Google.
It has like lots of configuration options!
We were not successful enough to configure it
in a way that our style is respected.
The main problems are with new lines and trailing commas:
sometimes they are added, sometimes removed.
If you have a working configuration
for both ``yapf`` and ``wemake-python-styleguide``,
please, let us know!
black
-----
``wemake-python-styleguide`` is on its way to be made compatible with ``black``.
Let's go deeper and see how.
``black`` itself is by default not compatible with ``PEP8`` and ``flake8``
(`docs <https://black.readthedocs.io/en/stable/the_black_code_style.html?highlight=flake8>`_),
that's why it is not compatible with ``wemake-python-styleguide`` without some modifications.
Here are the violations that ``black`` produces:
- Quotes: ``black`` uses ``"`` that almost no one uses in the ``python`` world
(That will be fixed by `-S` or using the `double-quote-string-fixer`)
- Trailing commas: ``black`` strips trailing commas
and trailing commas as a best-practice are quite popular in ``python`` code
(That will be fixed by https://github.com/psf/black/issues/1288)
- Line length is default to 88 instead of the standard 80.
(The line length can be fixed by uisng the `--line-length=80` function)
This official ``python-org`` product makes community standards hard to follow