Merge pull request #76 from stephenfin/readme-improvements

README tweaks

2 files changed, 198 insertions, 142 deletions

diff --git a/README.rst b/README.rst
index b07af06..1bc0e96 100644
--- a/README.rst
+++ b/README.rst
@@ -1,26 +1,12 @@
-*************************************************************
-fixtures: Fixtures with cleanups for testing and convenience.
-*************************************************************
+************************************************************
+fixtures: Fixtures with cleanups for testing and convenience
+************************************************************
 
-  Copyright (c) 2010, Robert Collins <robertc@robertcollins.net>
-
-  Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
-  license at the users choice. A copy of both licenses are available in the
-  project source as Apache-2.0 and BSD. You may not use this file except in
-  compliance with one of these two licences.
-
-  Unless required by applicable law or agreed to in writing, software
-  distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
-  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
-  license you chose for the specific language governing permissions and
-  limitations under that license.
-
-
-Fixtures defines a Python contract for reusable state / support logic,
+*fixtures* defines a Python contract for reusable state / support logic,
 primarily for unit testing. Helper and adaption logic is included to make it
 easy to write your own fixtures using the fixtures contract. Glue code is
-provided that makes using fixtures that meet the Fixtures contract in unittest
-compatible test cases easy and straight forward.
+provided that makes using fixtures that meet the ``Fixtures`` contract in
+``unittest`` compatible test cases easy and straight forward.
 
 Dependencies
 ============
@@ -28,48 +14,45 @@ Dependencies
 * Python 3.7+
   This is the base language fixtures is written in and for.
 
-* pbr
+* ``pbr``
   Used for version and release management of fixtures.
 
 The ``fixtures[streams]`` extra adds:
 
-* testtools <https://launchpad.net/testtools> 0.9.22 or newer.
-  testtools provides helpful glue functions for the details API used to report
+* ``testtools`` <https://launchpad.net/testtools>
+
+  ``testtools`` provides helpful glue functions for the details API used to report
   information about a fixture (whether its used in a testing or production
   environment).
 
-For use in a unit test suite using the included glue, one of:
+For use in a unit test suite using the included glue, you will need a test
+environment that supports ``TestCase.addCleanup``. Writing your own glue code
+is easy. Alternatively, you can simply use Fixtures directly without any
+support code.
 
-* bzrlib.tests
-
-* Or any other test environment that supports TestCase.addCleanup.
-
-Writing your own glue code is easy, or you can simply use Fixtures directly
-without any support code.
-
-To run the test suite for fixtures, testtools is needed.
+To run the test suite for fixtures, ``testtools`` is needed.
 
 Why Fixtures
 ============
 
-Standard Python unittest.py provides no obvious method for making and reusing
+Standard Python ``unittest`` provides no obvious method for making and reusing
 state needed in a test case other than by adding a method on the test class.
 This scales poorly - complex helper functions propagating up a test class
-hierarchy is a regular pattern when this is done. Mocking while a great tool
+hierarchy is a regular pattern when this is done. Mocking, while a great tool,
 doesn't itself prevent this (and helpers to mock complex things can accumulate
 in the same way if placed on the test class).
 
 By defining a uniform contract where helpers have no dependency on the test
 class we permit all the regular code hygiene activities to take place without
 the distorting influence of being in a class hierarchy that is modelling an
-entirely different thing - which is what helpers on a TestCase suffer from.
+entirely different thing - which is what helpers on a ``TestCase`` suffer from.
 
 About Fixtures
 ==============
 
-A Fixture represents some state. Each fixture has attributes on it that are
+A fixture represents some state. Each fixture has attributes on it that are
 specific to the fixture. For instance, a fixture representing a directory that
-can be used for temporary files might have a attribute 'path'.
+can be used for temporary files might have a attribute ``path``.
 
 Most fixtures have complete ``pydoc`` documentation, so be sure to check
 ``pydoc fixtures`` for usage information.
