composer-nb 0.1.0__py3-none-any.whl

composer_nb/__init__.py

@@ -0,0 +1,38 @@
+"""composer-nb: a small language for chords and drums, played inside notebooks.
+
+In Jupyter, load the cell magic and write music in `%%music` cells:
+
+    %load_ext composer_nb
+
+    %%music intro
+    tempo 75
+    sound guitar
+    play {
+      chords: Am E7|G D
+      kick: loop x-------
+      snare: loop ----x---
+    }
+
+Or build songs from Python with `Song`.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .song import Song
+from .widget import MusicWidget
+
+try:
+    __version__ = version("composer-nb")
+except PackageNotFoundError:  # running from a source checkout that isn't installed
+    __version__ = "0.0.0"
+
+__all__ = ["MusicWidget", "Song", "__version__"]
+
+
+def load_ipython_extension(ipython):
+    """Called by `%load_ext composer_nb`; registers the `%%music` cell magic and its Tab completion."""
+    from .completer import register
+    from .magic import MusicMagics
+
+    ipython.register_magics(MusicMagics)
+    register(ipython)

composer_nb/completer.py

@@ -0,0 +1,148 @@
+"""Tab completion inside `%%music` cells.
+
+Jupyter asks the kernel what could come next, and IPython only knows Python, so the
+extension adds a matcher of its own. The word lists mirror dsl/js/language.js;
+tests/python/test_completer.py fails if the two drift apart.
+"""
+
+import re
+from typing import Dict, List, Optional, Tuple
+
+from .song import Song
+
+DRUMS = ["crash", "ride", "hat", "tom", "floor", "snare", "kick"]
+VARIATIONS = {"ride": ["bell"], "hat": ["open", "pedal"]}
+INSTRUMENTS = ["piano", "epiano", "organ", "pad", "bass", "guitar"]
+SETTINGS = ["time", "tempo", "step", "sound", "key", "capo", "octave", "kit"]
+MODIFIERS = ["accent", "ghost", "double"]
+KITS = ["rock", "synth"]
+
+LANES = [lane for d in DRUMS for lane in [d, *(f"{d}.{v}" for v in VARIATIONS.get(d, []))]]
+PARTS = ["chords", *LANES]
+SETTING_VALUES = {"sound": INSTRUMENTS, "kit": KITS}
+
+MAGIC = "%%music"
+WORD_RE = re.compile(r"^\s*([A-Za-z_]\w*)\s*=", re.M)
+PATTERN_RE = re.compile(r"\bpattern\s+([A-Za-z_]\w*)")
+# The instrument line the cursor is on: its name, then what's been written after the colon.
+PART_RE = re.compile(r"(?:^|[\s{])([a-z]+(?:\.[a-z]+)?):([^:{}]*)$")
+NUMBER_RE = re.compile(r"^\d+$|\)$")
+
+Option = Tuple[str, str]  # the text to insert and its kind, which picks the icon
+
+
+def _options(texts, kind) -> List[Option]:
+    return [(t, kind) for t in texts]
+
+
+def _magic_line(line: str, songs: Dict[str, Song]) -> Optional[Tuple[str, List[Option]]]:
+    """Completions for the `%%music [name] [after <name>]` line itself."""
+    if not line.startswith(MAGIC + " "):
+        return None  # still typing the magic's name, which IPython completes
+    fragment = re.search(r"\w*$", line).group()
+    words = line[len(MAGIC) : len(line) - len(fragment)].split()
+    if words and words[-1] == "after":
+        return fragment, _options(sorted(songs), "variable")
+    if len(words) == 1:
+        return fragment, [("after ", "keyword")]
+    return fragment, []
+
+
+def _statement(head: str, body: str, patterns: List[str]) -> List[Option]:
+    """What can come next on a line that isn't an instrument's."""
+    inside = (body + head).count("{") > (body + head).count("}")
+    words = re.split(r"[{}]", head)[-1].split()
+    names = _options(patterns, "variable")
+    parts = _options([p + ": " for p in PARTS], "property")
+    if not words:
+        settings = _options([s + " " for s in SETTINGS], "keyword")
+        if inside:
+            return parts + names + settings
+        return settings + [("pattern ", "keyword"), ("play ", "keyword")]
+    first, last = words[0], words[-1]
+    if first in ("play", "pattern") and len(words) > 1 and NUMBER_RE.search(last):
+        return _options(["bars ", "bar "], "keyword")
+    if first == "play":
+        return names + (parts if len(words) == 1 else [])
+    if first == "time" and len(words) > 1 and "over" not in words:
+        return [("over ", "keyword")]
+    if first in SETTING_VALUES and len(words) == 1:
+        return _options(SETTING_VALUES[first], "value")
+    if inside and first not in SETTINGS and first != "pattern":
+        return names  # a line that plays patterns in order: intro verse * 2
+    return []
+
+
+def complete(text: str, cursor: int, songs: Optional[Dict[str, Song]] = None):
+    """Completions at `cursor` in a `%%music` cell (`text` includes the magic line).
+
+    Returns (fragment, options): the part of a word already typed, and what could
+    replace it. None means the cursor isn't somewhere this language applies.
+    """
+    songs = songs or {}
+    before = text[:cursor]
+    start = before.rfind("\n") + 1
+    line = before[start:]
+    if start == 0:
+        return _magic_line(line, songs)
+    if "//" in line:
+        return "", []
+    fragment = re.search(r"[A-Za-z_]\w*$|$", line).group()
+    head = line[: len(line) - len(fragment)]
+    magic_line, _, body = before[:start].partition("\n")
+
+    # Names defined above the cursor, in this cell or the cells it continues from.
+    after = re.search(r"\bafter\s+(\w+)", magic_line)
+    inherited = songs[after.group(1)].chain if after and after.group(1) in songs else []
+    defined = "\n".join([*inherited, body])
+    words = sorted(set(WORD_RE.findall(defined)))
+    patterns = sorted(set(PATTERN_RE.findall(defined)))
+
+    variation = re.search(r"([a-z]+)\.$", head)
+    part = PART_RE.search(head)
+    if variation:  # ride. -> ride.bell
+        options = _options([v + ": " for v in VARIATIONS.get(variation.group(1), [])], "property")
+    elif part and part.group(1) in PARTS:
+        written = part.group(2).split()
+        options = _options(words, "variable")
+        if not written:
+            options = [("loop ", "keyword")] + options
+        elif part.group(1) != "chords" and any(w[0].isdigit() for w in written):
+            options = _options(MODIFIERS, "keyword")  # beats take accent, ghost, double
+    else:
+        options = _statement(head, body, patterns)
+    return fragment, [o for o in options if o[0].startswith(fragment) and o[0] != fragment]
+
+
+def register(shell) -> None:
+    """Add the `%%music` matcher to `shell`'s completer, once."""
+    try:
+        from IPython.core.completer import SimpleCompletion, context_matcher
+    except ImportError:  # IPython before 8.6 has no matcher API
+        return
+    identifier = "composer_nb.music_matcher"
+    matchers = shell.Completer.custom_matchers
+    if any(getattr(m, "matcher_identifier", None) == identifier for m in matchers):
+        return
+
+    @context_matcher(identifier=identifier)
+    def music_matcher(context):
+        text = context.full_text
+        result = None
+        if text.startswith(MAGIC):
+            lines = text.split("\n")
+            cursor = sum(len(l) + 1 for l in lines[: context.cursor_line]) + context.cursor_position
+            songs = {k: v for k, v in shell.user_ns.items() if isinstance(v, Song)}
+            result = complete(text, cursor, songs)
+        if result is None:
+            return {"completions": [], "suppress": False}
+        fragment, options = result
+        return {
+            "completions": [SimpleCompletion(text=t, type=kind) for t, kind in options],
+            "matched_fragment": fragment,
+            # Python names mean nothing in a music cell, so IPython's own matchers stay out.
+            # (IPython only honours this when there's something to offer.)
+            "suppress": True,
+        }
+
+    matchers.append(music_matcher)

