Make usage of raw bookmarks easier (#1065)

(Async)Neo4jBookmarkManager's `initial_bookmarks` parameter, as well as
`Bookmarks.from_raw_values` `values` parameter accept anything of type
`Iterable[str]`. Unfortunately, `str` itself implements that type and yields
the characters of the string. That most certainly not what the user intended.

In an ideal world, we could tell the type checker to only accept `Iterable[str]`
when *not* of type `str`. See also python/typing#256.

To help users out, we now explicitly check for `isinstance(input, str)` and turn
such inputs into an iterable with the input string as the only element.

Author: robsdedude

src/neo4j/_async/bookmark_manager.py

@@ -51,10 +51,13 @@ def __init__(
         if not initial_bookmarks:
             self._bookmarks = set()
         else:
-            self._bookmarks = set(getattr(
-                initial_bookmarks, "raw_values",
-                t.cast(t.Iterable[str], initial_bookmarks)
-            ))
+            if not hasattr(initial_bookmarks, "raw_values"):
+                initial_bookmarks = Bookmarks.from_raw_values(
+                    t.cast(t.Iterable[str], initial_bookmarks)
+                )
+            self._bookmarks = set(
+                t.cast(Bookmarks, initial_bookmarks).raw_values
+            )
         self._lock = AsyncCooperativeLock()
 
     async def update_bookmarks(

src/neo4j/_sync/bookmark_manager.py

@@ -51,10 +51,13 @@ def __init__(
         if not initial_bookmarks:
             self._bookmarks = set()
         else:
-            self._bookmarks = set(getattr(
-                initial_bookmarks, "raw_values",
-                t.cast(t.Iterable[str], initial_bookmarks)
-            ))
+            if not hasattr(initial_bookmarks, "raw_values"):
+                initial_bookmarks = Bookmarks.from_raw_values(
+                    t.cast(t.Iterable[str], initial_bookmarks)
+                )
+            self._bookmarks = set(
+                t.cast(Bookmarks, initial_bookmarks).raw_values
+            )
         self._lock = CooperativeLock()
 
     def update_bookmarks(

src/neo4j/api.py

@@ -287,8 +287,12 @@ def from_raw_values(cls, values: t.Iterable[str]) -> Bookmarks:
         bookmarks.
 
         :param values: ASCII string values (raw bookmarks)
-        :type values: Iterable[str]
         """
+        if isinstance(values, str):
+            # Unfortunately, str itself is an iterable of str, iterating
+            # over characters. Type checkers will not catch this, so we help
+            # the user out.
+            values = values,
         obj = cls()
         bookmarks = []
         for value in values: