Merge pull request #4346 from tybug/deprecate-abstract-db

Deprecate `ExampleDatabase()`

Author: Zac-HD

hypothesis-python/RELEASE.rst

@@ -0,0 +1,7 @@
+RELEASE_TYPE: patch
+
+This patch deprecates creating a database using the abstract ``ExampleDatabase()`` class. Use one of the following instead:
+
+* Replace ``ExampleDatabase(":memory:")`` with |InMemoryExampleDatabase|.
+* Replace ``ExampleDatabase("/path/to/dir")`` with |DirectoryBasedExampleDatabase|.
+* Replace ``ExampleDatabase()`` with either |InMemoryExampleDatabase| or |DirectoryBasedExampleDatabase|, depending on your needs. Previously, Hypothesis interpreted ``ExampleDatabase()`` as a |DirectoryBasedExampleDatabase| in the default ``.hypothesis`` directory, with a fallback to |InMemoryExampleDatabase| if that location was not available.

hypothesis-python/docs/conf.py

@@ -250,12 +250,14 @@ def setup(app):
 
 .. |@reproduce_failure| replace:: :func:`@reproduce_failure <hypothesis.reproduce_failure>`
 
-.. |RedisExampleDatabase| replace:: :class:`~hypothesis.extra.redis.RedisExampleDatabase`
+.. |ExampleDatabase| replace:: :class:`~hypothesis.database.ExampleDatabase`
+.. |DirectoryBasedExampleDatabase| replace:: :class:`~hypothesis.database.DirectoryBasedExampleDatabase`
 .. |InMemoryExampleDatabase| replace:: :class:`~hypothesis.database.InMemoryExampleDatabase`
 .. |ReadOnlyDatabase| replace:: :class:`~hypothesis.database.ReadOnlyDatabase`
 .. |MultiplexedDatabase| replace:: :class:`~hypothesis.database.MultiplexedDatabase`
 .. |GitHubArtifactDatabase| replace:: :class:`~hypothesis.database.GitHubArtifactDatabase`
 .. |BackgroundWriteDatabase| replace:: :class:`~hypothesis.database.BackgroundWriteDatabase`
+.. |RedisExampleDatabase| replace:: :class:`~hypothesis.extra.redis.RedisExampleDatabase`
 
 .. |str| replace:: :obj:`python:str`
 .. |int| replace:: :obj:`python:int`

hypothesis-python/src/hypothesis/_settings.py

@@ -73,9 +73,9 @@ def __get__(self, obj, type=None):
                 # you can change the storage directory and it will be reflected
                 # in the default database.
                 if self.name == "database" and result is not_set:
-                    from hypothesis.database import ExampleDatabase
+                    from hypothesis.database import _db_for_path
 
-                    result = ExampleDatabase(not_set)
+                    result = _db_for_path(not_set)
                 assert result is not not_set
                 return result
             except KeyError:
@@ -440,8 +440,7 @@ def _validate_database(db: "ExampleDatabase") -> "ExampleDatabase":
         return db
     raise InvalidArgument(
         "Arguments to the database setting must be None or an instance of "
-        f"ExampleDatabase.  Try passing database=ExampleDatabase({db!r}), or "
-        "construct and use one of the specific subclasses in "
+        "ExampleDatabase. Try using one of the specific subclasses in "
         "hypothesis.database"
     )
 

hypothesis-python/src/hypothesis/database.py

@@ -38,6 +38,7 @@
 from urllib.request import Request, urlopen
 from zipfile import BadZipFile, ZipFile
 
+from hypothesis._settings import note_deprecation
 from hypothesis.configuration import storage_directory
 from hypothesis.errors import HypothesisException, HypothesisWarning
 from hypothesis.internal.conjecture.choice import ChoiceT
