==================
pytest-flake8-path
==================
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/pytest-flake8-path/main.yml?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/pytest-flake8-path/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/pytest-flake8-path.svg?style=for-the-badge
:target: https://pypi.org/project/pytest-flake8-path/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
A pytest fixture for testing flake8 plugins.
A quick example:
.. code-block:: python
def test_simple_run(flake8_path):
(flake8_path / "example.py").write_text("x = 1\n")
result = flake8_path.run_flake8()
assert result.out_lines == [
"./example.py:1:2: E221 multiple spaces before operator"
]
Installation
============
Use **pip**:
.. code-block:: sh
python -m pip install pytest-flake8-path
Python 3.8 to 3.12 supported.
----
**Working on a Django project?**
Check out my book `Speed Up Your Django Tests <https://adamchainz.gumroad.com/l/suydt>`__ which covers loads of ways to write faster, more accurate tests.
----
API
===
``flake8_path`` fixture
-----------------------
A pytest fixture that wraps Pytest's built-in ``tmp_path`` fixture
(`docs <https://docs.pytest.org/en/latest/how-to/tmp_path.html>`__), to create
a temporary directory, allow adding files, and running flake8. It acts like a
`pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>`__
object, with one extra method.
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.cfg``
entrypoint, which makes ``tox`` the easiest way to guarantee this is ready as
it will install your project before running tests.
``flake8dir.run_flake8(extra_args: list[str] | None = None) -> Flake8Result``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Runs flake8 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"]``. Note some arguments are already passed to
ensure Flake8 runs in an isolated manner - see source.
``Flake8Result``
----------------
Represents the parsed output of a flake8 run.
``Flake8Result.out: str``
~~~~~~~~~~~~~~~~~~~~~~~~~
The full string of output (stdout) generated by flake8.
``Flake8Result.err: str``
~~~~~~~~~~~~~~~~~~~~~~~~~
The full string of error output (stderr) 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.
On Windows, file paths are normalized into the Unix format (``\`` is replaced
with ``/``). This allows test suites to run the same on all operating systems.
For example, given a result you can check for a particular line being output:
.. code-block:: python
result = flake8_path.run_flake8()
expected = "./example.py:1:2: E221 multiple spaces before operator"
assert expected in result.out_lines
``Flake8Result.err_lines: list[str]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Like ``out_lines``, but for error output.
Examples
========
Basic
-----
Using ``Path.write_text()`` (`docs <https://docs.python.org/3/library/pathlib.html#pathlib.Path.write_text>`__) we can create an ``example.py`` file with code.
Then with ``flake8_path.run_flake8()`` we can run flake8 and check for an expected error:
.. code-block:: python
def test_simple(flake8_path):
(flake8_path / "example.py").write_text("x = 1\n")
result = flake8_path.run_flake8()
assert result.out_lines == [
"./example.py:1:2: E221 multiple spaces before operator"
]
assert result.err_lines == []
assert result.exit_code == 1
With dedent
-----------
The standard library’s ``textwrap.dedent()`` (`docs <https://docs.python.org/3/library/textwrap.html#textwrap.dedent>`__) is useful for including multi-line files.
Use a triple quoted multi-line string, with an initial backslash to prevent a blank first line:
.. code-block:: python
def test_multi_line(flake8_path):
(flake8_path / "example.py").write_text(
dedent(
"""\
x = 1
y = 2
"""
)
)
result = flake8_path.run_flake8()
assert result.out_lines == [
"./example.py:1:2: E221 multiple spaces before operator",
"./example.py:2:2: E221 multiple spaces before operator",
]
assert result.err_lines == []
assert result.exit_code == 1
Configuring flake8
------------------
Write a ``setup.cfg`` file to configure flake8 before running it:
.. code-block:: python
def test_with_setup_cfg(flake8_path):
(flake8_path / "setup.cfg").write_text(
dedent(
"""\
[flake8]
ignore = E221
"""
)
)
(flake8_path / "example.py").write_text("x = 1\n")
result = flake8_path.run_flake8()
assert result.out_lines == []
assert result.err_lines == []
assert result.exit_code == 0
History
=======
pytest-flake8-path is the successor to `pytest-flake8dir <https://pypi.org/project/pytest-flake8dir/>`__.
pytest-flake8dir was based upon pytest’s ``tmpdir`` fixture, which returned a legacy ``py.path.local`` object.
Since version 3.9.0, pytest has provided the ``tmp_path`` fixture, which returns a standard library ``pathlib.Path`` object.
pytest-flake8-path is a rewrite of pytest-flake8dir to use ``tmp_path`` instead of ``tmpdir``.
Raw data
{
"_id": null,
"home_page": "https://github.com/adamchainz/pytest-flake8-path",
"name": "pytest-flake8-path",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "pytest,flake8",
"author": "Adam Johnson",
"author_email": "me@adamj.eu",
"download_url": "https://files.pythonhosted.org/packages/e3/ad/202b5e890310eb7d1c4389949bb8c29dd0b2fbd8a7d34547dc6c3b1e9dad/pytest_flake8_path-1.5.0.tar.gz",
"platform": null,
"description": "==================\npytest-flake8-path\n==================\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/pytest-flake8-path/main.yml?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/pytest-flake8-path/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/pytest-flake8-path.svg?style=for-the-badge\n :target: https://pypi.org/project/pytest-flake8-path/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\nA pytest fixture for testing flake8 plugins.\n\nA quick example:\n\n.. code-block:: python\n\n def test_simple_run(flake8_path):\n (flake8_path / \"example.py\").write_text(\"x = 1\\n\")\n\n result = flake8_path.run_flake8()\n\n assert result.out_lines == [\n \"./example.py:1:2: E221 multiple spaces before operator\"\n ]\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: sh\n\n python -m pip install pytest-flake8-path\n\nPython 3.8 to 3.12 supported.\n\n----\n\n**Working on a Django project?**\nCheck out my book `Speed Up Your Django Tests <https://adamchainz.gumroad.com/l/suydt>`__ which covers loads of ways to write faster, more accurate tests.\n\n----\n\nAPI\n===\n\n``flake8_path`` fixture\n-----------------------\n\nA pytest fixture that wraps Pytest's built-in ``tmp_path`` fixture\n(`docs <https://docs.pytest.org/en/latest/how-to/tmp_path.html>`__), to create\na temporary directory, allow adding files, and running flake8. It acts like a\n`pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>`__\nobject, with one extra method.\n\nIf you're using this to test a flake8 plugin, make sure flake8 is picking up\nyour plugin during tests. Normally this is done with a ``setup.cfg``\nentrypoint, which makes ``tox`` the easiest way to guarantee this is ready as\nit will install your project before running tests.\n\n``flake8dir.run_flake8(extra_args: list[str] | None = None) -> Flake8Result``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nRuns flake8 and returns a ``Flake8Result`` representing the results.\n\n``extra_args`` may be a list of extra flags to pass to flake8, for example\npassing ``[\"--ignore\", \"E101\"]``. Note some arguments are already passed to\nensure Flake8 runs in an isolated manner - see source.\n\n``Flake8Result``\n----------------\n\nRepresents the parsed output of a flake8 run.\n\n``Flake8Result.out: str``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe full string of output (stdout) generated by flake8.\n\n``Flake8Result.err: str``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe full string of error output (stderr) generated by flake8.\n\n``Flake8Result.exit_code: int``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe exit code that the flake8 run exited with.\n\n``Flake8Result.out_lines: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA list of individual lines of output, without trailing newlines.\nThis is the most useful tool for making assertions against.\n\nOn Windows, file paths are normalized into the Unix format (``\\`` is replaced\nwith ``/``). This allows test suites to run the same on all operating systems.\n\nFor example, given a result you can check for a particular line being output:\n\n.. code-block:: python\n\n result = flake8_path.run_flake8()\n expected = \"./example.py:1:2: E221 multiple spaces before operator\"\n assert expected in result.out_lines\n\n``Flake8Result.err_lines: list[str]``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nLike ``out_lines``, but for error output.\n\nExamples\n========\n\nBasic\n-----\n\nUsing ``Path.write_text()`` (`docs <https://docs.python.org/3/library/pathlib.html#pathlib.Path.write_text>`__) we can create an ``example.py`` file with code.\nThen with ``flake8_path.run_flake8()`` we can run flake8 and check for an expected error:\n\n.. code-block:: python\n\n def test_simple(flake8_path):\n (flake8_path / \"example.py\").write_text(\"x = 1\\n\")\n\n result = flake8_path.run_flake8()\n\n assert result.out_lines == [\n \"./example.py:1:2: E221 multiple spaces before operator\"\n ]\n assert result.err_lines == []\n assert result.exit_code == 1\n\nWith dedent\n-----------\n\nThe standard library\u2019s ``textwrap.dedent()`` (`docs <https://docs.python.org/3/library/textwrap.html#textwrap.dedent>`__) is useful for including multi-line files.\nUse a triple quoted multi-line string, with an initial backslash to prevent a blank first line:\n\n.. code-block:: python\n\n def test_multi_line(flake8_path):\n (flake8_path / \"example.py\").write_text(\n dedent(\n \"\"\"\\\n x = 1\n y = 2\n \"\"\"\n )\n )\n\n result = flake8_path.run_flake8()\n\n assert result.out_lines == [\n \"./example.py:1:2: E221 multiple spaces before operator\",\n \"./example.py:2:2: E221 multiple spaces before operator\",\n ]\n assert result.err_lines == []\n assert result.exit_code == 1\n\nConfiguring flake8\n------------------\n\nWrite a ``setup.cfg`` file to configure flake8 before running it:\n\n.. code-block:: python\n\n def test_with_setup_cfg(flake8_path):\n (flake8_path / \"setup.cfg\").write_text(\n dedent(\n \"\"\"\\\n [flake8]\n ignore = E221\n \"\"\"\n )\n )\n (flake8_path / \"example.py\").write_text(\"x = 1\\n\")\n\n result = flake8_path.run_flake8()\n\n assert result.out_lines == []\n assert result.err_lines == []\n assert result.exit_code == 0\n\nHistory\n=======\n\npytest-flake8-path is the successor to `pytest-flake8dir <https://pypi.org/project/pytest-flake8dir/>`__.\npytest-flake8dir was based upon pytest\u2019s ``tmpdir`` fixture, which returned a legacy ``py.path.local`` object.\nSince version 3.9.0, pytest has provided the ``tmp_path`` fixture, which returns a standard library ``pathlib.Path`` object.\npytest-flake8-path is a rewrite of pytest-flake8dir to use ``tmp_path`` instead of ``tmpdir``.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A pytest fixture for testing flake8 plugins.",
"version": "1.5.0",
"project_urls": {
"Changelog": "https://github.com/adamchainz/pytest-flake8-path/blob/main/CHANGELOG.rst",
"Homepage": "https://github.com/adamchainz/pytest-flake8-path",
"Mastodon": "https://fosstodon.org/@adamchainz",
"Twitter": "https://twitter.com/adamchainz"
},
"split_keywords": [
"pytest",
"flake8"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4412ae4ef76c5c36a1e6219b79b21215586d3c34f4a56fce2d2acd7c637383ed",
"md5": "5fbddcdfb62aa74e5c42d59eca67c86e",
"sha256": "8766879344883e67762fc3f4f8f0d624a0d143de71f6488788599b3583e279a9"
},
"downloads": -1,
"filename": "pytest_flake8_path-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5fbddcdfb62aa74e5c42d59eca67c86e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5618,
"upload_time": "2023-07-10T14:50:54",
"upload_time_iso_8601": "2023-07-10T14:50:54.412146Z",
"url": "https://files.pythonhosted.org/packages/44/12/ae4ef76c5c36a1e6219b79b21215586d3c34f4a56fce2d2acd7c637383ed/pytest_flake8_path-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3ad202b5e890310eb7d1c4389949bb8c29dd0b2fbd8a7d34547dc6c3b1e9dad",
"md5": "a62695b4eb0679724b672187a7047e85",
"sha256": "2c144a3127995d34e82df397350dbef7780c9920c5b7e9ebc81f63299011381e"
},
"downloads": -1,
"filename": "pytest_flake8_path-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "a62695b4eb0679724b672187a7047e85",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5840,
"upload_time": "2023-07-10T14:50:56",
"upload_time_iso_8601": "2023-07-10T14:50:56.242635Z",
"url": "https://files.pythonhosted.org/packages/e3/ad/202b5e890310eb7d1c4389949bb8c29dd0b2fbd8a7d34547dc6c3b1e9dad/pytest_flake8_path-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 14:50:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamchainz",
"github_project": "pytest-flake8-path",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pytest-flake8-path"
}
JSON
