Documentation on plugins should explain why importing them is bad

[mgrazebrook]

Intuitively, I re-used a fixture not by making it a plugin but by importing it from a library I created which is shared by several projects. This creates flake8 error F811 and caused me to read up why this should not be OK. This was not a quick journey and didn't lead to clear answers.

The problem I'm solving: I have a test library which contains a fixture for setting up database test data. It's shared by several projects: this means it can't be defined in a project's conftest.py (other than by copy-paste). The fixture is used to create project-specific fixtures.

This is the same case as nicely documented here:

https://mail.python.org/pipermail/code-quality/2017-May/000901.html

or here:

https://stackoverflow.com/questions/43746413/how-do-i-get-flake8-to-work-with-f811-errors

Importing fixtures like this works. I haven't yet encountered any disadvantage. However after a bit of googling, reading and asking I found that this is not how one's supposed to do this but no explanation of why.

I'd like an update to the documentation here:

https://docs.pytest.org/en/latest/writing_plugins.html

It would be good if search terms such as "reuse pytest fixtures between projects or from a library" took me here.

It would be good if the documentation explained why re-using fixtures by importing from a pip installed library is a bad thing and if it really is a bad thing, perhaps the code should give some sort of warning if they're used that way.

It would be nice if the help text gave a direct answer to 'how do I write a pluging fixture' rather than having to trawl through the linked examples.

[nicoddemus]

Thanks @mgrazebrook for the feedback!

You are completely correct, an explicit section about that topic is missing from our docs. I've opened #7772 that adds that into fixture.html, in a format which I believe fits with the rest of the document. Please take a look and feel free to post any comments in the PR. 👍