plexora 0.0.1__py3-none-any.whl

plexora/__init__.py

@@ -0,0 +1,129 @@
+import multiprocessing
+
+multiprocessing.freeze_support()
+
+from flask import Flask
+from pathlib import Path
+
+import os
+
+# Initialize sklearn global threadpool controller to avoid deadlock in threaded
+# contexts.
+from threadpoolctl import threadpool_limits
+
+threadpool_limits()
+
+# Where data lives is `plexora.paths`' business, and it is resolved on demand
+# rather than here. This module used to compute `data_path` at import, whose
+# last fallback was relative to the current working directory -- see that
+# module's docstring for why that had to go, and why nothing may snapshot the
+# answer into a module constant again.
+
+
+# Re-exported under its historical name because server_cli.py imports it from
+# here. `plexora._url` is a leaf module -- it imports nothing from this package
+# -- so pulling it in mid-initialisation is safe.
+from plexora._url import clean_prefix as _clean_base_url
+
+app = None
+
+
+def create_app(plugins=None):
+    """Build the Flask app, then register the core routes and whichever
+    plugins this process activates.
+
+    `global app` is assigned immediately after constructing Flask(...) --
+    before the route-module imports below -- because those modules do
+    `from plexora import app` themselves; if the module-level
+    `app` attribute didn't exist yet at that point (e.g. only assigned via
+    `app = create_app()` after this function returns), that import would
+    fail on a partially-initialized package.
+
+    In practice this is called exactly once, at import time, at the bottom
+    of this file -- it's a factory (rather than a bare module-level
+    Flask()) only so plugins can be chosen before route registration
+    happens. Calling it a second time in one interpreter does NOT rebuild
+    the app: the route modules below are already in sys.modules, so their
+    @app.route decorators never run again and the second app comes back
+    with no core routes at all.
+    """
+    global app
+    # static_folder is None on purpose. It used to be "data", which Flask
+    # resolves against the PACKAGE directory -- so it pointed at
+    # site-packages/plexora/data whatever the data root actually was, and in
+    # the old dev layout (where those happened to be the same directory) it
+    # served the entire data tree from `/data/<path:filename>`. Nothing ever
+    # used it: no template calls url_for('static'), no client code requests
+    # /data/, and tiles go through /generated/data/... instead.
+    app = Flask(__name__, template_folder=Path("client/templates"), static_folder=None)
+    app.config["TEMPLATES_AUTO_RELOAD"] = True
+    app.config["CLIENT_PATH"] = app.root_path + "/client/"
+    # Read from the environment as well as being settable afterwards. It used
+    # to be set only by run.py, from its second positional argv -- so the flag
+    # (which drives the import page's path hints) was silently False for every
+    # other way of starting the server, including the console script the
+    # container could otherwise use.
+    app.config["IS_DOCKER"] = os.environ.get("PLEXORA_DOCKER", "").lower() in ("1", "true", "yes")
+    app.config["PLEXORA_BASE_URL"] = _clean_base_url(os.environ.get("PLEXORA_BASE_URL", ""))
+    app.config["PLEXORA_NOTEBOOK_MODE"] = os.environ.get("PLEXORA_NOTEBOOK_MODE", "").lower() in ("1", "true", "yes")
+
+    @app.after_request
+    def add_notebook_headers(response):
+        # X-Frame-Options: SAMEORIGIN would block the direct (non-proxy) notebook
+        # iframe flow, since the sidecar server (127.0.0.1:<port>) is always a
+        # different origin than the Jupyter page embedding it. The sidecar only
+        # binds to 127.0.0.1, so omitting the header does not expose it to the
+        # network.
+        return response
+
+    # Imported here (not at module top) purely for their route-registration
+    # side effects -- see the docstring above for why `app` must already be
+    # assigned by this point.
+    from plexora.server.routes import page_routes, data_routes, import_routes, quick_view_routes, browse_routes, tool_routes, system_routes, project_routes
+    from plexora.server.models import data_model, database_model
+    from plexora.server import plugins as plugin_registry
+
+    # `plugins is None` means "not passed, consult PLEXORA_PLUGINS", which in
+    # turn distinguishes unset (activate everything installed) from "" (a
+    # deliberate core-only build). A truthy check here would collapse those.
+    plugin_registry.install(app, plugins)
+
+    return app
+
+
+def get_config():
+    """Every project this user can open, merged across the roots.
+
+    Thin wrapper over the project registry, kept because a great deal of the
+    route layer already calls it. The merge -- and the rule that the user's own
+    root wins a name collision with a shared one -- lives in project.py, which
+    is the module that knows how to read a config.json safely.
+    """
+    # Imported here rather than at module scope: project.py is part of the
+    # server package, which imports this module back.
+    from plexora.server.models.project import Project
+
+    return Project.load_all()
+
+
+def get_config_names():
+    data = get_config()
+    try:
+        return [key for key in data.keys()]
+    except AttributeError:
+        return []
+
+
+def view(datasource, **kwargs):
+    """Return a notebook-displayable Plexora viewer for `datasource`.
+
+    This is a small public convenience wrapper around PlexoraViewer. In a
+    Jupyter cell, making it the last expression starts the sidecar server and
+    displays the viewer iframe.
+    """
+    from plexora.jupyter import PlexoraViewer
+
+    return PlexoraViewer(datasource=datasource, **kwargs)
+
+
+app = create_app()

