py.test plugin for efficiently checking PEP8 compliance 
========================================================================

Usage
---------

install via::

    pip install pytest-pep8

if you then type::

    py.test --pep8
    
every file ending in ``.py`` will be discovered and pep8-checked, 
starting from the command line arguments. 

.. warning::

    Running pep8 tests on your project is likely to cause a lot of 
    issues.  This plugin allows to configure on a per-project and
    per-file basis which errors or warnings to care about, see
    pep8ignore_.  As a preliminary advise, if you have 
    projects where you don't want to care at all about pep8 checks, 
    you can put configure it like this::

        # content of setup.cfg (or pytest.ini)
        [pytest]
        pep8ignore = * ALL


A little example 
-----------------------

If you have a pep8-violating file like this::

    # content of myfile.py
 
    somefunc( 123,456)

you can run it with the plugin installed::

    $ py.test --pep8
    =========================== test session starts ============================
    platform linux2 -- Python 2.7.3 -- pytest-2.2.5.dev2
    pep8: performing checks
    collecting ... collected 1 items
    
    myfile.py F
    
    ================================= FAILURES =================================
    ________________________________ PEP8-check ________________________________
    /home/hpk/tmp/doc-exec-259/myfile.py:2:10: E201 whitespace after '('
    somefunc( 123,456)
             ^
    /home/hpk/tmp/doc-exec-259/myfile.py:2:14: E231 missing whitespace after ','
    somefunc( 123,456)
                 ^
    
    ========================= 1 failed in 0.01 seconds =========================

For the meaning of (E)rror and (W)arning codes, see the error
output when running against your files or checkout `pep8.py
<https://github.com/jcrocholl/pep8/blob/master/pep8.py>`_.

Let's not now fix the PEP8 errors::

    # content of myfile.py
    somefunc(123, 456)

and run again::

    $ py.test --pep8
    =========================== test session starts ============================
    platform linux2 -- Python 2.7.3 -- pytest-2.2.5.dev2
    pep8: performing checks
    collecting ... collected 1 items
    
    myfile.py .
    
    ========================= 1 passed in 0.01 seconds =========================

the pep8 check now is passing. Moreover, if
you run it once again (and report skip reasons)::

    $ py.test --pep8 -rs 
    =========================== test session starts ============================
    platform linux2 -- Python 2.7.3 -- pytest-2.2.5.dev2
    pep8: performing checks
    collecting ... collected 1 items
    
    myfile.py s
    ========================= short test summary info ==========================
    SKIP [1] /home/hpk/p/pytest-pep8/pytest_pep8.py:63: file(s) previously passed PEP8 checks
    
    ======================== 1 skipped in 0.01 seconds =========================

you can see that the pep8 check was skipped because
the file has not been modified since it was last checked.
As the pep8 plugin uses the 
`pytest-cache plugin <http://pypi.python.org/pypi/pytest-cache>`_
to implement its caching, you can use its ``--clearcache`` option to 
remove all pytest caches, among them the pep8 related one, which 
will trigger the pep8 checking code to run once again::

    $ py.test --pep8 --clearcache
    =========================== test session starts ============================
    platform linux2 -- Python 2.7.3 -- pytest-2.2.5.dev2
    pep8: performing checks
    collecting ... collected 1 items
    
    myfile.py .
    
    ========================= 1 passed in 0.01 seconds =========================

.. _pep8ignore:

Configuring PEP8 options per project and file
---------------------------------------------

You may configure PEP8-checking options for your project
by adding an ``pep8ignore`` entry to your ``setup.cfg``
or ``setup.cfg`` file like this::

    # content of setup.cfg
    [pytest]
    pep8ignore = E201 E231

This would globally prevent complaints about two whitespace issues.
Rerunning with the above example will now look better::

    $ py.test -q  --pep8
    collecting ... collected 1 items
    .
    1 passed in 0.01 seconds

If you have some files where you want to specifically ignore 
some errors or warnings you can start a pep8ignore line with 
a glob-pattern and a space-separated list of codes::

    # content of setup.cfg
    [pytest]
    pep8ignore = 
        *.py E201
        doc/conf.py ALL

So if you have a conf.py like this::

    # content of doc/conf.py

    func (  [1,2,3]) #this line lots pep8 errors :)

then running again with the previous example will show a single
failure and it will ignore doc/conf.py alltogether::

    $ py.test --pep8 -v # verbose shows what is ignored
    =========================== test session starts ============================
    platform linux2 -- Python 2.7.3 -- pytest-2.2.5.dev2 -- /home/hpk/venv/1/bin/python
    pep8: performing checks
    cachedir: /home/hpk/tmp/doc-exec-259/.cache
    collecting ... collected 1 items
    
    myfile.py:0: PEP8-check(ignoring E201) PASSED
    
    ========================= 1 passed in 0.01 seconds =========================

Note that doc/conf.py was not considered or imported.

If you'ld like to have longer lines than 79 chars (which is the default for the
pep8 checker), you can configure it like this::

    # content of setup.cfg
    [pytest]
    pep8maxlinelength = 99

Running PEP8 checks and no other tests
---------------------------------------------

You can also restrict your test run to only perform "pep8" tests
and not any other tests by typing::

    py.test --pep8 -k pep8

This will only run tests that are marked with the "pep8" keyword
which is added for the pep8 test items added by this plugin.

Notes
-------------

The repository of this plugin is at http://bitbucket.org/hpk42/pytest-pep8

For more info on py.test see http://pytest.org

The code is partially based on Ronny Pfannschmidt's pytest-codecheckers plugin.