@@ -112,6 +113,15 @@ def _db_for_path(
 class _EDMeta(abc.ABCMeta):
     def __call__(self, *args: Any, **kwargs: Any) -> "ExampleDatabase":
         if self is ExampleDatabase:
+            note_deprecation(
+                "Creating a database using the abstract ExampleDatabase() class "
+                "is deprecated. Prefer using a concrete subclass, like "
+                "InMemoryExampleDatabase() or DirectoryBasedExampleDatabase(path). "
+                'In particular, the special string ExampleDatabase(":memory:") '
+                "should be replaced by InMemoryExampleDatabase().",
+                since="RELEASEDAY",
+                has_codemod=False,
+            )
             return _db_for_path(*args, **kwargs)
         return super().__call__(*args, **kwargs)
 

hypothesis-python/tests/conjecture/test_engine.py

@@ -26,7 +26,6 @@
     strategies as st,
 )
 from hypothesis.database import (
-    ExampleDatabase,
     InMemoryExampleDatabase,
     choices_from_bytes,
     choices_to_bytes,
@@ -85,7 +84,7 @@ def nodes(data):
 
 def test_can_load_data_from_a_corpus():
     key = b"hi there"
-    db = ExampleDatabase()
+    db = InMemoryExampleDatabase()
     value = b"=\xc3\xe4l\x81\xe1\xc2H\xc9\xfb\x1a\xb6bM\xa8\x7f"
     db.save(key, choices_to_bytes([value]))
 
@@ -223,7 +222,7 @@ def f(data):
 def test_stops_after_max_examples_when_reading():
     key = b"key"
 
-    db = ExampleDatabase(":memory:")
+    db = InMemoryExampleDatabase()
     for i in range(10):
         db.save(key, bytes([i]))
 

hypothesis-python/tests/cover/test_database_backend.py

@@ -39,12 +39,13 @@
     InMemoryExampleDatabase,
     MultiplexedDatabase,
     ReadOnlyDatabase,
+    _db_for_path,
     _pack_uleb128,
     _unpack_uleb128,
     choices_from_bytes,
     choices_to_bytes,
 )
-from hypothesis.errors import HypothesisWarning
+from hypothesis.errors import HypothesisDeprecationWarning, HypothesisWarning
 from hypothesis.internal.compat import WINDOWS
 from hypothesis.internal.conjecture.choice import choice_equal
 from hypothesis.stateful import (
@@ -58,7 +59,7 @@
 from hypothesis.strategies import binary, lists, tuples
 from hypothesis.utils.conventions import not_set
 
-from tests.common.utils import skipif_emscripten
+from tests.common.utils import checks_deprecated_behaviour, skipif_emscripten
 from tests.conjecture.common import ir, nodes
 
 
@@ -86,13 +87,15 @@ def test_can_delete_keys():
 
 
 def test_default_database_is_in_memory():
-    assert isinstance(ExampleDatabase(), InMemoryExampleDatabase)
+    with pytest.warns(HypothesisDeprecationWarning):
+        assert isinstance(ExampleDatabase(), InMemoryExampleDatabase)
 
 
 def test_default_on_disk_database_is_dir(tmp_path):
-    assert isinstance(
-        ExampleDatabase(tmp_path.joinpath("foo")), DirectoryBasedExampleDatabase
-    )
+    with pytest.warns(HypothesisDeprecationWarning):
+        assert isinstance(
+            ExampleDatabase(tmp_path.joinpath("foo")), DirectoryBasedExampleDatabase
+        )
 
 
 def test_does_not_error_when_fetching_when_not_exist(tmp_path):
@@ -103,7 +106,7 @@ def test_does_not_error_when_fetching_when_not_exist(tmp_path):
 @pytest.fixture(scope="function", params=["memory", "directory"])
 def exampledatabase(request, tmp_path):
     if request.param == "memory":
-        return ExampleDatabase()
+        return InMemoryExampleDatabase()
     assert request.param == "directory"
     return DirectoryBasedExampleDatabase(tmp_path / "examples")
 
@@ -468,7 +471,7 @@ def test_database_directory_inaccessible(dirs, tmp_path, monkeypatch):
         if WINDOWS
         else pytest.warns(HypothesisWarning, match=".*the default location is unusable")
     ):
-        database = ExampleDatabase(not_set)
+        database = _db_for_path(not_set)
     database.save(b"fizz", b"buzz")
 
 
@@ -784,3 +787,18 @@ def listener2(event):
 
     db.clear_listeners()
     assert db.ends == 1
+
+
+@checks_deprecated_behaviour
+def test_deprecated_example_database_path(tmp_path):
+    ExampleDatabase(tmp_path)
+
+
+@checks_deprecated_behaviour
+def test_deprecated_example_database_memory():
+    ExampleDatabase(":memory:")
+
+
+@checks_deprecated_behaviour
+def test_deprecated_example_database_no_args():
+    ExampleDatabase()

hypothesis-python/tests/cover/test_settings.py