plexora/__main__.py

@@ -0,0 +1,15 @@
+"""`python -m plexora` -- the same command as `plexora`, for anyone whose
+PATH does not have the console script on it (a common state on Windows, and
+inside conda environments that were activated after the shell started).
+
+A pass-through. It carries no special handling of its own: the one thing `-m`
+makes awkward -- that the package is imported before any argument is read, so
+`--plugins` would arrive after Blueprint registration -- is equally true of the
+console script, so the fix lives in `cli.main` where both reach it. See
+`plexora.cli.maybe_reexec_for_plugins`.
+"""
+
+from plexora.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plexora/_url.py

@@ -0,0 +1,105 @@
+"""Base-URL arithmetic, in one place.
+
+Three modules used to carry their own `_clean_base_url`, and two of them meant
+different things by it: `plexora/__init__.py` and `plexora/cli.py` returned a
+prefix with NO trailing slash (`/user/me`), while `plexora/jupyter.py` returned
+one WITH (`/user/me/`) because it immediately concatenated `proxy/<port>` onto
+the end. Same name, same-looking body, opposite contracts -- which is exactly
+the shape of bug that survives review. The two forms both have a legitimate
+caller, so they are kept, but under names that say which is which.
+
+The third function here is the reason this module exists at all.
+`clean_prefix` REFUSES a full origin. Everywhere Plexora used the old helper it
+was handling a mount path -- "/proxy/8000" -- and prefixing it with "/" is
+correct for that. Hosted notebooks introduce a base that is a whole origin
+instead: Colab's `google.colab.kernel.proxyPort()` hands back
+`https://xxxx.googleusercontent.com`. Feeding that to the old helper produced
+`/https:/xxxx.googleusercontent.com` -- a silently corrupt path that fails far
+from where it was made. Raising here turns that class of mistake into a message
+naming the value.
+
+Deliberately a leaf module: stdlib only, imports nothing from `plexora`, so
+`plexora/__init__.py` can use it while it is still initialising.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+
+def is_full_origin(value) -> bool:
+    """Whether `value` is an absolute http(s) URL rather than a mount path."""
+    if not value:
+        return False
+    return str(value).strip().lower().startswith(("http://", "https://"))
+
+
+def clean_prefix(base_url) -> str:
+    """A mount path with a leading slash and no trailing one; "" for none.
+
+    This is what `PLEXORA_BASE_URL` and `app.config['PLEXORA_BASE_URL']` hold,
+    and what templates concatenate request paths onto. "" and "/" both mean
+    "mounted at the root", and both must produce "" rather than "/" so that
+    `f"{prefix}/tile/..."` does not come out with a doubled slash.
+    """
+    if not base_url:
+        return ""
+    base_url = str(base_url).strip()
+    if is_full_origin(base_url):
+        raise ValueError(
+            f"Base URL must be a mount path such as '/proxy/8000', not a full "
+            f"URL: {base_url!r}. A full origin belongs in the DISPLAY url (see "
+            f"plexora._url.join_display), never in PLEXORA_BASE_URL -- the "
+            f"server mounts routes under a path, and prefixing a scheme with "
+            f"'/' would corrupt every link on the page."
+        )
+    if base_url == "/":
+        return ""
+    return "/" + base_url.strip("/")
+
+
+def prefix_with_slash(base_url) -> str:
+    """A mount path with slashes on BOTH ends; "/" for none.
+
+    The form callers want when they are about to append a further path segment
+    by string concatenation, as the notebook sidecar does with
+    `f"{prefix}proxy/{port}"`. Kept separate from `clean_prefix` rather than
+    making one of them call `rstrip` at each call site, because the two answers
+    for "no prefix" genuinely differ: "" and "/".
+    """
+    if not base_url or str(base_url).strip() == "/":
+        return "/"
+    if is_full_origin(base_url):
+        raise ValueError(
+            f"Base URL must be a mount path, not a full URL: {base_url!r}."
+        )
+    return "/" + str(base_url).strip().strip("/") + "/"
+
+
+def join_display(base, *segments) -> str:
+    """Build a URL a human or an <iframe> can follow.
+
+    Unlike the two above, `base` here may legitimately be any of three things,
+    because a hosted notebook picks a different one in each case:
+
+    - "" -- nothing known; the result is a site-root-relative path.
+    - a mount path (`/user/me/proxy/8123`) -- the JupyterHub and Open OnDemand
+      case. Stays path-only ON PURPOSE: an iframe resolves it against the
+      notebook page's own origin, which is the only origin that carries the
+      user's auth cookie, and hardcoding a host would break the moment the hub
+      moved or the user came in through a different name.
+    - a full origin (`https://xxxx.googleusercontent.com`) -- the Colab case,
+      where the proxy is a whole separate subdomain.
+
+    Segments are percent-quoted, so a project named "Tonsil 2 (repeat)" gives a
+    URL that survives being pasted into a browser.
+    """
+    base = "" if base is None else str(base).rstrip("/")
+    tail = "/".join(
+        quote(str(segment).strip("/"), safe="")
+        for segment in segments
+        if segment not in (None, "")
+    )
+    if not tail:
+        return f"{base}/" if base else "/"
+    return f"{base}/{tail}"

plexora/api/__init__.py

@@ -0,0 +1,55 @@
+"""Plexora's plugin API -- the only surface a plugin may import.
+
+    from plexora import api
+
+    ds = api.dataset("my_project")
+    ds.image.channel_names
+    ds.table.markers
+    ds.schema.x
+
+Anything not re-exported here is an implementation detail and will change
+without notice. In particular `plexora.server.models.data_model` is off limits:
+it carries mutable module-level globals under a load lock and two adjacent
+loaders whose names differ by one underscore. The handles in `dataset` call the
+correct one on a plugin's behalf.
+
+First-party plugins (gating today) import from here and nowhere else. That is
+deliberate -- it is what keeps this file honest, since a gap in the API becomes
+a gap in the shipped product rather than something only outside authors hit.
+"""
+
+from plexora.api.dataset import (
+    Dataset,
+    DatasetSchema,
+    ImageHandle,
+    ImageSource,
+    MetadataColumn,
+    SegHandle,
+    TableHandle,
+    TableSource,
+    dataset,
+)
+from plexora.api.http import json_response
+from plexora.api.store import PluginStore, store
+from plexora.server.models.adapters.anndata_adapter import _deduplicate_names
+
+#: Multiplexed panels routinely re-stain the same marker across cycles, so
+#: duplicate names are ordinary rather than exceptional. Suffixes them the way
+#: anndata's own var_names_make_unique() does.
+deduplicate_names = _deduplicate_names
+
+__all__ = [
+    "Dataset",
+    "DatasetSchema",
+    "ImageHandle",
+    "ImageSource",
+    "MetadataColumn",
+    "PluginStore",
+    "SegHandle",
+    "TableHandle",
+    "TableSource",
+    "dataset",
+    "deduplicate_names",
+    "json_response",
+    "store",
+]