[py-dev] RFC for (hopefully) final commments on pytest-2.3 API

[holger krekel]

Hi Brianna, Floris, Carl, Ronny, all,

first, let me thank for all the useful feedback you already provided.
I am back trying to finalize the next pytest release -- FYI trunk is actually
fully functional and implements all previously discussed features.

However, I am still pondering Brianna's feedback (that that she found it
surprising that there is a @pytest.setup but no teardown) and a few
other little naming and protocol issues.  If you find some time to state
your opinion on one or another issue i'd very much appreciate it:

- rename @pytest.setup to @pytest.fixture and the docs would talk 
  about fixture instead of setup functions. (See 
  http://pytest.org/dev/setup.html for the current docs)
  This would induce less of a question about @pytest.teardown?!

- rename @pytest.factory to @pytest.funcarg - because with pytest-trunk
  it's already the case that the former pytest_funcarg__NAME is just
  a shortcut - there is no internal distinction anymore if you use 
  the decorator or the prefix or both.  Removing the "pytest_funcarg__" prefix
  and using a @pytest.funcarg(...) declaration looks naturally related?!

- introduce a "resource-centric" convenience protocol for fixtures and 
  funcarg factories.  It would be used if you decorate a class instead of 
  a function and would lead to the calling of (optional) setup/teardown
  methods. Here is an example:

    # content of test_module.py

    import pytest

    @pytest.funcarg
    class db:
        def setup(self, funcarg1, funcarg2):
            # called during the setup phase of each test using the "db"
            # funcarg.  this setup function will be called multiple
            # times in case db.params is defined

        def teardown(self):
            # called during the teardown phase of a test which
            # previously saw a successful db.setup() call

- moreover, there could optionally be a class-method "configure" which is
  called ahead of any setup() and would allow to dynamically compute the scope 
  and params attribute and influence them e. g. from command line options::

    @pytest.funcarg
    class db:
        @classmethod
        def configure(cls, config):
            scope = config.option.scope
            params = ...

        ...

  Dynamic scoping/parametrization is used today if you want to have 
  broadly-scoped less-parametrized resources during development but 
  use more function-scope more-parametrized resources during CI runs.


- the same class convenience protocol would work for fixtures:

    import pytest
    @pytest.fixture
    class transact:
        def setup(self, db):
            db.begin()
            self.db = db
        def teardown(self):
            self.db.commit()

best,
holger