@@ -77,8 +60,8 @@ Most fixtures have complete ``pydoc`` documentation, so be sure to check
 Creating Fixtures
 =================
 
-Minimally, subclass Fixture, define _setUp to initialize your state and schedule
-a cleanup for when cleanUp is called and you're done::
+Minimally, subclass ``Fixture``, define ``_setUp`` to initialize your state,
+schedule a cleanup for when ``cleanUp`` is called, and you're done::
 
   >>> import unittest
   >>> import fixtures
@@ -87,14 +70,15 @@ a cleanup for when cleanUp is called and you're done::
   ...         self.frobnozzle = 42
   ...         self.addCleanup(delattr, self, 'frobnozzle')
 
-This will initialize frobnozzle when ``setUp`` is called, and when ``cleanUp``
-is called get rid of the frobnozzle attribute. Prior to version 1.3.0 fixtures
-recommended overriding ``setUp``. This is still supported, but since it is
-harder to write leak-free fixtures in this fashion, it is not recommended.
+This will initialize ``frobnozzle`` when ``setUp`` is called, and when
+``cleanUp`` is called get rid of the ``frobnozzle`` attribute. Prior to version
+1.3.0 *fixtures* recommended overriding ``setUp``. This is still supported, but
+since it is harder to write leak-free fixtures in this fashion, it is not
+recommended.
 
 If your fixture has diagnostic data - for instance the log file of an
-application server, or log messages, it can expose that by creating a content
-object (``testtools.content.Content``) and calling ``addDetail``.
+application server, or log messages - it can expose that by creating a content
+object (``testtools.content.Content``) and calling ``addDetail``::
 
   >>> from testtools.content import text_content
   >>> class WithLog(fixtures.Fixture):
@@ -103,14 +87,14 @@ object (``testtools.content.Content``) and calling ``addDetail``.
 
 The method ``useFixture`` will use another fixture, call ``setUp`` on it, call
 ``self.addCleanup(thefixture.cleanUp)``, attach any details from it and return
-the fixture. This allows simple composition of different fixtures.
+the fixture. This allows simple composition of different fixtures::
 
   >>> class ReusingFixture(fixtures.Fixture):
   ...     def _setUp(self):
   ...         self.noddy = self.useFixture(NoddyFixture())
 
-There is a helper for adapting a function or function pair into Fixtures. it
-puts the result of the function in fn_result::
+There is a helper for adapting a function or function pair into Fixtures. It
+puts the result of the function in ``fn_result``::
 
   >>> import os.path
   >>> import shutil
@@ -125,7 +109,7 @@ puts the result of the function in fn_result::
   True
   >>> fixture.cleanUp()
 
-This can be expressed even more pithily:
+This can be expressed even more pithily::
 
   >>> fixture = fixtures.FunctionFixture(tempfile.mkdtemp, shutil.rmtree)
   >>> fixture.setUp()
@@ -133,7 +117,7 @@ This can be expressed even more pithily:
   True
   >>> fixture.cleanUp()
 
-Another variation is MethodFixture which is useful for adapting alternate
+Another variation is ``MethodFixture`` which is useful for adapting alternate
 fixture implementations to Fixture::
 
   >>> class MyServer:
@@ -155,8 +139,8 @@ You can also combine existing fixtures using ``CompoundFixture``::
 The Fixture API
 ===============
 
-The example above introduces some of the Fixture API. In order to be able to
-clean up after a fixture has been used, all fixtures define a ``cleanUp``
+The example above introduces some of the ``Fixture`` API. In order to be able
+to clean up after a fixture has been used, all fixtures define a ``cleanUp``
 method which should be called when a fixture is finished with.
 
 Because it's nice to be able to build a particular set of related fixtures in
@@ -164,25 +148,25 @@ advance of using them, fixtures also have a ``setUp`` method which should be
 called before trying to use them.
 
 One common desire with fixtures that are expensive to create is to reuse them