composer_nb/magic.py

@@ -0,0 +1,53 @@
+import keyword
+from typing import Optional, Tuple
+
+from IPython.core.error import UsageError
+from IPython.core.magic import Magics, cell_magic, magics_class
+
+from .song import Song
+
+USAGE = "Usage: %%music [name] [after <name>]"
+
+
+def parse_magic_line(line: str) -> Tuple[Optional[str], Optional[str]]:
+    """Split the `%%music` line into (name, after)."""
+    words = line.split()
+    name = after = None
+    if words and words[0] != "after":
+        name = words.pop(0)
+    if words:
+        if words[0] != "after" or len(words) != 2:
+            raise UsageError(USAGE)
+        after = words[1]
+    for word in (name, after):
+        if word is not None and (not word.isidentifier() or keyword.iskeyword(word)):
+            raise UsageError(
+                f"{word!r} can't be a cell name. Use letters, digits and underscores, like intro or verse_2."
+            )
+    if name is not None and name == after:
+        raise UsageError(f"{name} can't continue from itself.")
+    return name, after
+
+
+@magics_class
+class MusicMagics(Magics):
+    @cell_magic
+    def music(self, line, cell):
+        """Play a cell of composer-nb source.
+
+        %%music                    play this cell on its own
+        %%music intro              ...and save it as `intro`
+        %%music verse after intro  start from the settings and definitions `intro` ended with
+        """
+        name, after_name = parse_magic_line(line)
+        after = None
+        if after_name is not None:
+            if after_name not in self.shell.user_ns:
+                raise UsageError(f"{after_name} hasn't been run yet. Run its cell first.")
+            after = self.shell.user_ns[after_name]
+            if not isinstance(after, Song):
+                raise UsageError(f"{after_name} is a {type(after).__name__}, not a %%music cell.")
+        song = Song(cell, after=after, name=name)
+        if name is not None:
+            self.shell.user_ns[name] = song
+        return song

