Storage API docs: prose, support level, changelog. #325

CHANGES.rst

@@ -13,6 +13,8 @@ Unreleased
 
 * Stop using deprecated :mod:`sqlite3` datetime converters/adapters.
   (:issue:`321`)
+* Document the storage :doc:`internal`.
+  (:issue:`325`)
 * Change all :doc:`internal APIs <internal>` to use timezone-aware datetimes,
   with the timezone set to UTC.
   (:issue:`321`)

docs/dev.rst

@@ -180,6 +180,17 @@ Other exceptions are possible; they will be marked aggresively as such.
   which served as inspiration for this.
 
 
+Internal API
+~~~~~~~~~~~~
+
+The :doc:`internal` is not stable,
+but the long term goal is for it to become so.
+
+In order to support / encourage potential users
+(e.g. plugins, alternate storage implementations),
+changes should at least be announced in the :doc:`changelog`.
+
+
 Supported Python versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/internal.rst

@@ -114,9 +114,41 @@ Data objects
     :members:
 
 
+.. _storage:
+
 Storage
 -------
 
+*reader* storage is abstracted by two :abbr:`DAO (data access object)` protocols:
+:class:`StorageType`, which provides the main storage,
+and :class:`SearchType`, which provides search-related operations.
+
+Currently, there's only one supported implementation, based on SQLite.
+
+That said, it is possible to use an alternate implementation
+by passing a :class:`StorageType` instance
+via the ``_storage`` :func:`.make_reader` argument::
+
+    reader = make_reader('unused', _storage=MyStorage(...))
+
+The protocols are *mostly* stable,
+but some backwards-incompatible changes are expected in the future
+(known ones are marked below with *Unstable*).
+The long term goal is for the storage API to become stable,
+but at least one other implementation needs to exists before that.
+(Working on one? :doc:`Let me know! <contributing>`)
+
+
+.. admonition:: Unstable
+
+    Currently, search is tightly-bound to a storage implementation
+    (see :meth:`~.BoundSearchStorageType.make_search`).
+    In the future, it may be possible to mix and match
+    main storage and search implementations,
+    but :class:`StorageType` will likely need
+    additional capabilities to support this.
+
+
 .. autoattribute:: reader.Reader._storage
 .. autoattribute:: reader.Reader._search