-in many test cases; to support this the base Fixture also defines a ``reset``
-which calls ``self.cleanUp(); self.setUp()``. Fixtures that can more
+in many test cases; to support this the base ``Fixture`` also defines a
+``reset`` which calls ``self.cleanUp(); self.setUp()``. Fixtures that can more
 efficiently make themselves reusable should override this method. This can then
 be used with multiple test state via things like ``testresources``,
 ``setUpClass``, or ``setUpModule``.
 
-When using a fixture with a test you can manually call the setUp and cleanUp
-methods. More convenient though is to use the included glue from
-``fixtures.TestWithFixtures`` which provides a mixin defining
-``useFixture`` (camel case because unittest is camel case throughout) method.
-It will call setUp on the fixture, call self.addCleanup(fixture) to schedule a
+When using a fixture with a test you can manually call the ``setUp`` and
+``cleanUp`` methods. More convenient though is to use the included glue from
+``fixtures.TestWithFixtures`` which provides a mixin defining ``useFixture``
+(camel case because ``unittest`` is camel case throughout) method. It will call
+``setUp`` on the fixture, call ``self.addCleanup(fixture)`` to schedule a
 cleanup, and return the fixture. This lets one write::
 
   >>> import testtools
   >>> import unittest
 
-Note that we use ``testtools.TestCase``. testtools has it's own implementation
-of ``useFixture`` so there is no need to use ``fixtures.TestWithFixtures`` with
-``testtools.TestCase``.
+Note that we use ``testtools.TestCase``. ``testtools`` has it's own
+implementation of ``useFixture`` so there is no need to use
+``fixtures.TestWithFixtures`` with ``testtools.TestCase``::
 
   >>> class NoddyTest(testtools.TestCase, fixtures.TestWithFixtures):
   ...     def test_example(self):
@@ -200,8 +184,8 @@ context manager::
   ...    print (os.path.isdir(fixture.fn_result))
   True
 
-When multiple cleanups error, fixture.cleanUp() will raise a wrapper exception
-rather than choosing an arbitrary single exception to raise::
+When multiple cleanups error, ``fixture.cleanUp()`` will raise a wrapper
+exception rather than choosing an arbitrary single exception to raise::
 
   >>> import sys
   >>> from fixtures.fixture import MultipleExceptions
@@ -220,8 +204,8 @@ rather than choosing an arbitrary single exception to raise::
 
 Fixtures often expose diagnostic details that can be useful for tracking down
 issues. The ``getDetails`` method will return a dict of all the attached
-details, but can only be called before ``cleanUp`` is called. Each detail
-object is an instance of ``testtools.content.Content``.
+details but can only be called before ``cleanUp`` is called. Each detail
+object is an instance of ``testtools.content.Content``::
 
   >>> with WithLog() as l:
   ...     print(l.getDetails()['message'].as_text())
@@ -233,7 +217,7 @@ Errors in setUp
 The examples above used ``_setUp`` rather than ``setUp`` because the base
 class implementation of ``setUp`` acts to reduce the chance of leaking
 external resources if an error is raised from ``_setUp``. Specifically,
-``setUp`` contains a try:/except: block which catches all exceptions, captures
+``setUp`` contains a try/except block which catches all exceptions, captures
 any registered detail objects, and calls ``self.cleanUp`` before propagating
 the error. As long as you take care to register any cleanups before calling
 the code that may fail, this will cause them to be cleaned up. The captured
@@ -242,9 +226,9 @@ detail objects are provided to the args of the raised exception.
 If the error that occurred was a subclass of ``Exception`` then ``setUp`` will
 raise ``MultipleExceptions`` with the last element being a ``SetupError`` that
 contains the detail objects. Otherwise, to prevent causing normally
-uncatchable errors like KeyboardInterrupt being caught inappropriately in the
-calling layer, the original exception will be raised as-is and no diagnostic
-data other than that from the original exception will be available.
+uncatchable errors like ``KeyboardInterrupt`` being caught inappropriately in
+the calling layer, the original exception will be raised as-is and no
+diagnostic data other than that from the original exception will be available.
 
 Shared Dependencies
 +++++++++++++++++++