composer_nb/song.py

@@ -0,0 +1,59 @@
+from typing import List, Optional
+
+from .widget import MusicWidget
+
+
+class Song:
+    """A cell's worth of composer-nb source.
+
+    Pass `after` to start from the settings and definitions another song ended
+    with (tempo, sound, your own names, ...). The link is to that song object, not to whichever cell
+    sits above, so moving cells around or running them out of order doesn't
+    change what a song sounds like.
+
+        intro = Song("tempo 75\\nsound guitar\\nplay chords: Am E7|G D", name="intro")
+        verse = Song("play chords: F C|Dm E7", after=intro, name="verse")
+    """
+
+    def __init__(self, source: str, *, after: Optional["Song"] = None, name: Optional[str] = None):
+        if not isinstance(source, str):
+            raise TypeError(f"source must be a str, not {type(source).__name__}")
+        if after is not None and not isinstance(after, Song):
+            raise TypeError(f"after must be a Song, not {type(after).__name__}")
+        self.source = source
+        self.after = after
+        self.name = name
+
+    @property
+    def chain(self) -> List[str]:
+        """Sources from the start of the `after` chain down to this song."""
+        sources = []
+        seen = set()
+        song = self
+        while song is not None:
+            if id(song) in seen:
+                raise ValueError("songs can't continue from each other in a loop")
+            seen.add(id(song))
+            sources.append(song.source)
+            song = song.after
+        return sources[::-1]
+
+    def widget(self) -> MusicWidget:
+        """The notebook player for this song."""
+        return MusicWidget(
+            sources=self.chain,
+            name=self.name or "",
+            after=(self.after.name or "") if self.after else "",
+        )
+
+    def _repr_mimebundle_(self, include=None, exclude=None):
+        bundle = self.widget()._repr_mimebundle_(include=include, exclude=exclude)
+        data, metadata = bundle if isinstance(bundle, tuple) else (bundle, {})
+        # Terminals and plain-text renderers get the song, not "<MusicWidget object at ...>".
+        return {**data, "text/plain": repr(self)}, metadata
+
+    def __repr__(self):
+        parts = [repr(self.name)] if self.name else []
+        if self.after is not None:
+            parts.append(f"after={self.after.name or 'Song(...)'}")
+        return f"Song({', '.join(parts)})"

composer_nb/static/widget.css

