Metadata-Version: 2.4
Name: databroker
Version: 2.0.0
Summary: Unification of NSLS-II data sources
Home-page: https://github.com/NSLS-II/databroker
Author: Brookhaven National Laboratory
License: BSD (3-clause)
Classifier: License :: OSI Approved :: BSD License
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tiled[minimal-client]
Provides-Extra: client
Requires-Dist: bluesky-tiled-plugins; extra == "client"
Requires-Dist: msgpack>=1.0.0; extra == "client"
Requires-Dist: orjson; extra == "client"
Requires-Dist: tiled[client]>=0.1.0b30; extra == "client"
Provides-Extra: server
Requires-Dist: area-detector-handlers; extra == "server"
Requires-Dist: bluesky-tiled-plugins; extra == "server"
Requires-Dist: cachetools; extra == "server"
Requires-Dist: entrypoints; extra == "server"
Requires-Dist: event-model; extra == "server"
Requires-Dist: fastapi; extra == "server"
Requires-Dist: json-merge-patch; extra == "server"
Requires-Dist: jsonpatch; extra == "server"
Requires-Dist: jsonschema; extra == "server"
Requires-Dist: mongomock; extra == "server"
Requires-Dist: mongoquery; extra == "server"
Requires-Dist: msgpack>=1.0.0; extra == "server"
Requires-Dist: pims; extra == "server"
Requires-Dist: pydantic; extra == "server"
Requires-Dist: pymongo<=4.11; extra == "server"
Requires-Dist: pytz; extra == "server"
Requires-Dist: rich; extra == "server"
Requires-Dist: starlette; extra == "server"
Requires-Dist: suitcase-mongo>=0.5.0; extra == "server"
Requires-Dist: tiled[server]>=0.1.0b30; extra == "server"
Requires-Dist: toolz; extra == "server"
Requires-Dist: typer; extra == "server"
Requires-Dist: tzlocal; extra == "server"
Requires-Dist: zarr; extra == "server"
Provides-Extra: back-compat
Requires-Dist: boltons; extra == "back-compat"
Requires-Dist: doct; extra == "back-compat"
Requires-Dist: humanize; extra == "back-compat"
Requires-Dist: jinja2; extra == "back-compat"
Provides-Extra: complete
Requires-Dist: area-detector-handlers; extra == "complete"
Requires-Dist: bluesky-tiled-plugins; extra == "complete"
Requires-Dist: boltons; extra == "complete"
Requires-Dist: cachetools; extra == "complete"
Requires-Dist: doct; extra == "complete"
Requires-Dist: entrypoints; extra == "complete"
Requires-Dist: event-model; extra == "complete"
Requires-Dist: fastapi; extra == "complete"
Requires-Dist: humanize; extra == "complete"
Requires-Dist: jinja2; extra == "complete"
Requires-Dist: json-merge-patch; extra == "complete"
Requires-Dist: jsonpatch; extra == "complete"
Requires-Dist: jsonschema; extra == "complete"
Requires-Dist: mongomock; extra == "complete"
Requires-Dist: mongoquery; extra == "complete"
Requires-Dist: msgpack>=1.0.0; extra == "complete"
Requires-Dist: orjson; extra == "complete"
Requires-Dist: pims; extra == "complete"
Requires-Dist: pydantic; extra == "complete"
Requires-Dist: pymongo<=4.11; extra == "complete"
Requires-Dist: pytz; extra == "complete"
Requires-Dist: rich; extra == "complete"
Requires-Dist: starlette; extra == "complete"
Requires-Dist: suitcase-mongo>=0.5.0; extra == "complete"
Requires-Dist: tiled[client]>=0.1.0b30; extra == "complete"
Requires-Dist: tiled[server]>=0.1.0b30; extra == "complete"
Requires-Dist: toolz; extra == "complete"
Requires-Dist: typer; extra == "complete"
Requires-Dist: tzlocal; extra == "complete"
Requires-Dist: zarr; extra == "complete"
Provides-Extra: all
Requires-Dist: area-detector-handlers; extra == "all"
Requires-Dist: bluesky-tiled-plugins; extra == "all"
Requires-Dist: boltons; extra == "all"
Requires-Dist: cachetools; extra == "all"
Requires-Dist: doct; extra == "all"
Requires-Dist: entrypoints; extra == "all"
Requires-Dist: event-model; extra == "all"
Requires-Dist: fastapi; extra == "all"
Requires-Dist: humanize; extra == "all"
Requires-Dist: jinja2; extra == "all"
Requires-Dist: json-merge-patch; extra == "all"
Requires-Dist: jsonpatch; extra == "all"
Requires-Dist: jsonschema; extra == "all"
Requires-Dist: mongomock; extra == "all"
Requires-Dist: mongoquery; extra == "all"
Requires-Dist: msgpack>=1.0.0; extra == "all"
Requires-Dist: orjson; extra == "all"
Requires-Dist: pims; extra == "all"
Requires-Dist: pydantic; extra == "all"
Requires-Dist: pymongo<=4.11; extra == "all"
Requires-Dist: pytz; extra == "all"
Requires-Dist: rich; extra == "all"
Requires-Dist: starlette; extra == "all"
Requires-Dist: suitcase-mongo>=0.5.0; extra == "all"
Requires-Dist: tiled[client]>=0.1.0b30; extra == "all"
Requires-Dist: tiled[server]>=0.1.0b30; extra == "all"
Requires-Dist: toolz; extra == "all"
Requires-Dist: typer; extra == "all"
Requires-Dist: tzlocal; extra == "all"
Requires-Dist: zarr; extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