@@ -298,7 +282,7 @@ a signal of some sort for each user of a fixture before it is reset. In the
 example here, ``TempDir`` might offer a subscribers attribute that both the
 DB and web server would be registered in. Calling ``reset`` or ``cleanUp``
 on the tempdir would trigger a callback to all the subscribers; the DB and
-web server reset methods would look something like:
+web server reset methods would look something like::
 
   >>> def reset(self):
   ...     if not self._cleaned:
@@ -308,7 +292,7 @@ web server reset methods would look something like:
 was needed and set ``self._cleaned``.) This approach has the (perhaps)
 surprising effect that resetting the webserver may reset the DB - if the
 webserver were to be depending on ``tempdir.reset`` as a way to reset the
-webservers state.
+webserver's state.
 
 Another approach which is not currently implemented is to provide an object
 graph of dependencies and a reset mechanism that can traverse that, along with
@@ -320,17 +304,19 @@ tempdir would be reset, and finally the DB and webserver would have
 Stock Fixtures
 ==============
 
-In addition to the Fixture, FunctionFixture and MethodFixture classes fixtures
-includes a number of precanned fixtures. The API docs for fixtures will list
-the complete set of these, should the dcs be out of date or not to hand. For
-the complete feature set of each fixture please see the API docs.
+In addition to the ``Fixture``, ``FunctionFixture`` and ``MethodFixture``
+classes, fixtures includes a number of pre-canned fixtures. The API docs for
+fixtures will list the complete set of these, should the docs be out of date or
+not to hand. For the complete feature set of each fixture please see the API
+docs.
 
-ByteStream
-++++++++++
+``ByteStream``
+++++++++++++++
 
-Trivial adapter to make a BytesIO (though it may in future auto-spill to disk
-for large content) and expose that as a detail object, for automatic inclusion
-in test failure descriptions. Very useful in combination with MonkeyPatch.
+Trivial adapter to make a ``BytesIO`` (though it may in future auto-spill to
+disk for large content) and expose that as a detail object, for automatic
+inclusion in test failure descriptions. Very useful in combination with
+``MonkeyPatch``::
 
   >>> fixture = fixtures.StringStream('my-content')
   >>> fixture.setUp()
@@ -340,35 +326,46 @@ in test failure descriptions. Very useful in combination with MonkeyPatch.
 
 This requires the ``fixtures[streams]`` extra.
 
-EnvironmentVariable
-+++++++++++++++++++
+``EnvironmentVariable``
++++++++++++++++++++++++
 
 Isolate your code from environmental variables, delete them or set them to a
-new value.
+new value::
 
   >>> fixture = fixtures.EnvironmentVariable('HOME')
 
-FakeLogger
-++++++++++
+``FakeLogger``
+++++++++++++++
 
 Isolate your code from an external logging configuration - so that your test
-gets the output from logged messages, but they don't go to e.g. the console.
+gets the output from logged messages, but they don't go to e.g. the console::
 
   >>> fixture = fixtures.FakeLogger()
 
-FakePopen
-+++++++++
+``FakePopen``
++++++++++++++
 
 Pretend to run an external command rather than needing it to be present to run
-tests.
+tests::
 
   >>> from io import BytesIO
   >>> fixture = fixtures.FakePopen(lambda _:{'stdout': BytesIO('foobar')})
 
-MockPatchObject
-+++++++++++++++
+``LogHandler``
+++++++++++++++
+
+Replace or extend a logger's handlers. The behavior of this fixture depends on
+the value of the ``nuke_handlers`` parameter: if ``true``, the logger's
+existing handlers are removed and replaced by the provided handler, while if
+``false`` the logger's set of handlers is extended by the provided handler::
+
+  >>> from logging import StreamHandler
+  >>> fixture = fixtures.LogHandler(StreamHandler())
 
-Adapts ``mock.patch.object`` to be used as a Fixture.
+``MockPatchObject``
++++++++++++++++++++
+
+Adapts ``mock.patch.object`` to be used as a fixture::
 
   >>> class Fred:
   ...     value = 1
