Metadata-Version: 2.1
Name: pytest-flake8dir
Version: 2.2.0
Summary: A pytest fixture for testing flake8 plugins.
Home-page: https://github.com/adamchainz/pytest-flake8dir
Author: Adam Johnson
Author-email: me@adamj.eu
License: ISC License
Project-URL: Changelog, https://github.com/adamchainz/pytest-flake8dir/blob/master/HISTORY.rst
Keywords: pytest,flake8
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
Requires-Dist: flake8
Requires-Dist: pytest

================
pytest-flake8dir
================

.. image:: https://img.shields.io/travis/adamchainz/pytest-flake8dir/master.svg
        :target: https://travis-ci.org/adamchainz/pytest-flake8dir

.. image:: https://img.shields.io/pypi/v/pytest-flake8dir.svg
        :target: https://pypi.python.org/pypi/pytest-flake8dir

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/python/black

A pytest fixture for testing flake8 plugins.

A quick example:

.. code-block:: python

    def test_simple_run(flake8dir):
        flake8dir.make_example_py('''
            x  = 1
        ''')
        result = flake8dir.run_flake8()
        assert result.out_lines == [
            './example.py:1:2: E221 multiple spaces before operator'
        ]

Installation
============

Use **pip**:

.. code-block:: sh

    pip install pytest-flake8dir

Python 3.5 to 3.8 supported.

API
===

``flake8dir`` fixture
---------------------

A pytest fixture that wraps Pytest's built-in ``tmpdir`` fixture
(`docs <https://docs.pytest.org/en/latest/tmpdir.html>`_), to create a
temporary directory, allow adding files, and running flake8.

If you're using this to test a flake8 plugin, make sure flake8 is picking up
your plugin during tests. Normally this is done with a ``setup.py`` entrypoint,
which makes ``tox`` the easiest way to guarantee this is ready as it will run
``setup.py install`` on your project before running tests.

``flake8dir.make_py_files(**kwargs: Mapping[str, str])``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates one python file for each passed keyword argument, with name
corresponding to the keyword argument + '.py', and content according the string
value of the argument. The value will be processed with ``textwrap.dedent()``
so mixed indentation is not a problem in your test files.

For example, this creates two python files in the temporary directory, called
``example1.py`` and ``example2.py``, each containing one line with an
assignment:

.. code-block:: python

    def test_sample(flake8dir):
        flake8dir.make_py_files(
            example1='''
                x = 1
            ''',
            example2='''
                y = 1
            '''
        )

``flake8dir.make_example_py(content: str)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A shortcut for ``make_py_files(example=content)``, for when you are using a
single file over and over. This creates just ``example.py``, which is often
all you need for testing a rule.

For example:

.. code-block:: python

    def test_sample(flake8dir):
        flake8dir.make_example_py('''
            x = 1
        ''')

``flake8dir.make_setup_cfg(contents: str)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Makes the file ``setup.cfg`` in the test directory with contents equal to the
string passed in. This is again processed with ``textwrap.dedent()`` so
indentation is not a worry. You'll probably want to set the ``[flake8]``
section header to configure flake8.

For example, this makes flake8 ignore rule E101:

.. code-block:: python

    def test_sample(flake8dir):
        flake8dir.make_setup_cfg('''
            [flake8]
            ignore = E101
        ''')

``flake8dir.make_file(filename: str, content: str)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Make an arbitrary file with the given filename - this function is the inner
implementation for ``make_py_files`` and ``make_setup_cfg``. ``filename`` may
include directories, like ``mydir/foo.py``, and they will be created.
``content`` is subject to the same ``textwrap.dedent()`` processing as
mentioned above.

For example:

.. code-block:: python

    def test_sample(flake8dir):
        flake8dir.make_file('myfile/foo.py', '''
            x = 1
        ''')

``flake8dir.run_flake8(extra_args: List[str]=None) -> Flake8Result``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Runs flake8 in the current process, and returns a ``Flake8Result`` representing
the results.

``extra_args`` may be a list of extra flags to pass to flake8, for example
passing ``['--ignore', 'E101']`` would achieve the same thing as the above
``setup.cfg`` example. Note some arguments are already passed to ensure it runs
in the same process without multiprocessing - see source.


``Flake8Result``
----------------

Represents the parsed output of a flake8 run.

``Flake8Result.out: str``
~~~~~~~~~~~~~~~~~~~~~~~~~

The full string of output generated by flake8.

``Flake8Result.exit_code: int``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The exit code that the flake8 run exited with.

``Flake8Result.out_lines: List[str]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A list of individual lines of output, without trailing newlines. This is the
most useful tool for making assertions against.

For example, given a result you can check for a particular line being output:

.. code-block:: python

    result = flake8dir.run_flake8()
    expected = './example.py:1:2: E221 multiple spaces before operator'
    assert expected in result.out_lines

.. _tmpdir: https://docs.pytest.org/en/latest/tmpdir.html

.. :changelog:

History
=======

2.2.0 (2019-12-19)
------------------

* Update Python support to 3.5-3.8, as 3.4 has reached its end of life.
* Converted setuptools metadata to configuration file. This meant removing the
  ``__version__`` attribute from the package. If you want to inspect the
  installed version, use
  ``importlib.metadata.version("pytest-flake8dir")``
  (`docs <https://docs.python.org/3.8/library/importlib.metadata.html#distribution-versions>`__ /
  `backport <https://pypi.org/project/importlib-metadata/>`__).

2.1.0 (2019-04-13)
------------------

* Run ``flake8`` in a ``subprocess`` rather than trying to get a speed boost by
  running it in the current process. This is to overcome plugin state not
  resetting in-process in ``flake8`` 3.7.0+.

2.0.0 (2019-02-28)
------------------

* Drop Python 2 support, only Python 3.4+ is supported now.

1.3.0 (2018-10-16)
------------------

* A temporary ``setup.cfg`` file is now always created with no options and
  passed as ``--config``, to avoid flake8 merging in user-specific settings.
  Use ``make_setup_cfg`` to set the contents of this file.

1.2.0 (2018-02-25)
------------------

* The exit code from ``flake8`` is now saved on the ``Flake8Result`` object.
  Any tests that relied on catching ``SystemExit`` themselves will need
  refactoring to use the new attribute for their assertions.

1.1.0 (2017-06-23)
------------------

* Add convenience methods ``make_example_py`` and ``make_file``.

1.0.0 (2017-06-22)
------------------

* First version with basic fixture supporting ``make_py_files``,
  ``make_setup_cfg`` and ``run_flake8``.