**********
Databroker
**********

|build_status| |coverage| |pypi_version| |license|

Deprecation Notice
==================

Databroker is no longer recommended for new users or facilities adopting
Bluesky. Instead, `Tiled`_ with `Bluesky Tiled Plugins`_ is recommended as the
canonical way to persist and access data and metadata from Bluesky.

Databroker now serves two purposes that remain relevant for some users and some
faciilities. First, it contains code adapting the legacy MongoDB-based Bluesky
document storage to Tiled---effectively a server-side plugin for Tiled. Second,
it wraps the Tiled Python client to provide an API backward-compatible with
legacy Databroker user code. _If you do not have MongoDB-based Bluesky storage
and you do not have legacy Databroker user code, you do not need Databroker._

Databroker will be maintained by NSLS-II through **April 2027** at minimum to
support the transition from MongoDB-based document storage to PostgreSQL-based
storage. The Python user interface may be maintained longer still, depending on
the need.

============== ==============================================================
PyPI           ``pip install databroker``
Conda          ``conda install -c conda-forge databroker``
Source code    https://github.com/bluesky/databroker
Documentation  https://blueskyproject.io/databroker
============== ==============================================================

The bundle of metadata and data looks like this, for example.

.. code:: python

   >>> run
   BlueskyRun
     uid='4a794c63-8223-4893-895e-d16e763188a8'
     exit_status='success'
     2020-03-07 09:17:40.436 -- 2020-03-07 09:28:53.173
     Streams:
       * primary
       * baseline

Additional user metadata beyond what is shown is stored in ``run.metadata``.
The bundle contains some number of logical tables of data ("streams"). They can
be accessed by name and read into a standard data structure from `xarray`_.
  
.. code:: python

    >>> run.primary.read()
    <xarray.Dataset>
    Dimensions:                   (time: 411)
    Coordinates:
      * time                      (time) float64 1.584e+09 1.584e+09 ... 1.584e+09
    Data variables:
        I0                        (time) float64 13.07 13.01 12.95 ... 9.862 9.845
        It                        (time) float64 11.52 11.47 11.44 ... 4.971 4.968
        Ir                        (time) float64 10.96 10.92 10.88 ... 4.761 4.763
        dwti_dwell_time           (time) float64 1.0 1.0 1.0 1.0 ... 1.0 1.0 1.0 1.0
        dwti_dwell_time_setpoint  (time) float64 1.0 1.0 1.0 1.0 ... 1.0 1.0 1.0 1.0
        dcm_energy                (time) float64 1.697e+04 1.698e+04 ... 1.791e+04
        dcm_energy_setpoint       (time) float64 1.697e+04 1.698e+04 ... 1.791e+04

Common search queries can be done with a high-level Python interface.

.. code:: python

    >>> from databroker.queries import TimeRange
    >>> catalog.search(TimeRange(since="2020"))

Custom queries can be done with the `MongoDB query language`_.

.. code:: python

    >>> query = {
    ...    "motors": {"$in": ["x", "y"]},  # scanning either x or y
    ...    "temperature" {"$lt": 300},  # temperature less than 300
    ...    "sample.element": "Ni",
    ... }
    >>> catalog.search(query)

See the tutorials for more.

.. |build_status| image:: https://github.com/bluesky/databroker/workflows/Unit%20Tests/badge.svg?branch=master
    :target: https://github.com/bluesky/databroker/actions?query=workflow%3A%22Unit+Tests%22
    :alt: Build Status

.. |coverage| image:: https://codecov.io/gh/bluesky/databroker/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/bluesky/databroker
    :alt: Test Coverage

.. |pypi_version| image:: https://img.shields.io/pypi/v/databroker.svg
    :target: https://pypi.org/project/databroker
    :alt: Latest PyPI version

.. |license| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
    :target: https://opensource.org/licenses/BSD-3-Clause
    :alt: BSD 3-Clause License

.. _xarray: https://xarray.pydata.org/

.. _MongoDB query language: https://docs.mongodb.com/manual/reference/operator/query/

.. _Bluesky Data Model: https://blueskyproject.io/event-model/main/user/explanations/data-model.html

.. _Suitcase: https://blueskyproject.io/suitcase/

.. _Intake: https://intake.readthedocs.io/en/latest/

.. _Bluesky Tiled Plugins: https://blueskyproject.io/bluesky-tiled-plugins/

.. _Tiled: https://blueskyproject.io/tiled/
