bluesky-tiled-plugins 2.0.0b54__tar.gz

bluesky_tiled_plugins-2.0.0b54/.gitignore

@@ -0,0 +1,140 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+docs/_build
+
+# PyInstaller
+
+#  Usually these files are written by a python script from a template
+
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# dotenv environment variables file
+.env*
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+cover/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+cover/*
+
+# Translations
+*.mo
+*.pot
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# Rope
+.ropeproject
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+#mac
+.DS_Store
+*~
+
+#vim
+*.swp
+
+#pycharm
+.idea/*
+
+#Dolphin browser files
+.directory/
+.directory
+
+#Binary data files
+*.volume
+*.am
+*.tiff
+*.tif
+*.dat
+*.DAT
+
+#generated documntation files
+docs/resource/api/generated/
+
+# Enaml
+__enamlcache__/
+
+# PyBuilder
+target/
+
+# sphinx docs
+docs/source/generated/
+
+# ctags
+.tags*
+
+# spyder ide
+.spyderworkspace*
+
+# PyCharm
+.idea/
+*.swo
+
+# Ctags
+.tags
+
+.pytest_cache
+docs/source/_as_gen/*
+
+# For VIM Users
+
+#
+dosc/source/_as_gen
+
+# generated by IPython example in docs
+docs/data/*
+docs/source/_generated_images/*
+
+*.swn
+
+.vscode/* 
+
+docs/output_directory
+docs/data.csv
+docs/data.xlsx
+docs/data.h5
+
+# generated by docker-compose
+data/*

bluesky_tiled_plugins-2.0.0b54/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: bluesky-tiled-plugins
+Version: 2.0.0b54
+Summary: Tiled client plugins to provide an customized user experience for Bluesky data in Tiled
+Author-email: Bluesky Project Contributors <dallan@bnl.gov>
+Maintainer-email: Brookhaven National Laboratory <dallan@bnl.gov>
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.7
+Requires-Dist: dask
+Requires-Dist: mongoquery
+Requires-Dist: pytz
+Requires-Dist: tiled[client]>=0.1.0b4
+Requires-Dist: tzlocal
+Description-Content-Type: text/markdown
+
+# bluesky-tiled-plugins
+
+This is a separate Python package, `bluesky-tiled-plugins`, that is
+developed in the databroker repository.
+
+For a user wishing to connect to a running Tiled server and access Bluesky data,
+this package, along with its dependency `tiled[client]`, is all they need.
+
+The databroker package is only required if the user wants to use the legacy
+`databroker.Broker` API.

bluesky_tiled_plugins-2.0.0b54/README.md

@@ -0,0 +1,10 @@
+# bluesky-tiled-plugins
+
+This is a separate Python package, `bluesky-tiled-plugins`, that is
+developed in the databroker repository.
+
+For a user wishing to connect to a running Tiled server and access Bluesky data,
+this package, along with its dependency `tiled[client]`, is all they need.
+
+The databroker package is only required if the user wants to use the legacy
+`databroker.Broker` API.

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/__init__.py

@@ -0,0 +1,3 @@
+from .catalog_of_bluesky_runs import CatalogOfBlueskyRuns  # noqa: F401
+from .bluesky_event_stream import BlueskyEventStream  # noqa: F401
+from .bluesky_run import BlueskyRun  # noqa: F401

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/_common.py

@@ -0,0 +1,6 @@
+# There are methods that IPython will try to call.
+# We special-case them because we want to avoid the getattr
+# resulting in an unnecessary network hit just to raise
+# AttributeError.
+
+IPYTHON_METHODS = {"_ipython_canary_method_should_not_exist_", "_repr_mimebundle_"}

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '2.0.0b54'
+__version_tuple__ = version_tuple = (2, 0, 0)

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/bluesky_event_stream.py

@@ -0,0 +1,83 @@
+import keyword
+import warnings
+
+from tiled.client.container import DEFAULT_STRUCTURE_CLIENT_DISPATCH, Container
+
+from ._common import IPYTHON_METHODS
+
+
+class BlueskyEventStream(Container):
+    """
+    This encapsulates the data and metadata for one 'stream' in a Bluesky 'run'.
+
+    This adds for bluesky-specific conveniences to the standard client Container.
+    """
+
+    def __repr__(self):
+        return f"<{type(self).__name__} {set(self)!r} stream_name={self.metadata['stream_name']!r}>"
+
+    @property
+    def descriptors(self):
+        return self.metadata["descriptors"]
+
+    @property
+    def _descriptors(self):
+        # For backward-compatibility.
+        # We do not normally worry about backward-compatibility of _ methods, but
+        # for a time databroker.v2 *only* have _descriptors and not descriptros,
+        # and I know there is useer code that relies on that.
+        warnings.warn("Use .descriptors instead of ._descriptors.", stacklevel=2)
+        return self.descriptors
+
+    def __getattr__(self, key):
+        """
+        Let run.X be a synonym for run['X'] unless run.X already exists.
+
+        This behavior is the same as with pandas.DataFrame.
+        """
+        # The wisdom of this kind of "magic" is arguable, but we
+        # need to support it for backward-compatibility reasons.
+        if key in IPYTHON_METHODS:
+            raise AttributeError(key)
+        if key in self:
+            return self[key]
+        raise AttributeError(key)
+
+    def __dir__(self):
+        # Build a list of entries that are valid attribute names
+        # and add them to __dir__ so that they tab-complete.
+        tab_completable_entries = [
+            entry
+            for entry in self
+            if (entry.isidentifier() and (not keyword.iskeyword(entry)))
+        ]
+        return super().__dir__() + tab_completable_entries
+
+    def read(self, *args, **kwargs):
+        """
+        Shortcut for reading the 'data' (as opposed to timestamps or config).
+
+        That is:
+
+        >>> stream.read(...)
+
+        is equivalent to
+
+        >>> stream["data"].read(...)
+        """
+        return self["data"].read(*args, **kwargs)
+
+    def to_dask(self):
+        warnings.warn(
+            """Do not use this method.
+Instead, set dask or when first creating the client, as in
+
+    >>> catalog = from_uri("...", "dask")
+
+and then read() will return dask objects.""",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.new_variation(
+            structure_clients=DEFAULT_STRUCTURE_CLIENT_DISPATCH["dask"]
+        ).read()

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/bluesky_run.py

@@ -0,0 +1,147 @@
+import json
+import keyword
+import warnings
+from datetime import datetime
+
+from tiled.client.container import Container
+from tiled.client.utils import handle_error
+
+from ._common import IPYTHON_METHODS
+from .document import Start, Stop, Descriptor, EventPage, DatumPage, Resource
+
+
+_document_types = {
+    "start": Start,
+    "stop": Stop,
+    "descriptor": Descriptor,
+    "event_page": EventPage,
+    "datum_page": DatumPage,
+    "resource": Resource,
+}
+
+
+class BlueskyRun(Container):
+    """
+    This encapsulates the data and metadata for one Bluesky 'run'.
+
+    This adds for bluesky-specific conveniences to the standard client Container.
+    """
+
+    def __repr__(self):
+        metadata = self.metadata
+        datetime_ = datetime.fromtimestamp(metadata["start"]["time"])
+        return (
+            f"<{type(self).__name__} "
+            f"{set(self)!r} "
+            f"scan_id={metadata['start'].get('scan_id', 'UNSET')!s} "  # (scan_id is optional in the schema)
+            f"uid={metadata['start']['uid'][:8]!r} "  # truncated uid
+            f"{datetime_.isoformat(sep=' ', timespec='minutes')}"
+            ">"
+        )
+
+    @property
+    def start(self):
+        """
+        The Run Start document. A convenience alias:
+
+        >>> run.start is run.metadata["start"]
+        True
+        """
+        return self.metadata["start"]
+
+    @property
+    def stop(self):
+        """
+        The Run Stop document. A convenience alias:
+
+        >>> run.stop is run.metadata["stop"]
+        True
+        """
+        return self.metadata["stop"]
+
+    @property
+    def v2(self):
+        return self
+
+    def documents(self, fill=False):
+        # For back-compat with v2:
+        if fill == "yes":
+            fill = True
+        elif fill == "no":
+            fill = False
+        elif fill == "delayed":
+            raise NotImplementedError("fill='delayed' is not supported")
+        else:
+            fill = bool(fill)
+        link = self.item["links"]["self"].replace("/metadata", "/documents", 1)
+        with self.context.http_client.stream(
+            "GET",
+            link,
+            params={"fill": fill},
+            headers={"Accept": "application/json-seq"},
+        ) as response:
+            if response.is_error:
+                response.read()
+                handle_error(response)
+            tail = ""
+            for chunk in response.iter_bytes():
+                for line in chunk.decode().splitlines(keepends=True):
+                    if line[-1] == "\n":
+                        item = json.loads(tail + line)
+                        yield (item["name"], _document_types[item["name"]](item["doc"]))
+                        tail = ""
+                    else:
+                        tail += line
+            if tail:
+                item = json.loads(tail)
+                yield (item["name"], _document_types[item["name"]](item["doc"]))
+
+    def __getattr__(self, key):
+        """
+        Let run.X be a synonym for run['X'] unless run.X already exists.
+
+        This behavior is the same as with pandas.DataFrame.
+        """
+        # The wisdom of this kind of "magic" is arguable, but we
+        # need to support it for backward-compatibility reasons.
+        if key in IPYTHON_METHODS:
+            raise AttributeError(key)
+        if key in self:
+            return self[key]
+        raise AttributeError(key)
+
+    def __dir__(self):
+        # Build a list of entries that are valid attribute names
+        # and add them to __dir__ so that they tab-complete.
+        tab_completable_entries = [
+            entry
+            for entry in self
+            if (entry.isidentifier() and (not keyword.iskeyword(entry)))
+        ]
+        return super().__dir__() + tab_completable_entries
+
+    def describe(self):
+        "For back-compat with intake-based BlueskyRun"
+        warnings.warn(
+            "This will be removed. Use .metadata directly instead of describe()['metadata'].",
+            DeprecationWarning,
+        )
+        return {"metadata": self.metadata}
+
+    def __call__(self):
+        warnings.warn(
+            "Do not call a BlueskyRun. For now this returns self, for "
+            "backward-compatibility. but it will be removed in a future "
+            "release.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self
+
+    def read(self):
+        raise NotImplementedError(
+            "Reading any entire run is not supported. "
+            "Access a stream in this run and read that."
+        )
+
+    to_dask = read

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/catalog_of_bluesky_runs.py

@@ -0,0 +1,146 @@
+import collections.abc
+import numbers
+import operator
+
+from tiled.adapters.utils import IndexCallable
+from tiled.client.container import Container
+from tiled.client.utils import handle_error
+from tiled.utils import safe_json_dump
+
+from .queries import PartialUID, RawMongo, ScanID
+
+
+class CatalogOfBlueskyRuns(Container):
+    """
+    This adds some bluesky-specific conveniences to the standard client Container.
+
+    >>> catalog.scan_id[1234]  # scan_id lookup
+    >>> catalog.uid["9acjef"]  # (partial) uid lookup
+    >>> catalog[1234]  # automatically do scan_id lookup for positive integer
+    >>> catalog["9acjef"]  # automatically do (partial) uid lookup for string
+    >>> catalog[-5]  # automatically do catalog.values()[-N] for negative integer
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.scan_id = IndexCallable(self._lookup_by_scan_id)
+        self.uid = IndexCallable(self._lookup_by_partial_uid)
+        self._v1 = None
+
+    def __repr__(self):
+        # This is a copy/paste of the general-purpose implementation
+        # tiled.adapters.utils.tree_repr
+        # with some modifications to extract scan_id from the metadata.
+        sample = self.items()[:10]
+        # Use scan_id (int) if defined; otherwise fall back to uid.
+        sample_reprs = [
+            repr(value.metadata["start"].get("scan_id", key)) for key, value in sample
+        ]
+        out = "<Catalog {"
+        # Always show at least one.
+        if sample_reprs:
+            out += sample_reprs[0]
+        # And then show as many more as we can fit on one line.
+        counter = 1
+        for sample_repr in sample_reprs[1:]:
+            if len(out) + len(sample_repr) > 60:  # character count
+                break
+            out += ", " + sample_repr
+            counter += 1
+        approx_len = operator.length_hint(self)  # cheaper to compute than len(node)
+        # Are there more in the node that what we displayed above?
+        if approx_len > counter:
+            out += f", ...}} ~{approx_len} entries>"
+        else:
+            out += "}>"
+        return out
+
+    @property
+    def v2(self):
+        return self
+
+    def __getitem__(self, key):
+        # For convenience and backward-compatiblity reasons, we support
+        # some "magic" here that is helpful in an interactive setting.
+        if isinstance(key, str):
+            # CASE 1: Interpret key as a uid or partial uid.
+            if len(key) == 36:
+                # This looks like a full uid. Try direct lookup first.
+                try:
+                    return super().__getitem__(key)
+                except KeyError:
+                    # Fall back to partial uid lookup below.
+                    pass
+            return self._lookup_by_partial_uid(key)
+        elif isinstance(key, numbers.Integral):
+            if key > 0:
+                # CASE 2: Interpret key as a scan_id.
+                return self._lookup_by_scan_id(key)
+            else:
+                # CASE 3: Interpret key as a recently lookup, as in
+                # `catalog[-1]` is the latest entry.
+                key = int(key)
+                return self.values()[key]
+        elif isinstance(key, slice):
+            if (key.start is None) or (key.start >= 0):
+                raise ValueError(
+                    "For backward-compatibility reasons, slicing here "
+                    "is limited to negative indexes. "
+                    "Use .values() to slice how you please."
+                )
+            return self.values()[key]
+        elif isinstance(key, collections.abc.Iterable):
+            # We know that isn't a str because we check that above.
+            # Recurse.
+            return [self[item] for item in key]
+        else:
+            raise ValueError(
+                "Indexing expects a string, an integer, or a collection of strings and/or integers."
+            )
+
+    def _lookup_by_scan_id(self, scan_id):
+        results = self.search(ScanID(scan_id, duplicates="latest"))
+        if not results:
+            raise KeyError(f"No match for scan_id={scan_id}")
+        else:
+            # By construction there must be only one result. Return it.
+            return results.values().first()
+
+    def _lookup_by_partial_uid(self, partial_uid):
+        results = self.search(PartialUID(partial_uid))
+        if not results:
+            raise KeyError(f"No match for partial_uid {partial_uid}")
+        else:
+            # By construction there must be only one result. Return it.
+            return results.values().first()
+
+    def get_serializer(self):
+        from tiled.server.app import get_root_tree
+
+        if not hasattr(self.context.http_client, "app"):
+            raise NotImplementedError("Only works on local application.")
+        tree = self.context.http_client.app.dependency_overrides[get_root_tree]()
+        return tree.get_serializer()
+
+    def search(self, query):
+        # For backward-compatiblity, accept a dict and interpret it as a Mongo
+        # query against the 'start' documents.
+        if isinstance(query, dict):
+            query = RawMongo(start=query)
+        return super().search(query)
+
+    @property
+    def v1(self):
+        "Accessor to legacy interface."
+        if self._v1 is None:
+            from databroker.v1 import Broker
+
+            self._v1 = Broker(self)
+        return self._v1
+
+    def post_document(self, name, doc):
+        link = self.item["links"]["self"].replace("/metadata", "/documents", 1)
+        response = self.context.http_client.post(
+            link, content=safe_json_dump({"name": name, "doc": doc})
+        )
+        handle_error(response)

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/document.py

@@ -0,0 +1,165 @@
+import copy
+
+from dask.base import normalize_token
+
+
+class NotMutable(Exception):
+    pass
+
+
+class Document(dict):
+    """
+    Document is an immutable dict subclass.
+
+    It is immutable to help consumer code avoid accidentally corrupting data
+    that another part of the cosumer code was expected to use unchanged.
+
+    Subclasses of Document must define __dask_tokenize__. The tokenization
+    schemes typically uniquely identify the document based on only a subset of
+    its contents, and mutating the contents can thereby create situations where
+    two unequal objects have colliding tokens. Immutability helps guard against
+    this too.
+
+    Note that Documents are not *recursively* immutable. Just as it is possible
+    create a tuple (immutable) of lists (mutable) and mutate the lists, it is
+    possible to mutate the internal contents of a Document, but this should not
+    be done. It is safer to use the to_dict() method to create a mutable deep
+    copy.
+
+    This is implemented as a dict subclass in order to satisfy certain
+    consumers that expect an object that satisfies isinstance(obj, dict).
+    This implementation detail may change in the future.
+    """
+
+    __slots__ = ("__not_a_real_dict",)
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # This lets pickle recognize that this is not a literal dict and that
+        # it should respect its custom __setstate__.
+        self.__not_a_real_dict = True
+
+    def __repr__(self):
+        # same as dict, but wrapped in the class name so the eval round-trips
+        return f"{self.__class__.__name__}({dict(self)})"
+
+    def _repr_pretty_(self, p, cycle):
+        """
+        A multi-line but eval-able text repr with readable indentation
+
+        This hooks into IPython/Jupyter's display mechanism
+        This is *not* invoked by print() or repr(), but it is invoked by
+        IPython.display.display() which is called in this common scenario::
+
+            In [1]: doc = Document(...)
+            In [2]: doc
+            <pretty representation will show here>
+        """
+        # Note: IPython's pretty-prettying mechanism is custom and complex.
+        # The `text` method used below is a direct and blunt way to engage it
+        # and seems widely used in the IPython code base. There are other
+        # specific mechanisms for displaying collections like dicts, but they
+        # can *truncate* which I think we want to avoid and they would require
+        # more investment to understand how to use.
+        from pprint import pformat
+
+        return p.text(f"{self.__class__.__name__}({pformat(dict(self))})")
+
+    def __getstate__(self):
+        return dict(self)
+
+    def __setstate__(self, state):
+        dict.update(self, state)
+        self.__not_a_real_dict = True
+
+    def __readonly(self, *args, **kwargs):
+        raise NotMutable(
+            "Documents are not mutable. Call the method to_dict() to make a "
+            "fully independent and mutable deep copy."
+        )
+
+    def __setitem__(self, key, value):
+        try:
+            self.__not_a_real_dict
+        except AttributeError:
+            # This path is necessary to support un-pickling.
+            return dict.__setitem__(self, key, value)
+        else:
+            self.__readonly()
+
+    __delitem__ = __readonly
+    pop = __readonly
+    popitem = __readonly
+    clear = __readonly
+    setdefault = __readonly
+    update = __readonly
+
+    def to_dict(self):
+        """
+        Create a mutable deep copy.
+        """
+        # Convert to dict and then make a deep copy to ensure that if the user
+        # mutates any internally nested dicts there is no spooky action at a
+        # distance.
+        return copy.deepcopy(dict(self))
+
+    def __deepcopy__(self, memo):
+        # Without this, copy.deepcopy(Document(...)) fails because deepcopy
+        # creates a new, empty Document instance and then tries to add items to
+        # it.
+        return self.__class__({k: copy.deepcopy(v, memo) for k, v in self.items()})
+
+    def __dask_tokenize__(self):
+        raise NotImplementedError
+
+
+# We must use dask's registration mechanism to tell it to treat Document
+# specially. Dask's tokenization dispatch mechanism discovers that Docuemnt is
+# a dict subclass and treats it as a dict, ignoring its __dask_tokenize__
+# method. To force it to respect our cutsom tokenization, we must explicitly
+# register it.
+
+
+@normalize_token.register(Document)
+def tokenize_document(instance):
+    return instance.__dask_tokenize__()
+
+
+class Start(Document):
+    def __dask_tokenize__(self):
+        return ("start", self["uid"])
+
+
+class Stop(Document):
+    def __dask_tokenize__(self):
+        return ("stop", self["uid"])
+
+
+class Resource(Document):
+    def __dask_tokenize__(self):
+        return ("resource", self["uid"])
+
+
+class Descriptor(Document):
+    def __dask_tokenize__(self):
+        return ("descriptor", self["uid"])
+
+
+class Event(Document):
+    def __dask_tokenize__(self):
+        return ("event", self["uid"])
+
+
+class EventPage(Document):
+    def __dask_tokenize__(self):
+        return ("event_page", self["uid"])
+
+
+class Datum(Document):
+    def __dask_tokenize__(self):
+        return ("datum", self["datum_id"])
+
+
+class DatumPage(Document):
+    def __dask_tokenize__(self):
+        return ("datum_page", self["uid"])

bluesky_tiled_plugins-2.0.0b54/bluesky_tiled_plugins/queries.py

@@ -0,0 +1,305 @@
+from dataclasses import asdict, dataclass
+import enum
+import warnings
+from typing import List, Optional
+
+# Not all of these are used, but import them all
+# for user convenience so everything can be imported from bluesky_tiled_plugins.queries
+from tiled.queries import (  # noqa: F401
+    Comparison,
+    Contains,
+    Eq,
+    FullText,
+    In,
+    Key,
+    NotEq,
+    NotIn,
+    Operator,
+    QueryValueError,
+    Regex,
+)
+from tiled.query_registration import register
+
+
+class Duplicates(str, enum.Enum):
+    latest = "latest"
+    all = "all"
+    error = "error"
+
+
+@register(name="scan_id")
+@dataclass
+class _ScanID:
+    """
+    Find matches to scan_id(s).
+    """
+
+    scan_ids: List[int]
+    duplicates: Duplicates
+
+    def __init__(self, *, scan_ids, duplicates):
+        self.scan_ids = scan_ids
+        self.duplicates = Duplicates(duplicates)
+
+    def encode(self):
+        return {
+            "scan_ids": ",".join(str(scan_id) for scan_id in self.scan_ids),
+            "duplicates": self.duplicates.value,
+        }
+
+    @classmethod
+    def decode(cls, *, scan_ids, duplicates):
+        return cls(
+            scan_ids=[int(scan_id) for scan_id in scan_ids.split(",")],
+            duplicates=Duplicates(duplicates),
+        )
+
+
+def ScanID(*scan_ids, duplicates="latest"):
+    # Wrap _ScanID to provide a nice usage for *one or more scan_ids*:
+    # >>> ScanID(5)
+    # >>> ScanID(5, 6, 7)
+    # Placing a varargs parameter (*scan_ids) in the dataclass constructor
+    # would cause trouble on the server side and generally feels "wrong"
+    # so we have this wrapper function instead.
+    return _ScanID(scan_ids=scan_ids, duplicates=duplicates)
+
+
+@register(name="scan_id_range")
+@dataclass
+class ScanIDRange:
+    """
+    Find scans in the range.
+    """
+
+    start_id: int
+    end_id: int
+    duplicates: Duplicates
+
+    def __init__(self, start_id, end_id, duplicates="latest"):
+        self.start_id = start_id
+        self.end_id = end_id
+        self.duplicates = Duplicates(duplicates)
+
+    def encode(self):
+        return {
+            "start_id": self.start_id,
+            "end_id": self.end_id,
+            "duplicates": self.duplicates.value,
+        }
+
+    @classmethod
+    def decode(cls, *, start_id, end_id, duplicates="latest"):
+        return cls(
+            start_id=int(start_id),
+            end_id=int(end_id),
+            duplicates=Duplicates(duplicates),
+        )
+
+
+@register(name="partial_uid")
+@dataclass
+class _PartialUID:
+    """
+    Find matches to (partial) uid(s).
+    """
+
+    partial_uids: List[str]
+
+    def encode(self):
+        return {"partial_uids": ",".join(str(uid) for uid in self.partial_uids)}
+
+    @classmethod
+    def decode(cls, *, partial_uids):
+        return cls(partial_uids=partial_uids.split(","))
+
+
+def PartialUID(*partial_uids):
+    # See comment above with ScanID and _ScanID. Same thinking here.
+    return _PartialUID(partial_uids)
+
+
+@register(name="duration")
+@dataclass
+class Duration:
+    """
+    Run a MongoDB query against a given collection.
+    """
+
+    less_than: float
+    greater_than: float
+
+
+def RawMongo(start):
+    """
+    DEPRECATED
+
+    Raw MongoDB queries are no longer supported.  If it is possible to express
+    the import as a supported query, we transform it and warn. If not, we raise
+    an error.
+    """
+
+    if len(start) == 1:
+        ((key, value),) = start.items()
+        if not isinstance(value, dict):
+            # We can transform this into a simple query.
+            warnings.warn(
+                """RawMongo will not be supported
+in a future release of databroker, and its functionality has been limited.
+Instead, use:
+
+    Key("{key}") == {value!r}
+"""
+            )
+            return Key(key) == value
+    raise ValueError(
+        """Arbitrary MongoDB queries no longer supported.
+
+If this is critical to you, please open an issue at
+
+    https://github.com/bluesky/databroker
+
+describing your use case and we will see what we can work out."""
+    )
+
+
+# human friendly timestamp formats we'll parse
+_TS_FORMATS = [
+    "%Y-%m-%d %H:%M:%S",
+    "%Y-%m-%d %H:%M",  # these 2 are not as originally doc'd,
+    "%Y-%m-%d %H",  # but match previous pandas behavior
+    "%Y-%m-%d",
+    "%Y-%m",
+    "%Y",
+]
+
+
+def _normalize_human_friendly_time(val, tz):
+    """Given one of :
+    - string (in one of the formats below)
+    - datetime (eg. datetime.now()), with or without tzinfo)
+    - timestamp (eg. time.time())
+    return a timestamp (seconds since jan 1 1970 UTC).
+
+    Non string/datetime values are returned unaltered.
+    Leading/trailing whitespace is stripped.
+    Supported formats:
+    {}
+    """
+    # {} is placeholder for formats; filled in after def...
+
+    import pytz
+    from datetime import datetime
+
+    zone = pytz.timezone(tz)  # tz as datetime.tzinfo object
+    epoch = pytz.UTC.localize(datetime(1970, 1, 1))
+    check = True
+
+    if isinstance(val, str):
+        # unix 'date' cmd format '%a %b %d %H:%M:%S %Z %Y' works but
+        # doesn't get TZ?
+
+        # Could cleanup input a bit? remove leading/trailing [ :,-]?
+        # Yes, leading/trailing whitespace to match pandas behavior...
+        # Actually, pandas doesn't ignore trailing space, it assumes
+        # the *current* month/day if they're missing and there's
+        # trailing space, or the month is a single, non zero-padded digit.?!
+        val = val.strip()
+
+        for fmt in _TS_FORMATS:
+            try:
+                ts = datetime.strptime(val, fmt)
+                break
+            except ValueError:
+                pass
+
+        try:
+            if isinstance(ts, datetime):
+                val = ts
+                check = False
+            else:
+                # what else could the type be here?
+                raise TypeError("expected datetime," " got {:r}".format(ts))
+
+        except NameError:
+            raise ValueError("failed to parse time: " + repr(val))
+
+    if check and not isinstance(val, datetime):
+        return val
+
+    if val.tzinfo is None:
+        # is_dst=None raises NonExistent and Ambiguous TimeErrors
+        # when appropriate, same as pandas
+        val = zone.localize(val, is_dst=None)
+
+    return (val - epoch).total_seconds()
+
+
+@register(name="time_range")
+@dataclass
+class TimeRange:
+    """
+    A search query representing a time range.
+
+    Parameters
+    ----------
+    since, until: dates gives as timestamp, datetime, or human-friendly string, optional
+    timezone : string
+        As in, 'US/Eastern'. If None is given, tzlocal is used.
+
+    Examples
+    --------
+    Any granularity (year, month, date, hour, minute, second) is accepted.
+
+    >>> TimeRange(since='2014')
+
+    >>> TimeRange(until='2019-07')
+
+    >>> TimeRange(since='2014-07-04', until='2020-07-04')
+
+    >>> TimeRange(since='2014-07-04 05:00')
+
+    """
+
+    timezone: str
+    since: Optional[float] = None
+    until: Optional[float] = None
+
+    def __init__(self, *, timezone=None, since=None, until=None):
+        # Stash the raw values just for use in the repr.
+        self._raw_since = since
+        self._raw_until = until
+
+        if timezone is None:
+            import tzlocal
+
+            lz = tzlocal.get_localzone()
+            try:
+                timezone = lz.key
+            except AttributeError:
+                timezone = lz.zone
+        self.timezone = timezone
+        if since is None:
+            self.since = None
+        else:
+            self.since = _normalize_human_friendly_time(since, tz=self.timezone)
+        if until is None:
+            self.until = None
+        else:
+            self.until = _normalize_human_friendly_time(until, tz=self.timezone)
+        if since is not None and until is not None:
+            if self.since > self.until:
+                raise ValueError("since must not be greater than until.")
+
+    def __repr__(self):
+        return (
+            f"{type(self).__name__!s}("
+            f"timezone={self.timezone!r}, since={self._raw_since!r}, until={self._raw_until!r})"
+        )
+
+    def encode(self):
+        return asdict(self)
+
+    @classmethod
+    def decode(cls, *, timezone, since=None, until=None):
+        return cls(timezone=timezone, since=since, until=until)

bluesky_tiled_plugins-2.0.0b54/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bluesky-tiled-plugins"
+description = "Tiled client plugins to provide an customized user experience for Bluesky data in Tiled"
+readme = { file = "README.md", content-type = "text/markdown" }
+authors = [
+  { name = "Bluesky Project Contributors", email = "dallan@bnl.gov" },
+]
+maintainers = [
+  { name = "Brookhaven National Laboratory", email = "dallan@bnl.gov" },
+]
+requires-python = ">=3.7"
+
+dependencies = [
+  "dask",
+  "mongoquery",
+  "pytz",
+  "tiled[client] >=0.1.0b4",
+  "tzlocal",
+]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+
+dynamic = ["version"]
+
+[project.entry-points."tiled.special_client"]
+CatalogOfBlueskyRuns = "bluesky_tiled_plugins.catalog_of_bluesky_runs:CatalogOfBlueskyRuns"
+BlueskyRun = "bluesky_tiled_plugins.bluesky_run:BlueskyRun"
+BlueskyEventStream = "bluesky_tiled_plugins.bluesky_event_stream:BlueskyEventStream"
+
+[tool.hatch]
+version.source = "vcs"
+version.raw-options = { root = ".." }
+version.fallback-version = "0.0.0"
+build.hooks.vcs.version-file = "bluesky_tiled_plugins/_version.py"
+