@@ -26,7 +26,7 @@
     note_deprecation,
     settings,
 )
-from hypothesis.database import ExampleDatabase, InMemoryExampleDatabase
+from hypothesis.database import InMemoryExampleDatabase
 from hypothesis.errors import (
     HypothesisDeprecationWarning,
     InvalidArgument,
@@ -107,7 +107,7 @@ def test_can_not_set_verbosity_to_non_verbosity():
         settings(verbosity="kittens")
 
 
-@pytest.mark.parametrize("db", [None, ExampleDatabase()])
+@pytest.mark.parametrize("db", [None, InMemoryExampleDatabase()])
 def test_inherits_an_empty_database(db):
     with local_settings(settings(database=InMemoryExampleDatabase())):
         assert settings.default.database is not None
@@ -118,7 +118,7 @@ def test_inherits_an_empty_database(db):
         assert t.database is db
 
 
-@pytest.mark.parametrize("db", [None, ExampleDatabase()])
+@pytest.mark.parametrize("db", [None, InMemoryExampleDatabase()])
 def test_can_assign_database(db):
     x = settings(database=db)
     assert x.database is db
@@ -195,7 +195,7 @@ def test_can_have_none_database():
     assert settings(database=None).database is None
 
 
-@pytest.mark.parametrize("db", [None, ExampleDatabase(":memory:")])
+@pytest.mark.parametrize("db", [None, InMemoryExampleDatabase()])
 @pytest.mark.parametrize("bad_db", [":memory:", ".hypothesis/examples"])
 def test_database_type_must_be_ExampleDatabase(db, bad_db):
     with local_settings(settings(database=db)):
@@ -444,7 +444,7 @@ def a_rule(self, x):
 
 def test_derandomise_with_explicit_database_is_invalid():
     with pytest.raises(InvalidArgument):
-        settings(derandomize=True, database=ExampleDatabase(":memory:"))
+        settings(derandomize=True, database=InMemoryExampleDatabase())
 
 
 @pytest.mark.parametrize(

hypothesis-python/tests/cover/test_stateful.py

@@ -27,7 +27,7 @@
 )
 from hypothesis.control import current_build_context
 from hypothesis.core import encode_failure
-from hypothesis.database import ExampleDatabase
+from hypothesis.database import InMemoryExampleDatabase
 from hypothesis.errors import DidNotReproduce, Flaky, InvalidArgument, InvalidDefinition
 from hypothesis.internal.entropy import deterministic_PRNG
 from hypothesis.stateful import (
@@ -434,7 +434,7 @@ def test_settings_attribute_is_validated():
 
 
 def test_saves_failing_example_in_database():
-    db = ExampleDatabase(":memory:")
+    db = InMemoryExampleDatabase()
     ss = Settings(
         database=db, max_examples=1000, suppress_health_check=list(HealthCheck)
     )

hypothesis-python/tests/nocover/test_database_usage.py

@@ -12,7 +12,7 @@
 
 from hypothesis import assume, core, find, given, settings, strategies as st
 from hypothesis.database import (
-    ExampleDatabase,
+    DirectoryBasedExampleDatabase,
     GitHubArtifactDatabase,
     InMemoryExampleDatabase,
     ReadOnlyDatabase,
@@ -165,7 +165,7 @@ def test(i):
 def test_database_not_created_when_not_used(tmp_path_factory, key, value):
     path = tmp_path_factory.mktemp("hypothesis") / "examples"
     assert not path.exists()
-    database = ExampleDatabase(path)
+    database = DirectoryBasedExampleDatabase(path)
     assert not list(database.fetch(key))
     assert not path.exists()
     database.save(key, value)

hypothesis-python/tests/nocover/test_flatmap.py

@@ -13,7 +13,7 @@
 import pytest
 
 from hypothesis import HealthCheck, assume, given, settings
-from hypothesis.database import ExampleDatabase
+from hypothesis.database import InMemoryExampleDatabase
 from hypothesis.strategies import (
     booleans,
     builds,
@@ -55,7 +55,7 @@ def test_flatmap_retrieve_from_db():
     track = []
 
     @given(floats(0, 1).flatmap(lambda x: lists(just(x))))
-    @settings(database=ExampleDatabase())
+    @settings(database=InMemoryExampleDatabase())
     def record_and_test_size(xs):
         if sum(xs) >= 1:
             track.append(xs)