Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

suggested additions to documentation of API versions #747

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

suggested additions to documentation of API versions #747

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions docs/source/explanations/v2-transition.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,18 @@ libraries `dask`_, `intake`_, and `xarray`_, which emerged or reached maturity
some time after 2015. Databroker 1.x provides three public interfaces on top of
these two implementations.

=========== ========= ============== ==================================================
API version Interface Implementation Who should use it?
=========== ========= ============== ==================================================
v2 New New All new users
v1 Original New Users with old scripts that use original interface
v0 Original Original Users who hit bugs in v1/v2 and need a fallback
=========== ========= ============== ==================================================
Databorker 2.x contains a new remote-friendly interface using Tiled. This allows
Databroker clients to commincate over HTTP by default. The API interface is very
similar to API v2, with subtle differences mostly in initializing the client.

=========== ========= ============== =========================== ==================================================
API version Interface Implementation Support Databroker Versions Who should use it?
=========== ========= ============== =========================== ==================================================
v2 + tiled New+ Tiled 2.x All new users
v2 New New 2.x, 1.x Users with scripts that use the original v2
v1 Original New 2.x, 1.x Users with old scripts that use original interface
v0 Original Original 2.x, 1.x Users who hit bugs in v1/v2 and need a fallback
=========== ========= ============== =========================== ==================================================

Which interface should I use?
-----------------------------
Expand Down Expand Up @@ -50,6 +55,12 @@ binary formats, such as `TileDB`_.
How do I use them?
------------------

.. code:: python

# v2 + tiled, recommended for new users
# not sure what goes here?


All of the tutorials now use ``databroker.v2``. As they show, this gets you a
v2-style catalog.

Expand Down