Merge pull request #38 from uber/ca/improve_doc

Add documentation about uninstall fixtures

charlatan/fixture.py

@@ -124,7 +124,7 @@ def get_instance(self, path=None, fields=None):
         :param str path: remaining path to return
         :param dict fields: overriding fields
 
-        .. versionremoved:: 0.3.7
+        .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
 
         """

charlatan/fixtures_manager.py

@@ -281,7 +281,7 @@ def install_fixture(self, fixture_key, do_not_save=False, attrs=None):
 
         :rtype: :data:`fixture_instance`
 
-        .. versionremoved:: 0.3.7
+        .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
 
         """
@@ -315,7 +315,7 @@ def install_fixtures(self, fixture_keys, do_not_save=False):
 
         :rtype: list of :data:`fixture_instance`
 
-        .. versionremoved:: 0.3.7
+        .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
 
         """
@@ -332,7 +332,7 @@ def install_all_fixtures(self, do_not_save=False):
 
         :rtype: list of :data:`fixture_instance`
 
-        .. versionremoved:: 0.3.7
+        .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
 
         """
@@ -346,7 +346,7 @@ def uninstall_fixture(self, fixture_key, do_not_delete=False):
         :param bool do_not_delete: True if fixture should not be deleted.
 
         :rtype: :data:`fixture_instance` or None if no instance was uninstalled
-        with the given key
+            with the given key
         """
 
         try:
@@ -411,7 +411,7 @@ def get_fixture(self, fixture_key, attrs=None):
 
         :rtype: instantiated but unsaved fixture
 
-        .. versionremoved:: 0.3.7
+        .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
 
         """
@@ -445,7 +445,7 @@ def get_fixtures(self, fixture_keys):
 
         :rtype: list of instantiated but unsaved fixtures
 
-        .. versionremoved:: 0.3.7
+        .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
 
         """

docs/quickstart.rst

@@ -108,8 +108,6 @@ For a single test
 
         def test_toaster(self):
             self.install_fixture("toaster")
-            # Do things... and optionally uninstall it once you're done
-            self.uninstall_fixture("toaster")
 
 With pytest
 """""""""""
@@ -121,6 +119,9 @@ In ``conftest.py``:
 
 .. code-block:: python
 
+    import pytest
+
+
     @pytest.fixture
     def get_fixture():
         return fixtures_manager.get_fixture
@@ -177,3 +178,20 @@ Here's the general process:
    on the instance. If there's no such method, charlatan will do nothing.
 
 :ref:`hooks` are also supported.
+
+Uninstalling fixtures
+"""""""""""""""""""""
+
+Because charlatan is not coupled with the persistence layer, it does not have
+strong opinions about resetting the world after a test runs. There's multiple
+ways to handle test tear down:
+
+* Wrap test inside a transaction (if you're using sqlalchemy, its documentation
+  has a `good
+  explanation <http://docs.sqlalchemy.org/en/rel_0_9/orm/session_transaction.html#joining-a-session-into-an-external-transaction-such-as-for-test-suites>`_
+  about how to achieve that).
+* Drop and recreate the database (not really efficient).
+* Install and uninstall fixtures explicitly (you have to keep track of them
+  though, if you forget to uninstall one fixture it will leak in the other
+  tests). See
+  :py:meth:`charlatan.FixturesManager.uninstall_fixture`.