@@ -379,24 +376,24 @@ Adapts ``mock.patch.object`` to be used as a Fixture.
   >>> Fred().value
   1
 
-MockPatch
-+++++++++
+``MockPatch``
++++++++++++++
 
-Adapts ``mock.patch`` to be used as a Fixture.
+Adapts ``mock.patch`` to be used as a fixture::
 
   >>> fixture = fixtures.MockPatch('subprocess.Popen.returncode', 3)
 
-MockPatchMultiple
-+++++++++++++++++
+``MockPatchMultiple``
++++++++++++++++++++++
 
-Adapts ``mock.patch.multiple`` to be used as a Fixture.
+Adapts ``mock.patch.multiple`` to be used as a ``fixture``::
 
   >>> fixture = fixtures.MockPatchMultiple('subprocess.Popen', returncode=3)
 
-MonkeyPatch
-+++++++++++
+``MonkeyPatch``
++++++++++++++++
 
-Control the value of a named Python attribute.
+Control the value of a named Python attribute::
 
   >>> def fake_open(path, mode):
   ...     pass
@@ -405,48 +402,60 @@ Control the value of a named Python attribute.
 Note that there are some complexities when patching methods - please see the
 API documentation for details.
 
-NestedTempfile
-++++++++++++++
+``NestedTempfile``
+++++++++++++++++++
 
-Change the default directory that the tempfile module places temporary files
-and directories in. This can be useful for containing the noise created by
-code which doesn't clean up its temporary files. This does not affect
-temporary file creation where an explicit containing directory was provided.
+Change the default directory that the ``tempfile`` module places temporary
+files and directories in. This can be useful for containing the noise created
+by code which doesn't clean up its temporary files. This does not affect
+temporary file creation where an explicit containing directory was provided::
 
   >>> fixture = fixtures.NestedTempfile()
 
-PackagePathEntry
-++++++++++++++++
+``PackagePathEntry``
+++++++++++++++++++++
 
 Adds a single directory to the path for an existing Python package. This adds
-to the package.__path__ list. If the directory is already in the path, nothing
-happens, if it isn't then it is added on setUp and removed on cleanUp.
+to the ``package.__path__`` list. If the directory is already in the path,
+nothing happens, if it isn't then it is added on ``setUp`` and removed on
+``cleanUp``::
 
   >>> fixture = fixtures.PackagePathEntry('package/name', '/foo/bar')
 
-PythonPackage
-+++++++++++++
+``PythonPackage``
++++++++++++++++++
 
 Creates a python package directory. Particularly useful for testing code that
 dynamically loads packages/modules, or for mocking out the command line entry
-points to Python programs.
+points to Python programs::
 
   >>> fixture = fixtures.PythonPackage('foo.bar', [('quux.py', '')])
 
-PythonPathEntry
-+++++++++++++++
+``PythonPathEntry``
++++++++++++++++++++
 
-Adds a single directory to sys.path. If the directory is already in the path,
-nothing happens, if it isn't then it is added on setUp and removed on cleanUp.
+Adds a single directory to ``sys.path``. If the directory is already in the
+path, nothing happens, if it isn't then it is added on ``setUp`` and removed on
+``cleanUp``::
 
   >>> fixture = fixtures.PythonPathEntry('/foo/bar')
 
-StringStream
-++++++++++++
+``Stream``
+++++++++++
+
+Trivial adapter to expose a file-like object as a detail object, for automatic
+inclusion in test failure descriptions. ``StringStream`` and ``BytesStream``
+provided concrete users of this fixture.
+
+This requires the ``fixtures[streams]`` extra.
+
+``StringStream``
+++++++++++++++++
 