@@ -0,0 +1 @@
+.cnb{--cnb-accent: var(--jp-brand-color1, #1a73e8);--cnb-text: var(--jp-ui-font-color1, rgba(0, 0, 0, .87));--cnb-mute: var(--jp-ui-font-color2, rgba(0, 0, 0, .54));--cnb-paper: var(--jp-layout-color1, #fff);--cnb-border: var(--jp-border-color2, rgba(0, 0, 0, .12));--cnb-wave: var(--jp-ui-font-color3, rgba(0, 0, 0, .38));--cnb-error: var(--jp-error-color1, #b00020);--cnb-mono: var(--jp-code-font-family, ui-monospace, "SF Mono", Menlo, monospace);display:flex;flex-direction:column;gap:8px;padding:4px 0;color:var(--cnb-text);font-family:var(--jp-ui-font-family, system-ui, sans-serif);font-size:13px}.cnb-head{display:flex;flex-wrap:wrap;align-items:baseline;gap:8px}.cnb-name{font-weight:600}.cnb-after{padding:0 6px;border:1px solid var(--cnb-border);border-radius:999px;color:var(--cnb-mute);font-size:11px}.cnb-settings{color:var(--cnb-mute);font-family:var(--cnb-mono);font-size:11.5px}.cnb-status{color:var(--cnb-mute);font-size:12px}.cnb-status-error{color:var(--cnb-error)}.cnb-player{display:flex;align-items:center;gap:10px}.cnb-play{position:relative;flex-shrink:0;width:30px;height:30px;padding:0;border:1px solid var(--cnb-border);border-radius:50%;background:var(--cnb-paper);color:var(--cnb-accent);cursor:pointer}.cnb-play:hover{border-color:var(--cnb-accent)}.cnb-play:before{content:"";position:absolute;top:50%;left:52%;transform:translate(-40%,-50%);border-style:solid;border-width:6px 0 6px 10px;border-color:transparent transparent transparent currentColor}.cnb-play.is-playing:before{left:50%;transform:translate(-50%,-50%);width:3px;height:11px;border:solid currentColor;border-width:0 3px}.cnb-wave{position:relative;flex:1;min-width:0;height:44px;cursor:pointer}.cnb-wave canvas{display:block;height:44px}.cnb-wave-base{width:100%}.cnb-wave-progress{position:absolute;inset:0 auto 0 0;width:0;overflow:hidden}.cnb-time{flex-shrink:0;color:var(--cnb-mute);font-family:var(--cnb-mono);font-size:11.5px;font-variant-numeric:tabular-nums}.cnb-download{flex-shrink:0;padding:3px 8px;border:1px solid var(--cnb-border);border-radius:4px;color:var(--cnb-mute);font-size:11px;text-decoration:none}.cnb-download:hover{border-color:var(--cnb-accent);color:var(--cnb-accent)}.cnb-chords{display:flex;flex-wrap:wrap;gap:6px}.cnb-chip{display:flex;flex-direction:column;gap:2px;min-width:64px;padding:5px 8px;border:1px solid var(--cnb-border);border-radius:4px;background:var(--cnb-paper);font-family:var(--cnb-mono)}.cnb-chip-label{font-size:12px}.cnb-chip-notes{color:var(--cnb-mute);font-size:9.5px;font-weight:600}.cnb-errors{display:flex;flex-direction:column;gap:2px;padding:6px 10px;border-left:3px solid var(--cnb-error);background:color-mix(in srgb,var(--cnb-error) 7%,transparent);font-family:var(--cnb-mono);font-size:11.5px}.cnb-error{display:flex;gap:10px}.cnb-error-line{flex-shrink:0;color:var(--cnb-error)}.cnb-grid{display:flex;flex-direction:column;gap:6px}.cnb-grid-head{margin-top:4px;color:var(--cnb-mute);font-family:var(--cnb-mono);font-size:11px}.cnb-bar{display:grid;gap:2px;align-items:center}.cnb-lane{color:var(--cnb-mute);font-family:var(--cnb-mono);font-size:11px;white-space:nowrap}.cnb-bar-num{font-size:10px}.cnb-cell{height:16px;border-radius:3px;background:color-mix(in srgb,var(--cnb-text) 6%,transparent);color:var(--cnb-paper);font-family:var(--cnb-mono);font-size:10px;font-weight:600;line-height:16px;text-align:center;overflow:hidden}.cnb-alt{background:color-mix(in srgb,var(--cnb-text) 11%,transparent)}.cnb-hit{background:color-mix(in srgb,var(--cnb-accent) 62%,var(--cnb-paper))}.cnb-acc{background:var(--cnb-accent)}.cnb-ghost{opacity:.45}.cnb-cell.cnb-now{outline:1.5px solid var(--cnb-text);outline-offset:-1px}.cnb-count{color:var(--cnb-mute);font-family:var(--cnb-mono);font-size:10px;text-align:center}.cnb-count-beat{color:var(--cnb-text);font-weight:600}.cnb-count.cnb-now{color:var(--cnb-accent);font-weight:700}.cnb-output{display:flex;flex-direction:column;gap:8px}.cnb-output+.cnb-output{margin-top:6px;padding-top:10px;border-top:1px solid var(--cnb-border)}.cnb-output-head{display:flex;flex-wrap:wrap;align-items:baseline;gap:8px}.cnb-play-line{color:var(--cnb-accent);font-family:var(--cnb-mono);font-size:12px;font-weight:600}