genome-spy-python 0.1.0__tar.gz → 0.2.0__tar.gz

{genome_spy_python-0.1.0 → genome_spy_python-0.2.0}/.github/workflows/ci.yml

@@ -68,3 +68,32 @@ jobs:
       - run: uv run python tools/generate_schema_wrapper.py
       - run: uv run ruff format src/genome_spy/schema src/genome_spy/helpers.py src/genome_spy/api.py src/genome_spy/__init__.py
       - run: git diff --exit-code src/genome_spy/schema src/genome_spy/helpers.py src/genome_spy/api.py src/genome_spy/__init__.py tools
+
+  notebook-rendering:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.11"
+      - run: uv build --wheel
+      - name: Install the wheel with the minimum supported AnyWidget
+        run: |
+          uv venv --seed --python 3.11 "$RUNNER_TEMP/notebook-env"
+          for wheel in "$GITHUB_WORKSPACE"/dist/*.whl; do
+            uv pip install --python "$RUNNER_TEMP/notebook-env/bin/python" \
+              "$wheel[arrow]" "anywidget==0.11.0" jupyterlab pandas numpy playwright pillow
+          done
+          "$RUNNER_TEMP/notebook-env/bin/python" -m playwright install --with-deps chromium
+      - name: Render the brush notebook in JupyterLab
+        run: |
+          "$RUNNER_TEMP/notebook-env/bin/python" tools/check_notebook_rendering.py \
+            notebooks/brush_linked_genome_tracks.ipynb \
+            --screenshot "$RUNNER_TEMP/notebook-rendering.png"
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: notebook-rendering
+          path: ${{ runner.temp }}/notebook-rendering.png
+          if-no-files-found: ignore

{genome_spy_python-0.1.0 → genome_spy_python-0.2.0}/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-09-09
+
+### Added
+
+- Python lists and tuples in `gs.expr()` for array expressions containing
+  values, parameters, and calculations.
+- A brush-linked notebook example with an Open in Colab link in the README.
+
+### Changed
+
+- Require AnyWidget 0.11.0 or newer to match the widget lifecycle API used for rendering.
+- Simplified the contributing guide and added brief notebook troubleshooting advice.
+
+### Fixed
+
+- PIK3CA lollipop connectors now reach the protein track.
+- Packaged datasets can be imported on Python 3.14.
+
 ## [0.1.0] - 2026-09-09
 
 First public alpha release, targeting GenomeSpy Core 0.87.0.
@@ -27,4 +45,5 @@ First public alpha release, targeting GenomeSpy Core 0.87.0.
 - Packaged example datasets, documentation, tutorials, and an interactive
   visualization gallery.
 
+[0.2.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/genome-spy/genome-spy-python/releases/tag/v0.1.0

genome_spy_python-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,201 @@
+# Contributing to genome-spy-python
+
+Bug reports, documentation, examples, tests, and code contributions are welcome.
+
+## How to contribute
+
+Open an issue before starting a large change. Small fixes can go straight to a
+pull request.
+
+Explain what your pull request changes and why. Keep unrelated changes separate,
+and update tests and docs when behavior or the public API changes.
+
+## Development setup
+
+Use Python 3.11 or newer and [`uv`](https://docs.astral.sh/uv/). Install the
+development and docs dependencies from the repository root:
+
+```bash
+uv sync --group dev --group docs
+```
+
+Main directories:
+
+- `src/genome_spy/` — library code
+- `tests/` — tests
+- `docs/examples/` — gallery examples
+- `tools/` — code and documentation generators
+
+Install pre-commit hooks to check changes before committing:
+
+```bash
+uv run pre-commit install
+```
+
+## Coding practices
+
+### Python and typing
+
+Use type hints such as `list[T]`, `dict[K, V]`, and `X | Y` for public APIs.
+Add Google-style docstrings covering purpose, arguments, results, exceptions,
+and an example. Keep file, network, and notebook code separate from core logic.
+
+Keep changes small. Prefer generating APIs from the GenomeSpy schema over
+adding handwritten alternatives.
+
+### Formatting and linting
+
+Format and lint with [Ruff](https://docs.astral.sh/ruff/):
+
+```bash
+uv run ruff format .
+uv run ruff check .
+```
+
+Check types after changing library code:
+
+```bash
+uv run mypy src/
+```
+
+### Testing
+
+Add a focused test for each behavior change. Run the Python tests with:
+
+```bash
+uv run pytest tests/ -x
+```
+
+Run the widget's JavaScript tests with:
+
+```bash
+node --test tests/widget.test.mjs
+```
+
+Run the checks relevant to your changes before submitting a pull request.
+CI also checks generated code, docs, and the installed package.
+
+### Performance
+
+Avoid unnecessary data copies and large chart specifications. Measure performance
+before adding complexity to make code faster.
+
+## Generated schema and expression APIs
+
+Do not edit generated files in `src/genome_spy/schema/` by hand. The generator
+uses the GenomeSpy version in `pyproject.toml`, its schema, and the matching
+GenomeSpy and Vega expression documentation.
+
+Regenerate after changing that version or the generator:
+
+```bash
+uv run python tools/generate_schema_wrapper.py
+```
+
+This requires `npm` and internet access. Use `--package-dir` for a local package,
+or both `--genome-spy-expression-docs` and `--vega-expression-docs` for local
+expression docs.
+
+Then check the results:
+
+```bash
+uv run pytest tests/test_schema_codegen.py -x
+uv run ruff format src/genome_spy/schema src/genome_spy/helpers.py src/genome_spy/api.py src/genome_spy/__init__.py
+git diff --check
+```
+
+Review and commit the generated files alongside your changes. CI checks that
+regenerating them produces no differences.
+
+New transforms should be generated from the schema. Add overrides in
+`tools/generate_schema_wrapper.py` only for Python conventions the schema
+cannot describe.
+
+## Documentation
+
+### API reference
+
+After changing the public API, regenerate `docs/api.md` from `genome_spy.__all__`:
+
+```bash
+uv run python tools/generate_api_docs.py
+```
+
+Sphinx creates the individual pages in `docs/generated/`; do not commit them.
+
+### Build and preview
+
+Build the docs and check for warnings:
+
+```bash
+uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+```
+
+Rerun the same command to rebuild changed pages and examples. Keep `docs/_build/`
+and avoid `-E` and `-a` for faster builds. Changes to shared code, data, build
+tools, or the lockfile regenerate all examples.
+
+To force example regeneration, delete the gallery cache (normally
+`docs/_build/html/.doctrees/genomespy-gallery`). Changes to remote data or files
+outside the tracked dependencies are not detected automatically.
+
+Preview locally:
+
+```bash
+cd docs/_build/html
+python3 -m http.server
+```
+
+Open <http://localhost:8000>. Interactive examples need internet access to load
+GenomeSpy.
+
+### Gallery examples
+
+Write examples in `docs/examples/`. Put explanations, data sources, any
+necessary disclaimers, and upstream links in an optional Markdown file with
+the same name.
+
+Focus on plotting, not data preparation: load prepared packaged datasets and
+prefer Python expressions such as `gs.datum.score > 0`. Remember that
+`.transform_*()` defines work that GenomeSpy runs in the browser, not Python.
+
+After editing an example, run:
+
+```bash
+uv run pytest tests/test_docs_gallery.py -q
+uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+```
+
+Check the chart visually before updating its committed thumbnail.
+
+### Notebook rendering
+
+CI checks that the brush notebook renders in a fresh environment. Follow
+[the workflow](.github/workflows/ci.yml) for setup, then run with that
+environment's Python:
+
+```bash
+python -m playwright install chromium
+python tools/check_notebook_rendering.py notebooks/brush_linked_genome_tracks.ipynb --screenshot /tmp/notebook-rendering.png
+```
+
+## Commit guidelines
+
+Keep each commit focused on one change. Use
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+
+```text
+feat(expressions): generate runtime helpers
+fix(widget): preserve zoom during data updates
+docs(gallery): add a sequence example
+```
+
+Do not rewrite shared history unless reviewers ask you to.
+
+## Community and communication
+
+Report wrapper bugs and request features in the
+[Python package issue tracker](https://github.com/genome-spy/genome-spy-python/issues).
+For GenomeSpy's grammar or renderer, use the upstream
+[discussions](https://github.com/genome-spy/genome-spy/discussions) or
+[issues](https://github.com/genome-spy/genome-spy/issues).

{genome_spy_python-0.1.0 → genome_spy_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: genome-spy-python
-Version: 0.1.0
+Version: 0.2.0
 Summary: genome-spy-python is a declarative genomics visualization library for Python, built on top of the genome-spy JSON specification.
 Project-URL: Homepage, https://github.com/genome-spy/genome-spy-python
 Project-URL: Documentation, https://genomespy.app/genome-spy-python/
@@ -23,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.11
-Requires-Dist: anywidget>=0.9.18
+Requires-Dist: anywidget>=0.11.0
 Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: traitlets>=5.14.3
 Provides-Extra: arrow
@@ -36,6 +36,12 @@ Description-Content-Type: text/markdown
 
 <h1 align="center">genome-spy-python</h1>
 
+<p align="center">
+  <a href="https://github.com/genome-spy/genome-spy-python/actions/workflows/ci.yml"><img src="https://github.com/genome-spy/genome-spy-python/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
+  <a href="https://pypi.org/project/genome-spy-python/"><img src="https://img.shields.io/pypi/v/genome-spy-python" alt="PyPI version"></a>
+  <a href="https://colab.research.google.com/github/genome-spy/genome-spy-python/blob/main/notebooks/brush_linked_genome_tracks.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open brush example in Colab"></a>
+</p>
+
 `genome-spy-python` is a Python interface for
 <a href="https://genomespy.app/" target="_blank" rel="noopener noreferrer">GenomeSpy</a>,
 a grammar for interactive and scalable genomic visualization. It lets Python

{genome_spy_python-0.1.0 → genome_spy_python-0.2.0}/README.md

@@ -4,6 +4,12 @@
 
 <h1 align="center">genome-spy-python</h1>
 
+<p align="center">
+  <a href="https://github.com/genome-spy/genome-spy-python/actions/workflows/ci.yml"><img src="https://github.com/genome-spy/genome-spy-python/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
+  <a href="https://pypi.org/project/genome-spy-python/"><img src="https://img.shields.io/pypi/v/genome-spy-python" alt="PyPI version"></a>
+  <a href="https://colab.research.google.com/github/genome-spy/genome-spy-python/blob/main/notebooks/brush_linked_genome_tracks.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open brush example in Colab"></a>
+</p>
+
 `genome-spy-python` is a Python interface for
 <a href="https://genomespy.app/" target="_blank" rel="noopener noreferrer">GenomeSpy</a>,
 a grammar for interactive and scalable genomic visualization. It lets Python

{genome_spy_python-0.1.0 → genome_spy_python-0.2.0}/docs/examples/pik3ca_tcga_brca_lollipop.py

@@ -115,6 +115,8 @@ mutation_view = (
     .properties(
         data=gs.Data(name="mutations"),
     )
+    # Let the anchors extend below their track to meet the protein.
+    .configure_mark(clip="x")
     .encode(
         x=gs.X("position:I").axis(None),
         xOffset=gs.XOffset("xDisplacement:Q").scale(None),
@@ -129,7 +131,9 @@ mutation_view = (
         length=DISPLACEMENT_LENGTH,
         as_="xDisplacement",
         positionFactor=pixels_per_residue,
-        extent=gs.expr("[0.5, proteinLength + 0.5 - 25 / max(1, pixelsPerResidue)]"),
+        extent=gs.expr(
+            [0.5, protein_length + 0.5 - 25 / gs.expr.max(1, pixels_per_residue)]
+        ),
     )
 )
 

{genome_spy_python-0.1.0 → genome_spy_python-0.2.0}/docs/user-guide/notebooks.md

@@ -138,3 +138,11 @@ Marimo control changes.
 
 See the {py:class}`genome_spy.api.JupyterChart` reference for multiple datasets,
 transport options, and method signatures.
+
+## If a chart does not appear
+
+Make sure the package is installed in the Python environment your notebook
+uses. After installing or upgrading it, restart the notebook's Python session
+and rerun the cells. The chart also needs internet access to load its display
+code. As an alternative, use {py:meth}`~genome_spy.TopLevelSpec.save` to save an
+HTML file and open it in a browser.