-Trivial adapter to make a StringIO (though it may in future auto-spill to disk
-for large content) and expose that as a detail object, for automatic inclusion
-in test failure descriptions. Very useful in combination with MonkeyPatch.
+Trivial adapter to make a ``StringIO`` (though it may in future auto-spill to
+disk for large content) and expose that as a detail object, for automatic
+inclusion in test failure descriptions. Very useful in combination with
+``MonkeyPatch``::
 
   >>> fixture = fixtures.StringStream('stdout')
   >>> fixture.setUp()
@@ -456,49 +465,95 @@ in test failure descriptions. Very useful in combination with MonkeyPatch.
 
 This requires the ``fixtures[streams]`` extra.
 
-TempDir
-+++++++
+``TempDir``
++++++++++++
 
-Create a temporary directory and clean it up later.
+Create a temporary directory and clean it up later::
 
   >>> fixture = fixtures.TempDir()
 
 The created directory is stored in the ``path`` attribute of the fixture after
-setUp.
+``setUp``.
 
-TempHomeDir
-+++++++++++
+``TempHomeDir``
++++++++++++++++
 
-Create a temporary directory and set it as $HOME in the environment.
+Create a temporary directory and set it as ``$HOME`` in the environment::
 
   >>> fixture = fixtures.TempHomeDir()
 
 The created directory is stored in the ``path`` attribute of the fixture after
-setUp.
+``setUp``.
 
-The environment will now have $HOME set to the same path, and the value
-will be returned to its previous value after tearDown.
+The environment will now have ``$HOME`` set to the same path, and the value
+will be returned to its previous value after ``tearDown``.
 
-Timeout
-+++++++
+``Timeout``
++++++++++++
 
 Aborts if the covered code takes more than a specified number of whole wall-clock
 seconds.
 
-There are two possibilities, controlled by the 'gentle' argument: when gentle,
+There are two possibilities, controlled by the ``gentle`` argument: when gentle,
 an exception will be raised and the test (or other covered code) will fail.
 When not gentle, the entire process will be terminated, which is less clean,
 but more likely to break hangs where no Python code is running.
 
-*Caution:* Only one timeout can be active at any time across all threads in a
-single process.  Using more than one has undefined results.  (This could be
-improved by chaining alarms.)
+> *Caution*
+> Only one timeout can be active at any time across all threads in a single
+> process.  Using more than one has undefined results.  (This could be improved
+> by chaining alarms.)
+
+> *Note*
+> Currently supported only on Unix because it relies on the ``alarm`` system
+> call.
+
+``WarningsCapture``
++++++++++++++++++++
+
+Capture warnings for later analysis::
+
+  >>> fixture = fixtures.WarningsCapture()
 
-*Note:* Currently supported only on Unix because it relies on the ``alarm``
-system call.
+The captured warnings are stored in the ``captures`` attribute of the fixture
+after ``setUp``.
+
+``WarningsFilter``
+++++++++++++++++++
+
+Configure warnings filters during test runs::
+
+  >>> fixture = fixtures.WarningsFilter(
+  ...     [
+  ...         {
+  ...             'action': 'ignore',
+  ...             'message': 'foo',
+  ...             'category': DeprecationWarning,
+  ...         },
+  ...     ]
+  ... )
+
+Order is important: entries closer to the front of the list override entries
+later in the list, if both match a particular warning.
 
 Contributing
 ============
 
 Fixtures has its project homepage on GitHub
 <https://github.com/testing-cabal/fixtures>.
+
+License
+=======
+
+  Copyright (c) 2010, Robert Collins <robertc@robertcollins.net>
+
+  Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
+  license at the users choice. A copy of both licenses are available in the
+  project source as Apache-2.0 and BSD. You may not use this file except in
+  compliance with one of these two licences.
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
+  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+  license you chose for the specific language governing permissions and
+  limitations under that license.
diff --git a/setup.cfg b/setup.cfg
index a16e500..0c12754 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -20,6 +20,7 @@ classifiers =
     Programming Language :: Python :: 3.8
     Programming Language :: Python :: 3.9
     Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
     Programming Language :: Python :: Implementation :: CPython
     Programming Language :: Python :: Implementation :: PyPy
     Topic :: Software Development :: Quality Assurance