medusa-style 0.3.0__tar.gz

medusa_style-0.3.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# 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
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Claude Code
+.claude/

medusa_style-0.3.0/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to **medusa-style** are documented here. This project follows
+[Keep a Changelog](https://keepachangelog.com/) and [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] — 2026-07-01
+
+Ground-up refactor around **rendering environments** and an orthogonal
+**Style × Theme** model. The applied look is now a simple `(Palette, Style)`
+pair — one axis for color, one for visual language — and the package is organized
+by backend (`qt/`, `mpl/`) so new environments plug in without touching existing
+code. Net **−470 lines** with more capability, and a stricter, adversarially
+reviewed correctness bar.
+
+### Highlights
+- **Two independent axes.** A **theme** is a color scheme (`dark`, `light`); a
+  **style** is a visual language (`modern`, `presentation`). Any style renders in
+  any theme, and each switches on its own.
+- **One entry point, broader reach.** `apply(target)` auto-detects its target and
+  now covers a Qt **`QWidget`** and a Matplotlib **`Axes`** in addition to a
+  `QApplication`, a `Figure`, and global theming — you never pick a backend.
+- **Assets decoupled from code.** The ~370-line QSS moved out of Python into
+  `assets/qss/base.qss` and is fully tokenized, so a style changes UI density
+  with zero code. All assets load through one zip-safe `resources` module.
+- **Extensible by design.** Add a theme, a style, or a whole new environment
+  (Plotly, VisPy, …) with a single `register_*` call and no edits elsewhere.
+- **Same lazy-import discipline.** `import medusa_style` stays stdlib-only; the Qt
+  path never imports Matplotlib and vice-versa.
+
+### Added
+- `use_style()`, `current_style()`, `styles()` and the built-in **`presentation`**
+  style (larger type, thicker plot lines, roomier controls).
+- `apply(widget)` (scoped Qt stylesheet) and `apply(ax)` (single Axes).
+- `register_theme()`, `register_style()`, `register_environment()` extension doors.
+- `medusa_style.mpl.style_axes()` and `medusa_style.resources.asset_names()`.
+- One-off overrides: `apply(target, theme=…, style=…)`.
+- `BSD-3-Clause` `LICENSE` file, a `CHANGELOG`, and a GitHub Actions workflow that
+  publishes to PyPI on release via Trusted Publishing (OIDC).
+
+### Changed (breaking, relative to 0.2.x)
+- The look is a `(Palette, Style)` pair — the `Theme` composite and the
+  `Typography`/`Geometry` split are gone. `Style` is one flat dataclass.
+- `on_theme_change(cb)` → **`on_change(cb)`**; the callback now receives
+  `(palette, style)`.
+- `current_theme()` now returns a **`Palette`** (was a `Theme`).
+- `customize(fonts=…, spacing=…)` → **`customize(style=…)`** (`colors=` unchanged);
+  it can derive a theme and/or a style and switch both atomically.
+- Data-viz **encodings** (categorical cycle, sequential/diverging colormaps) moved
+  from `Palette` fields to module constants in `medusa_style.palette`
+  (`CATEGORICAL_CYCLE`, `SEQUENTIAL_STOPS`, …) — they are theme- **and**
+  style-independent.
+- `medusa_style.mpl` / `medusa_style.qt` are now packages (import paths unchanged);
+  `write_mplstyle()` signature is `(path, theme=…, style=…)`.
+
+### Removed
+- `medusa_style.theme` and its `ThemeManager`, `ThemeRegistry`, `QssGenerator`,
+  `MplStyleGenerator`, `QssTemplateSource` and the Qt-signal observer proxy.
+- Pre-generated `assets/styles/*.mplstyle` and `mpl.apply_packaged_style()` —
+  generate on demand with `mpl.write_mplstyle()` (no second source of truth).
+- Dead tokens `Palette.shadow` and `Geometry.elevation`.
+
+### Fixed
+Correctness issues surfaced by an adversarial review of the new code:
+- A live `use_theme`/`use_style` no longer forces Fusion back on when the app was
+  built with `fusion=False`.
+- `style_figure(surface=…)` now applies the surface to the **axes** too (cohesion
+  held on the override path).
+- Live `use_style` now resizes chrome fonts (title/labels/ticks) on already-open
+  tracked figures — presentation's larger type reaches embedded plots.
+- `customize(colors=…, style=…)` switches both axes in a **single** atomic step
+  (one repaint, one `on_change`) instead of a transient half-applied look.
+- `use_theme(<active>)` re-syncs a target that had a one-off `theme=`/`style=`
+  override, instead of a no-op.
+- `apply()` on a `QCoreApplication` (headless, no GUI) is a graceful no-op.
+- `icon(color=…)` reorders 8-digit `#RRGGBBAA` roles to Qt's byte order like every
+  other color path; `font.monospace` uses a monospace fallback tail.
+
+### Compatibility
+- Python **3.11–3.13**; `matplotlib >= 3.6`, `PySide6 >= 6.5` (both core deps).
+- Two themes (`dark` default, `light`) × two styles (`modern` default,
+  `presentation`). The colorblind-aware categorical cycle and the
+  `medusa_sequential` / `medusa_diverging` colormaps are unchanged.
+- Verified headless + Qt-offscreen and as an installed wheel; the wheel and sdist
+  both pass `twine check`.
+
+### Upgrading from 0.2.x
+```diff
+- ms.on_theme_change(lambda theme: ...theme.name)
++ ms.on_change(lambda palette, style: ...palette.name)
+
+- theme = ms.current_theme()          # a Theme
++ palette = ms.current_theme()        # a Palette
+
+- ms.customize(colors={...}, fonts={"ui_size_body": 15}, spacing={"radius_md": 10})
++ ms.customize(colors={...}, style={"ui_size_body": 15, "radius_md": 10})
+
+- from medusa_style.theme import ThemeManager   # removed
++ # use ms.apply / ms.use_theme / ms.use_style, or medusa_style.appearance
+```
+
+### Install
+```bash
+pip install medusa-style==0.3.0
+```
+
+[0.3.0]: https://github.com/medusabci/medusa-style/releases/tag/v0.3.0

medusa_style-0.3.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, MEDUSA (https://www.medusabci.com)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

medusa_style-0.3.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: medusa-style
+Version: 0.3.0
+Summary: Single source of truth for MEDUSA styling: one Style x Theme look for PySide6 QSS + Matplotlib, organized by rendering environment.
+Project-URL: Homepage, https://www.medusabci.com/
+Project-URL: Source, https://github.com/medusabci/medusa-style
+Author: MEDUSA
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: bci,eeg,matplotlib,neuroscience,pyside6,qss,theming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: pyside6>=6.5
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# medusa-style
+
+**Single source of truth (SSOT) for MEDUSA styling.** One look themes BOTH
+PySide6 desktop apps (via generated QSS) and Matplotlib scientific plots (built
+on Matplotlib's bundled seaborn baseline) — so a microvolt is the same color in
+the dark acquisition app and on a white-paper export, and an embedded plot is
+seamless with the panel that hosts it.
+
+The look has **two independent axes**:
+
+- a **theme** — the *color scheme* (`dark`, `light`, …), a `Palette`.
+- a **style** — the *visual language* (`modern`, `presentation`, …): fonts,
+  density and plot line widths, a `Style`.
+
+Any style renders in any theme. The code is organized by **rendering
+environment** (`qt/`, `mpl/`, …), so adding a backend never touches the others.
+
+## Install
+
+```bash
+pip install git+https://github.com/medusabci/medusa-style.git
+```
+
+That's all — PySide6 and Matplotlib are both core dependencies (every MEDUSA
+component needs both). The only extra is `[dev]` for building/testing the
+package itself. The seaborn *library* is **not** required: the seaborn base
+styles ship inside Matplotlib.
+
+## The whole API
+
+```python
+import medusa_style as ms
+
+ms.apply(app)               # paint a Qt application (widgets + seamless plots)
+ms.apply(widget)            # scope the theme to one Qt widget
+ms.apply()                  # theme every Matplotlib figure you draw
+ms.apply(fig)               # restyle one figure in place
+ms.apply(ax)                # restyle one axes in place
+ms.use_theme("light")       # switch COLORS — restyles everything already styled
+ms.use_style("presentation")# switch VISUAL LANGUAGE — restyles everything
+ms.current_theme()          # the active Palette
+ms.current_style()          # the active Style
+ms.themes()                 # ['dark', 'light']          — for a theme picker
+ms.styles()                 # ['modern', 'presentation'] — for a style picker
+ms.customize(colors=..., style=...)   # one-line house theme / style
+ms.on_change(cb)            # react to switches — cb(palette, style)
+ms.categorical_color(7)     # SSOT categorical color #7
+```
+
+`apply()` dispatches on what you give it: nothing → global Matplotlib, a
+`QApplication`/`QWidget` → Qt, a `Figure`/`Axes` → Matplotlib. You never choose a
+backend. Whatever you pass is remembered, so a later `use_theme()`/`use_style()`
+repaints it with no loop on your side.
+
+### Desktop app (PySide6)
+
+```python
+import sys
+import medusa_style as ms
+from medusa_style.qt import application, PlotPanel
+from PySide6.QtWidgets import QMainWindow
+
+app = application(sys.argv)        # Hi-DPI handled before construction; themed
+ms.apply()                         # theme Matplotlib figures too
+
+win = QMainWindow()
+panel = PlotPanel(toolbar=True)    # seamless embed — no objectName, no restyle call
+panel.figure.add_subplot(111).plot(range(10), color=ms.categorical_color(0))
+win.setCentralWidget(panel)
+win.show()
+
+# View menu -> app AND embedded figure restyle, one line each:
+view = win.menuBar().addMenu("View")
+view.addAction("Light", lambda: ms.use_theme("light"))
+view.addAction("Presentation", lambda: ms.use_style("presentation"))
+sys.exit(app.exec())
+```
+
+`PlotPanel` is the borderless Matplotlib↔Qt seam as a drop-in widget: its
+background equals the plot's, and it tracks itself for live theme/style switches.
+For a frame you already own, use `medusa_style.qt.embed_figure(frame, fig)`.
+
+### Notebook / headless (Qt never imported)
+
+```python
+import medusa_style as ms
+ms.apply()                  # theme Matplotlib globally
+fig = make_figure()
+ms.apply(fig)               # ...or restyle one figure
+ms.use_theme("dark")        # restyles tracked figures in place
+```
+
+Importing `medusa_style` pulls in **neither** PySide6 **nor** Matplotlib until
+you actually style something.
+
+## Themes and styles
+
+Two built-in **themes** (color schemes), both tuned for long medical/scientific
+sessions:
+
+- **dark** (default) — deep, cool, near-black canvas for dim-lab real-time use.
+- **light** — a calm cool-gray elevation ramp for reports/paper export
+  (`plot_bg` is pure white).
+
+Two built-in **styles** (visual languages):
+
+- **modern** (default) — the clean flat MEDUSA look (`assets/qss/base.qss`).
+- **presentation** — larger type, thicker plot lines and roomier controls for
+  projectors and slides (token-only; reuses `base.qss`).
+
+The data-visualization encodings — a 16-color colorblind-aware categorical cycle
+and the `medusa_sequential` (PSD) / `medusa_diverging` (topomap) colormaps — are
+**theme- and style-independent**, so results stay comparable across every look.
+
+## Customize
+
+Zero config by default; override in one line. `colors` derive a new **theme**,
+`style` derives a new **style**:
+
+```python
+ms.customize(
+    colors={"accent_primary": "#FF6600"},                # -> a registered theme
+    style={"ui_size_body": 15, "plot_line_width": 1.4},  # -> a registered style
+)                            # activates + live-restyles; returns the created value(s)
+```
+
+## Architecture & extensibility
+
+```
+medusa_style/
+  api.py        the public verbs
+  dispatch.py   target detection + environment routing (stdlib-only)
+  appearance.py the active (theme, style) + live switching + observer
+  palette.py    the color SSOT (Palette, DARK, LIGHT) + encodings
+  style.py      the visual languages (Style, MODERN, PRESENTATION)
+  resources.py  zip-safe asset loading
+  qt/           the Qt environment (QSS render, PlotPanel, icons, fonts)
+  mpl/          the Matplotlib environment (rcParams, colormaps, figure styling)
+  assets/       qss/ (structural templates), icons/, fonts/, brand/
+```
+
+- **Add a theme** — one `Palette(...)` literal in `palette.py` (+ `PALETTES`
+  entry) or `ms.register_theme(...)`. Works in every environment immediately.
+- **Add a style** — one `Style(...)` literal in `style.py` (+ `STYLES` entry) or
+  `ms.register_style(...)`. A token-only style is pure data; only a structurally
+  different widget language needs its own `assets/qss/<name>.qss`.
+- **Add an environment** (Plotly, VisPy, Bokeh, …) — a new package with a
+  `matches`/`_apply`/`reapply` trio and one `ms.register_environment(...)`. No
+  existing file changes.
+
+## Power-user namespaces
+
+The tiny top-level surface is enough for almost everything; reach into these only
+when you need the knobs:
+
+| Namespace              | What's there |
+|------------------------|--------------|
+| `medusa_style.qt`      | `application()`, `PlotPanel`, `embed_figure()`, `style_app()`, `stylesheet()`, `prepare_high_dpi()`, `icon()`, `pixmap()`, `load_fonts()` |
+| `medusa_style.mpl`     | `style_figure()`, `style_axes()`, `rcparams()`, `build_rcparams()`, `mplstyle_text()`, `register_colormaps()`, `sequential_cmap()`, `diverging_cmap()` |
+| `medusa_style.palette` | the raw SSOT colors: `Palette`, `DARK`, `LIGHT`, `CATEGORICAL_CYCLE`, WCAG utils |
+| `medusa_style.style`   | the visual languages: `Style`, `MODERN`, `PRESENTATION` |
+
+`medusa_style.qt` imports PySide6 (never Matplotlib); `medusa_style.mpl` imports
+Matplotlib (never Qt). `import medusa_style` loads neither until you style
+something, so a headless figure-export job never pulls in Qt.
+
+## Icons, fonts & brand assets
+
+```python
+from medusa_style import qt
+
+button.setIcon(qt.icon("save_as"))        # theme-agnostic action icon
+button.setIcon(qt.icon("delete_forever", color="error"))  # ...or a semantic color
+splash = qt.pixmap("medusa_splash")       # brand images (splash/login/about)
+win.setWindowIcon(qt.app_icon())          # the MEDUSA app icon
+path = qt.asset_path("fonts/Roboto-Regular.ttf")   # any bundled file, real path
+```
+
+**`qt.icon(name)` icons are theme-agnostic.** The color is not baked in: each
+icon recolors to the active theme on every repaint and changes with Qt's state
+automatically — a disabled widget dims its icon, and a theme switch repaints it
+live, with no re-fetch. Pass `color=` (a palette role like `"error"`/`"accent_primary"`,
+or a `"#RRGGBB"` literal) to force a specific color; it still dims when disabled.
+
+`qt.application()` does the common setup for you: it registers the bundled fonts
+(Roboto family, Abel, Dense, Womby) and sets the MEDUSA window icon app-wide
+(both opt-out via `application(set_icon=False, load_bundled_fonts=False)`).
+
+## Packaging
+
+All runtime data lives under `medusa_style/assets/` — `qss/` (the structural QSS
+templates), `icons/`, `fonts/` and `brand/`. They are declared in `pyproject.toml`
+so the wheel always includes them, while the editable `.psd` design sources stay
+in the repo-level `design_source/` directory (outside the package, never shipped):
+
+```toml
+[tool.hatch.build.targets.wheel]
+packages  = ["medusa_style"]
+artifacts = [
+    "medusa_style/assets/**/*.qss",
+    "medusa_style/assets/**/*.svg",
+    "medusa_style/assets/**/*.png",
+    "medusa_style/assets/**/*.ico",
+    "medusa_style/assets/**/*.ttf",
+    "medusa_style/assets/**/*.otf",
+    "medusa_style/py.typed",
+]
+```
+
+At runtime the assets are loaded zip-safely via `medusa_style.resources` (which
+wraps `importlib.resources`), so it works even from inside a zipped wheel.
+Matplotlib `.mplstyle` files are generated on demand
+(`medusa_style.mpl.write_mplstyle(...)`) rather than shipped, so they can never
+drift from the SSOT.
+```
+```