molstar-cli 0.0.1__tar.gz

molstar_cli-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/
+molstar_cli/_version.py

molstar_cli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Zalevsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

molstar_cli-0.0.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: molstar-cli
+Version: 0.0.1
+Summary: Open local structure and map files (mmCIF, PDB, EMDB maps, ...) in the Mol* viewer from the command line
+Project-URL: Homepage, https://github.com/aozalevsky/molstar_cli
+Project-URL: Issues, https://github.com/aozalevsky/molstar_cli/issues
+Project-URL: Mol*, https://molstar.org
+Author: Arthur Zalevsky
+License-Expression: MIT
+License-File: LICENSE
+License-File: molstar_cli/static/molstar/LICENSE.molstar
+Keywords: cryo-em,emdb,mmcif,mol*,molecular visualization,molstar,pdb,viewer
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# molstar-cli
+
+Open local structure and map files in the [Mol*](https://molstar.org) viewer from the terminal.
+
+```console
+$ pip install molstar-cli
+$ molstar 5me2.cif emd_3488.map.gz
+Mol* viewer: http://127.0.0.1:34037/MtXDcbb3cYRnGhsxczKvZw/
+Press Ctrl-C to stop.
+```
+
+All files open together in one Mol* scene in your default browser — e.g. a model fitted
+into its cryo-EM map. The Mol* viewer is bundled, so it works offline; there are no
+dependencies beyond Python ≥ 3.10.
+
+## Usage
+
+```
+molstar FILE [FILE ...] [-p PORT] [--no-browser]
+```
+
+```console
+$ molstar *.cif                      # several structures, one scene
+$ molstar model.cif emd_1234.map.gz  # model + EMDB map
+$ molstar PDBDEV_00000001.cif        # integrative (IHM) models, incl. coarse-grained beads
+```
+
+The command keeps serving while you look at the structures; stop it with Ctrl-C.
+Reloading the browser tab re-reads the files from disk.
+
+| Option | |
+|---|---|
+| `-p`, `--port PORT` | listen on a fixed port instead of a random free one |
+| `--no-browser` | only print the URL |
+| `-V`, `--version` | print the molstar-cli and bundled Mol* versions |
+
+### Supported formats
+
+Anything Mol*'s *Open Files* dialog accepts, detected by file extension, optionally
+wrapped in `.gz` or `.zip`:
+
+- **Structures:** mmCIF / PDBx (`.cif`, `.mmcif`, `.mcif`) including IHM integrative
+  models, BinaryCIF (`.bcif`), PDB (`.pdb`, `.ent`), PDBQT, PQR, GRO, XYZ, SDF / MOL /
+  MOL2, LAMMPS data/dump
+- **Volumes:** CCP4 / MRC / MAP (`.map`, `.mrc`, `.ccp4` — EMDB maps), DSN6 / BRIX,
+  DX, Cube, density server CIF, MTZ
+- **Trajectories and topologies:** DCD, XTC, TRR, NetCDF, PSF, PRMTOP, TOP
+- **Other:** PLY / OBJ meshes, MolViewSpec (`.mvsj`, `.mvsx`), Mol* sessions (`.molj`, `.molx`)
+
+Unsupported files are skipped with a warning in the Mol* log panel.
+
+Maps open at Mol*'s default isovalue (2σ) — the EMDB-recommended contour level is not
+stored in the map file. Adjust it in the Volume panel on the right.
+
+### Remote machines
+
+With `--no-browser`, or on a Linux machine without a display (e.g. over SSH), `molstar`
+doesn't start a browser; it prints an `ssh -L` command instead:
+
+```console
+server$ molstar model.cif
+Mol* viewer: http://127.0.0.1:41235/Xy.../
+On a remote machine? Run `ssh -L 41235:127.0.0.1:41235 server` on your computer, then open the URL above there.
+Press Ctrl-C to stop.
+```
+
+Use `--port` to keep the same forwarded port between runs.
+
+### Security
+
+The server listens on `127.0.0.1` only, every URL carries a random token, and only the
+files named on the command line can be read — no directory listing, no other paths.
+
+## Development
+
+```console
+$ python -m venv .venv && .venv/bin/pip install -e . pytest
+$ .venv/bin/pytest
+```
+
+### Updating the bundled Mol*
+
+The prebuilt viewer from the [`molstar` npm package](https://www.npmjs.com/package/molstar)
+is vendored in `molstar_cli/static/molstar/` (no Node.js needed):
+
+```console
+$ python scripts/update_molstar.py 5.11.0
+```
+
+Check that it loads, then commit the result.
+
+### Releasing
+
+Create a GitHub release with a tag like `v0.0.2`. The package version is taken from the
+tag, so there is nothing to bump. The *Publish to PyPI* workflow builds and uploads it
+using [trusted publishing](https://docs.pypi.org/trusted-publishers/) (PyPI publisher:
+owner `aozalevsky`, repository `molstar_cli`, workflow `publish.yml`, environment `pypi`).
+
+## Citing Mol*
+
+If you use Mol* in your work, please cite:
+
+> D. Sehnal, S. Bittrich, M. Deshpande, R. Svobodová, K. Berka, V. Bazgier, S. Velankar,
+> S.K. Burley, J. Koča, A.S. Rose. Mol* Viewer: modern web app for 3D visualization and
+> analysis of large biomolecular structures. *Nucleic Acids Research* 49(W1), W431–W437
+> (2021). [doi:10.1093/nar/gkab314](https://doi.org/10.1093/nar/gkab314)
+
+## License
+
+MIT. The bundled Mol* viewer is © Mol* contributors, also MIT —
+see [`LICENSE.molstar`](molstar_cli/static/molstar/LICENSE.molstar).

molstar_cli-0.0.1/README.md

@@ -0,0 +1,111 @@
+# molstar-cli
+
+Open local structure and map files in the [Mol*](https://molstar.org) viewer from the terminal.
+
+```console
+$ pip install molstar-cli
+$ molstar 5me2.cif emd_3488.map.gz
+Mol* viewer: http://127.0.0.1:34037/MtXDcbb3cYRnGhsxczKvZw/
+Press Ctrl-C to stop.
+```
+
+All files open together in one Mol* scene in your default browser — e.g. a model fitted
+into its cryo-EM map. The Mol* viewer is bundled, so it works offline; there are no
+dependencies beyond Python ≥ 3.10.
+
+## Usage
+
+```
+molstar FILE [FILE ...] [-p PORT] [--no-browser]
+```
+
+```console
+$ molstar *.cif                      # several structures, one scene
+$ molstar model.cif emd_1234.map.gz  # model + EMDB map
+$ molstar PDBDEV_00000001.cif        # integrative (IHM) models, incl. coarse-grained beads
+```
+
+The command keeps serving while you look at the structures; stop it with Ctrl-C.
+Reloading the browser tab re-reads the files from disk.
+
+| Option | |
+|---|---|
+| `-p`, `--port PORT` | listen on a fixed port instead of a random free one |
+| `--no-browser` | only print the URL |
+| `-V`, `--version` | print the molstar-cli and bundled Mol* versions |
+
+### Supported formats
+
+Anything Mol*'s *Open Files* dialog accepts, detected by file extension, optionally
+wrapped in `.gz` or `.zip`:
+
+- **Structures:** mmCIF / PDBx (`.cif`, `.mmcif`, `.mcif`) including IHM integrative
+  models, BinaryCIF (`.bcif`), PDB (`.pdb`, `.ent`), PDBQT, PQR, GRO, XYZ, SDF / MOL /
+  MOL2, LAMMPS data/dump
+- **Volumes:** CCP4 / MRC / MAP (`.map`, `.mrc`, `.ccp4` — EMDB maps), DSN6 / BRIX,
+  DX, Cube, density server CIF, MTZ
+- **Trajectories and topologies:** DCD, XTC, TRR, NetCDF, PSF, PRMTOP, TOP
+- **Other:** PLY / OBJ meshes, MolViewSpec (`.mvsj`, `.mvsx`), Mol* sessions (`.molj`, `.molx`)
+
+Unsupported files are skipped with a warning in the Mol* log panel.
+
+Maps open at Mol*'s default isovalue (2σ) — the EMDB-recommended contour level is not
+stored in the map file. Adjust it in the Volume panel on the right.
+
+### Remote machines
+
+With `--no-browser`, or on a Linux machine without a display (e.g. over SSH), `molstar`
+doesn't start a browser; it prints an `ssh -L` command instead:
+
+```console
+server$ molstar model.cif
+Mol* viewer: http://127.0.0.1:41235/Xy.../
+On a remote machine? Run `ssh -L 41235:127.0.0.1:41235 server` on your computer, then open the URL above there.
+Press Ctrl-C to stop.
+```
+
+Use `--port` to keep the same forwarded port between runs.
+
+### Security
+
+The server listens on `127.0.0.1` only, every URL carries a random token, and only the
+files named on the command line can be read — no directory listing, no other paths.
+
+## Development
+
+```console
+$ python -m venv .venv && .venv/bin/pip install -e . pytest
+$ .venv/bin/pytest
+```
+
+### Updating the bundled Mol*
+
+The prebuilt viewer from the [`molstar` npm package](https://www.npmjs.com/package/molstar)
+is vendored in `molstar_cli/static/molstar/` (no Node.js needed):
+
+```console
+$ python scripts/update_molstar.py 5.11.0
+```
+
+Check that it loads, then commit the result.
+
+### Releasing
+
+Create a GitHub release with a tag like `v0.0.2`. The package version is taken from the
+tag, so there is nothing to bump. The *Publish to PyPI* workflow builds and uploads it
+using [trusted publishing](https://docs.pypi.org/trusted-publishers/) (PyPI publisher:
+owner `aozalevsky`, repository `molstar_cli`, workflow `publish.yml`, environment `pypi`).
+
+## Citing Mol*
+
+If you use Mol* in your work, please cite:
+
+> D. Sehnal, S. Bittrich, M. Deshpande, R. Svobodová, K. Berka, V. Bazgier, S. Velankar,
+> S.K. Burley, J. Koča, A.S. Rose. Mol* Viewer: modern web app for 3D visualization and
+> analysis of large biomolecular structures. *Nucleic Acids Research* 49(W1), W431–W437
+> (2021). [doi:10.1093/nar/gkab314](https://doi.org/10.1093/nar/gkab314)
+
+## License
+
+MIT. The bundled Mol* viewer is © Mol* contributors, also MIT —
+see [`LICENSE.molstar`](molstar_cli/static/molstar/LICENSE.molstar).

molstar_cli-0.0.1/molstar_cli/__init__.py

@@ -0,0 +1,12 @@
+"""Open local molecular structure and volume files in the Mol* viewer."""
+from pathlib import Path
+
+try:
+    from ._version import __version__  # written from the git tag at build/install time
+except ImportError:  # source tree that was never built or installed
+    __version__ = "0+unknown"
+
+
+def molstar_version() -> str:
+    """Version of the bundled Mol* viewer."""
+    return (Path(__file__).parent / "static" / "molstar" / "VERSION").read_text().strip()

molstar_cli-0.0.1/molstar_cli/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

molstar_cli-0.0.1/molstar_cli/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

molstar_cli-0.0.1/molstar_cli/cli.py

@@ -0,0 +1,70 @@
+"""Command-line entry point: ``molstar FILE [FILE ...]``."""
+from __future__ import annotations
+
+import argparse
+import os
+import socket
+import sys
+import webbrowser
+from pathlib import Path
+
+from . import __version__, molstar_version
+from .server import MolstarServer
+
+
+def parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="molstar",
+        description="Open structure and volume files (mmCIF, BinaryCIF, PDB, EMDB maps, ...) "
+                    "together in one Mol* viewer scene in your browser.",
+    )
+    parser.add_argument("files", nargs="+", metavar="FILE", help="files to open")
+    parser.add_argument("-p", "--port", type=int, default=0, help="port to listen on (default: a random free port)")
+    parser.add_argument("--no-browser", action="store_true", help="only print the URL, do not open a browser")
+    parser.add_argument("-V", "--version", action="version",
+                        version=f"molstar-cli {__version__} (Mol* {molstar_version()})")
+    return parser.parse_args(argv)
+
+
+def can_open_browser() -> bool:
+    """Whether webbrowser.open would reach a graphical browser rather than lynx/w3m in this terminal."""
+    if sys.platform in ("darwin", "win32") or os.environ.get("BROWSER"):
+        return True
+    return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+
+    bad = False
+    for name in args.files:
+        path = Path(name)
+        if not path.is_file():
+            reason = "is a directory" if path.is_dir() else "no such file"
+            print(f"molstar: error: {name}: {reason}", file=sys.stderr)
+            bad = True
+    if bad:
+        return 2
+
+    try:
+        server = MolstarServer(args.files, port=args.port)
+    except OSError as e:
+        print(f"molstar: error: cannot listen on port {args.port}: {e.strerror or e}", file=sys.stderr)
+        return 1
+
+    with server:
+        port = server.server_address[1]
+        print(f"Mol* viewer: {server.url}")
+        if args.no_browser or not can_open_browser():
+            print(f"On a remote machine? Run `ssh -L {port}:127.0.0.1:{port} {socket.gethostname()}` "
+                  "on your computer, then open the URL above there.")
+        else:
+            webbrowser.open(server.url)
+        # Flush now: when stdout is a pipe or file it is block-buffered, and the URL
+        # would otherwise only appear after the server stops.
+        print("Press Ctrl-C to stop.", flush=True)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+    return 0

molstar_cli-0.0.1/molstar_cli/server.py

@@ -0,0 +1,128 @@
+"""Local HTTP server for the bundled Mol* viewer and the files it should open."""
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import shutil
+import socketserver
+import sys
+from collections.abc import Iterable
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import quote, unquote, urlsplit
+
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+VIEWER_DIR = STATIC_DIR / "molstar"
+INDEX_HTML = STATIC_DIR / "open.html"
+
+CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".ico": "image/x-icon",
+    ".jpg": "image/jpeg",
+}
+
+
+class MolstarServer(ThreadingHTTPServer):
+    """Serves the viewer and ``files`` on localhost under a random URL token.
+
+    Only the files passed in are readable; everything else is 403 (wrong token) or 404.
+    """
+
+    daemon_threads = True
+    # On Windows SO_REUSEADDR lets a second socket bind a port that is already in use.
+    allow_reuse_address = sys.platform != "win32"
+
+    def __init__(self, files: Iterable[str | os.PathLike], host: str = "127.0.0.1", port: int = 0):
+        self.files = [Path(f).resolve() for f in files]
+        self.token = secrets.token_urlsafe(16)
+        super().__init__((host, port), _Handler)
+
+    def server_bind(self):
+        # Skip HTTPServer.server_bind: its socket.getfqdn() reverse DNS lookup can block
+        # for ~35 s on macOS, and server_name is only used by CGI handlers.
+        socketserver.TCPServer.server_bind(self)
+        self.server_name, self.server_port = self.server_address[:2]
+
+    @property
+    def url(self) -> str:
+        host, port = self.server_address[:2]
+        return f"http://{host}:{port}/{self.token}/"
+
+    def manifest(self) -> list[dict[str, str]]:
+        return [{"name": f.name, "url": f"files/{i}/{quote(f.name)}"} for i, f in enumerate(self.files)]
+
+    def handle_error(self, request, client_address):
+        # The browser dropping a connection mid-transfer is not worth a traceback.
+        if not isinstance(sys.exc_info()[1], ConnectionError):
+            super().handle_error(request, client_address)
+
+
+class _Handler(BaseHTTPRequestHandler):
+    server: MolstarServer
+
+    def do_GET(self):
+        path = unquote(urlsplit(self.path).path)
+        prefix = f"/{self.server.token}/"
+        if not path.startswith(prefix):
+            self.send_error(403)
+            return
+        rest = path[len(prefix):]
+        if rest == "":
+            self._send_file(INDEX_HTML)
+        elif rest == "files.json":
+            self._send_bytes(json.dumps(self.server.manifest()).encode(), CONTENT_TYPES[".json"])
+        elif rest.startswith("files/"):
+            self._send_file(self._listed_file(rest), "application/octet-stream")
+        else:
+            self._send_file(self._viewer_asset(rest))
+
+    def _listed_file(self, rest: str) -> Path | None:
+        parts = rest.split("/")
+        if len(parts) != 3 or not parts[1].isdecimal():
+            return None
+        index, name = int(parts[1]), parts[2]
+        if index >= len(self.server.files) or self.server.files[index].name != name:
+            return None
+        return self.server.files[index]
+
+    def _viewer_asset(self, rest: str) -> Path | None:
+        try:
+            target = (VIEWER_DIR / rest).resolve()
+        except (OSError, ValueError):
+            return None
+        return target if target.is_relative_to(VIEWER_DIR) and target.is_file() else None
+
+    def _send_file(self, path: Path | None, content_type: str | None = None):
+        if path is None:
+            self.send_error(404)
+            return
+        try:
+            f = path.open("rb")
+        except OSError:
+            self.send_error(404)
+            return
+        with f:
+            self._send_headers(os.fstat(f.fileno()).st_size,
+                               content_type or CONTENT_TYPES.get(path.suffix.lower(), "application/octet-stream"))
+            try:
+                shutil.copyfileobj(f, self.wfile)
+            except ConnectionError:
+                pass
+
+    def _send_bytes(self, data: bytes, content_type: str):
+        self._send_headers(len(data), content_type)
+        self.wfile.write(data)
+
+    def _send_headers(self, length: int, content_type: str):
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(length))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+
+    def log_message(self, format, *args):
+        pass

molstar_cli-0.0.1/molstar_cli/static/molstar/LICENSE.molstar

@@ -0,0 +1,21 @@
+The MIT License
+
+    Copyright (c) 2017 - now, Mol* contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

molstar_cli-0.0.1/molstar_cli/static/molstar/VERSION

@@ -0,0 +1 @@
+5.11.0