Metadata-Version: 2.5
Name: prot-struct-viz
Version: 0.1.0
Summary: Render a protein structure as a self-contained static HTML Mol* view, colored and labeled per residue from a CSV.
Project-URL: Documentation, https://jbloomlab.github.io/prot-struct-viz/
Project-URL: Homepage, https://github.com/jbloomlab/prot-struct-viz
Project-URL: Repository, https://github.com/jbloomlab/prot-struct-viz
Project-URL: Issues, https://github.com/jbloomlab/prot-struct-viz/issues
Author-email: Jesse Bloom <jbloom@fredhutch.org>
License: MIT License
        
        Copyright (c) 2026, Jesse Bloom
        
        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.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: gemmi>=0.7
Requires-Dist: jinja2>=3.0
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: molviewspec<2,>=1.8
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: black>=24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Description-Content-Type: text/markdown

# prot-struct-viz

[![PyPI version](https://img.shields.io/pypi/v/prot-struct-viz.svg)](https://pypi.org/project/prot-struct-viz/)
[![Python versions](https://img.shields.io/pypi/pyversions/prot-struct-viz.svg)](https://pypi.org/project/prot-struct-viz/)
[![tests](https://github.com/jbloomlab/prot-struct-viz/actions/workflows/tests.yml/badge.svg)](https://github.com/jbloomlab/prot-struct-viz/actions/workflows/tests.yml)
[![Docs](https://img.shields.io/github/deployments/jbloomlab/prot-struct-viz/github-pages?label=docs)](https://jbloomlab.github.io/prot-struct-viz/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Render a protein structure as a **self-contained static HTML file** using
[Mol\*](https://molstar.org/), with residues colored, labeled, and styled from a CSV.
Everything the view needs — coordinates, colors, tooltips, labels — is embedded in the one
file, so it can be dropped on GitHub Pages with no backend.

- **Documentation:** <https://jbloomlab.github.io/prot-struct-viz/>
- **Live example:** <https://jbloomlab.github.io/prot-struct-viz/examples/>

## Install

```bash
pip install prot-struct-viz
```

## Quick start

Write a CSV of the residues you want to say something about, and a spec file naming the
structure, where the HTML goes, and one or more **views** of it. Then:

```bash
prot-struct-viz spec.yaml
```

That writes the page, plus a report on any disagreement between the CSV and the
structure. One spec can hold several named views — different colorings, labels,
representations, or heteroatoms — and the page gets a selector that switches between them
without moving the camera. The URL tracks the selector, so a link can point at one
particular view.

The [quick start](https://jbloomlab.github.io/prot-struct-viz/#quick-start) shows both
files in full; the documentation covers every spec key, the CSV columns, and what a
reader of the output can click.

## Development

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,docs]"

scripts/check.sh            # pytest + ruff + black
scripts/build_examples.sh   # render examples/*/spec.yaml into examples/output/
scripts/build_docs.sh       # mkdocs build --strict
```

Documentation lives in `docs/`, which is the single source — this README is a front door,
not a second copy. Conventions, and the checks to run after changing anything that affects
rendering, are in [`CLAUDE.md`](CLAUDE.md).

### Releasing

Releases are tag-driven and publish to PyPI through
[trusted publishing](https://docs.pypi.org/trusted-publishers/), so no API token is
stored in the repo. The one-time PyPI setup and the per-release recipe are documented at
the top of [`.github/workflows/release.yml`](.github/workflows/release.yml). In short:

```bash
# 1. Bump `version` in pyproject.toml and roll CHANGELOG's [Unreleased] into it.
git commit -am "release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags
```

The workflow verifies the tag matches `pyproject.toml` before anything reaches PyPI.
