songleaf 0.0.2__tar.gz

songleaf-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# 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/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

songleaf-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+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.

songleaf-0.0.2/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: songleaf
+Version: 0.0.2
+Summary: Dense, readable one-page song sheets (lyrics + chords + score snippets) from searchable sources
+Project-URL: Homepage, https://github.com/thorwhalen/songleaf
+Project-URL: Repository, https://github.com/thorwhalen/songleaf
+Project-URL: Documentation, https://thorwhalen.github.io/songleaf
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chords,lead-sheet,lyrics,music,pdf,song-sheet
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Requires-Dist: cw<0.2,>=0.1.4
+Requires-Dist: dol
+Requires-Dist: pandas
+Requires-Dist: rapidfuzz>=3
+Requires-Dist: reportlab>=4
+Requires-Dist: sung>=0.0.26
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# songleaf
+
+Dense, readable one-page song sheets: lyrics and chords on one A4 page, with the lyrics as large as will fit.
+
+```bash
+pip install songleaf
+python -m songleaf sheet "wonderwall oasis"    # -> a one-page PDF in ~/.local/share/songleaf/sheets/
+```
+
+The default source is the Kaggle *chords-and-lyrics* corpus (about 135,000 songs), read from a local copy of its zip (see [Sources](#sources)).
+
+## What the sheet looks like
+
+- **One page, largest type that fits.** The lyric font size is found by search for each song. On 1,500 randomly sampled corpus songs, the median came out around 22 pt, and 1,498 of the 1,500 fit on one page. A song that cannot fit at the minimum size spills onto a second page.
+- **Chords take no line of their own.** They are smaller and blue, start over the syllable they land on, and overlap the tops of the letters of their lyric line.
+- **Lines share rows.** Consecutive lines of a paragraph are packed onto one row, separated by a light `/`. A blank line or a new section starts a new row.
+- **Small labels.** Sections are grey prefixes (`V1`, `Ch`, `Br`); title, artist, capo and key are one small line at the top.
+
+## Command line
+
+```bash
+python -m songleaf search "wonderwall oasis"              # fuzzy: typos and word order don't matter
+python -m songleaf search --artist oasis --lyrics "roads winding"
+python -m songleaf sheet "wonderwall oasis" --output wonderwall.pdf
+python -m songleaf sheet "wonderwall oasis" --pick 2      # the second-best match
+python -m songleaf songs                                  # songs already stored
+python -m songleaf sheet kaggle_chords:1234               # a song by its key: no search
+python -m songleaf sheet kaggle_chords:1234 --refresh     # fetch it again from its source
+```
+
+The `songleaf` console script is the same command.
+
+## Python
+
+```python
+import songleaf
+
+hits = songleaf.search("wonderwall oasis")
+song = songleaf.get_song(hits[0].key)  # a Song: lyrics text + annotations
+songleaf.render_dense_a4(song, "wonderwall.pdf")  # {'font_size': ..., 'pages': 1, ...}
+
+songleaf.sheet("wonderwall oasis")  # search, store and render in one call
+```
+
+## The song model
+
+A `Song` is lyrics text plus *standoff* annotations anchored on character offsets, so annotation layers never touch the text:
+
+- `section`: spans its lines, `{"label": "Chorus"}`;
+- `chord`: a point on the first character of the syllable the chord lands on, `{"symbol": "G/B", "timing": "at"}` (`"before"` marks a chord that sounds ahead of that syllable);
+- `score`: a link from a stretch of lyrics to a score snippet, `{"source", "id", "url", "format"}`.
+
+Metadata (title, artist, capo, key) and provenance (source, id, url, licence) travel with the song, and `Song.to_dict()` is its JSON form.
+
+```python
+from songleaf import Song, chord, section, parse_chords_over_lyrics
+
+song = Song(
+    "Paper boats drift", [section(0, 17, "Verse 1"), chord(0, "G"), chord(6, "D")]
+)
+song = parse_chords_over_lyrics(
+    "G     D\nPaper boats drift"
+)  # the same chords, from a chart
+```
+
+## Storage
+
+Songs are kept in a `MutableMapping` (`songleaf.song_store()`): one JSON file per song under `~/.local/share/songleaf/songs/`. Rendered sheets go to `~/.local/share/songleaf/sheets/`. Set `SONGLEAF_DATA_DIR` to move both.
+
+## Sources
+
+`KaggleChordsSource` reads the [chords-and-lyrics dataset](https://www.kaggle.com/datasets/eitanbentora/chords-and-lyrics-dataset) through `sung`. It needs a local copy of the zip: point `SUNG_CHORDS_AND_LYRICS_ZIP` at it, or keep it where `haggle` downloads it (`$HAGGLE_ROOTDIR/zips/eitanbentora/chords-and-lyrics-dataset.zip`). Without a local copy, `sung` downloads it from Kaggle, which needs Kaggle credentials. The corpus was scraped from a chords site, so keep it to personal use.
+
+Loading the corpus takes about five seconds on the first search in a process.
+
+## Extending
+
+Three keyword arguments are the extension points, on `sheet` (and `search` for sources):
+
+- `sources=`: objects with a `name`, `search(query, *, title, artist, lyrics, limit)` returning `Hit`s, and `get(song_id)` returning a `Song`;
+- `store=`: any `MutableMapping[str, Song]` (a `dict` works);
+- `renderer=`: any `(song, output) -> dict` function.
+
+```python
+songleaf.sheet("paper boats", sources=[my_source], store={}, renderer=my_renderer)
+```

songleaf-0.0.2/README.md

@@ -0,0 +1,86 @@
+# songleaf
+
+Dense, readable one-page song sheets: lyrics and chords on one A4 page, with the lyrics as large as will fit.
+
+```bash
+pip install songleaf
+python -m songleaf sheet "wonderwall oasis"    # -> a one-page PDF in ~/.local/share/songleaf/sheets/
+```
+
+The default source is the Kaggle *chords-and-lyrics* corpus (about 135,000 songs), read from a local copy of its zip (see [Sources](#sources)).
+
+## What the sheet looks like
+
+- **One page, largest type that fits.** The lyric font size is found by search for each song. On 1,500 randomly sampled corpus songs, the median came out around 22 pt, and 1,498 of the 1,500 fit on one page. A song that cannot fit at the minimum size spills onto a second page.
+- **Chords take no line of their own.** They are smaller and blue, start over the syllable they land on, and overlap the tops of the letters of their lyric line.
+- **Lines share rows.** Consecutive lines of a paragraph are packed onto one row, separated by a light `/`. A blank line or a new section starts a new row.
+- **Small labels.** Sections are grey prefixes (`V1`, `Ch`, `Br`); title, artist, capo and key are one small line at the top.
+
+## Command line
+
+```bash
+python -m songleaf search "wonderwall oasis"              # fuzzy: typos and word order don't matter
+python -m songleaf search --artist oasis --lyrics "roads winding"
+python -m songleaf sheet "wonderwall oasis" --output wonderwall.pdf
+python -m songleaf sheet "wonderwall oasis" --pick 2      # the second-best match
+python -m songleaf songs                                  # songs already stored
+python -m songleaf sheet kaggle_chords:1234               # a song by its key: no search
+python -m songleaf sheet kaggle_chords:1234 --refresh     # fetch it again from its source
+```
+
+The `songleaf` console script is the same command.
+
+## Python
+
+```python
+import songleaf
+
+hits = songleaf.search("wonderwall oasis")
+song = songleaf.get_song(hits[0].key)  # a Song: lyrics text + annotations
+songleaf.render_dense_a4(song, "wonderwall.pdf")  # {'font_size': ..., 'pages': 1, ...}
+
+songleaf.sheet("wonderwall oasis")  # search, store and render in one call
+```
+
+## The song model
+
+A `Song` is lyrics text plus *standoff* annotations anchored on character offsets, so annotation layers never touch the text:
+
+- `section`: spans its lines, `{"label": "Chorus"}`;
+- `chord`: a point on the first character of the syllable the chord lands on, `{"symbol": "G/B", "timing": "at"}` (`"before"` marks a chord that sounds ahead of that syllable);
+- `score`: a link from a stretch of lyrics to a score snippet, `{"source", "id", "url", "format"}`.
+
+Metadata (title, artist, capo, key) and provenance (source, id, url, licence) travel with the song, and `Song.to_dict()` is its JSON form.
+
+```python
+from songleaf import Song, chord, section, parse_chords_over_lyrics
+
+song = Song(
+    "Paper boats drift", [section(0, 17, "Verse 1"), chord(0, "G"), chord(6, "D")]
+)
+song = parse_chords_over_lyrics(
+    "G     D\nPaper boats drift"
+)  # the same chords, from a chart
+```
+
+## Storage
+
+Songs are kept in a `MutableMapping` (`songleaf.song_store()`): one JSON file per song under `~/.local/share/songleaf/songs/`. Rendered sheets go to `~/.local/share/songleaf/sheets/`. Set `SONGLEAF_DATA_DIR` to move both.
+
+## Sources
+
+`KaggleChordsSource` reads the [chords-and-lyrics dataset](https://www.kaggle.com/datasets/eitanbentora/chords-and-lyrics-dataset) through `sung`. It needs a local copy of the zip: point `SUNG_CHORDS_AND_LYRICS_ZIP` at it, or keep it where `haggle` downloads it (`$HAGGLE_ROOTDIR/zips/eitanbentora/chords-and-lyrics-dataset.zip`). Without a local copy, `sung` downloads it from Kaggle, which needs Kaggle credentials. The corpus was scraped from a chords site, so keep it to personal use.
+
+Loading the corpus takes about five seconds on the first search in a process.
+
+## Extending
+
+Three keyword arguments are the extension points, on `sheet` (and `search` for sources):
+
+- `sources=`: objects with a `name`, `search(query, *, title, artist, lyrics, limit)` returning `Hit`s, and `get(song_id)` returning a `Song`;
+- `store=`: any `MutableMapping[str, Song]` (a `dict` works);
+- `renderer=`: any `(song, output) -> dict` function.
+
+```python
+songleaf.sheet("paper boats", sources=[my_source], store={}, renderer=my_renderer)
+```

songleaf-0.0.2/pyproject.toml

@@ -0,0 +1,192 @@
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "songleaf"
+version = "0.0.2"
+description = "Dense, readable one-page song sheets (lyrics + chords + score snippets) from searchable sources"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = [
+    "music",
+    "lyrics",
+    "chords",
+    "song-sheet",
+    "lead-sheet",
+    "pdf",
+]
+authors = [
+    { name = "Thor Whalen" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = [
+    "cw>=0.1.4,<0.2",
+    "dol",
+    "pandas",
+    "rapidfuzz>=3",
+    "reportlab>=4",
+    "sung>=0.0.26",
+]
+
+[project.scripts]
+songleaf = "songleaf.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/thorwhalen/songleaf"
+Repository = "https://github.com/thorwhalen/songleaf"
+Documentation = "https://thorwhalen.github.io/songleaf"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+]
+docs = [
+    "sphinx>=6.0",
+    "sphinx-rtd-theme>=1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["songleaf"]
+
+# An allowlist, so a source distribution never ships anything but code, tests and docs.
+[tool.hatch.build.targets.sdist]
+include = [
+    "songleaf/**/*.py",
+    "tests/**/*.py",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+exclude = [
+    "**/*.ipynb",
+    ".git",
+    ".venv",
+    "build",
+    "dist",
+    "tests",
+    "examples",
+    "scrap",
+]
+
+[tool.ruff.lint]
+select = [
+    "D100",
+]
+ignore = [
+    "D203",
+    "E501",
+    "B905",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/*" = [
+    "D",
+]
+"**/examples/*" = [
+    "D",
+]
+"**/scrap/*" = [
+    "D",
+]
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = [
+    "tests",
+]
+doctest_optionflags = [
+    "NORMALIZE_WHITESPACE",
+    "ELLIPSIS",
+]
+
+[tool.wads.ci]
+project_name = ""
+
+[tool.wads.ci.commands]
+pre_test = []
+test = []
+post_test = []
+lint = []
+format = []
+
+[tool.wads.ci.env]
+required_envvars = []
+test_envvars = []
+extra_envvars = []
+
+[tool.wads.ci.env.defaults]
+
+[tool.wads.ci.quality.ruff]
+enabled = true
+
+[tool.wads.ci.quality.black]
+enabled = false
+
+[tool.wads.ci.quality.mypy]
+enabled = false
+
+[tool.wads.ci.testing]
+enabled = true
+python_versions = [
+    "3.10",
+    "3.12",
+]
+pytest_args = [
+    "-v",
+    "--tb=short",
+]
+coverage_enabled = true
+coverage_threshold = 0
+coverage_report_format = [
+    "term",
+    "xml",
+]
+exclude_paths = [
+    "examples",
+    "scrap",
+]
+test_on_windows = true
+
+[tool.wads.ci.metrics]
+enabled = true
+config_path = ".github/umpyre-config.yml"
+storage_branch = "code-metrics"
+python_version = "3.10"
+force_run = false
+
+[tool.wads.ci.build]
+sdist = true
+wheel = true
+
+[tool.wads.ci.publish]
+enabled = true
+skip_ci_marker = "[skip ci]"
+publish_marker = "[publish]"
+
+[tool.wads.ci.docs]
+enabled = true
+builder = "epythet"
+ignore_paths = [
+    "tests/",
+    "scrap/",
+    "examples/",
+]

songleaf-0.0.2/songleaf/__init__.py

@@ -0,0 +1,43 @@
+"""songleaf: dense, readable one-page song sheets from searchable sources.
+
+Find a song, keep it as lyrics plus anchored annotations (sections, chords,
+provenance, score links), and render it onto one A4 page with the lyrics as
+large as will fit.
+
+>>> import songleaf
+>>> song = songleaf.parse_chords_over_lyrics("C       G\\nHello there my friend")
+>>> [a.body["symbol"] for a in song.of_kind("chord")]
+['C', 'G']
+
+From a query to a PDF, on the Kaggle chords-and-lyrics corpus::
+
+    songleaf.sheet("wonderwall oasis")   # -> {'path': '.../sheets/oasis-wonderwall.pdf', ...}
+
+or ``python -m songleaf sheet "wonderwall oasis"``.
+"""
+
+from songleaf.model import Annotation, Song, chord, score_link, section
+from songleaf.parse import parse_chords_over_lyrics
+from songleaf.render import DenseStyle, fit_font_size, render_dense_a4
+from songleaf.sources import Hit, KaggleChordsSource, get_song, search
+from songleaf.store import song_store
+from songleaf.tools import sheet, songs
+
+__all__ = [
+    "Annotation",
+    "DenseStyle",
+    "Hit",
+    "KaggleChordsSource",
+    "Song",
+    "chord",
+    "fit_font_size",
+    "get_song",
+    "parse_chords_over_lyrics",
+    "render_dense_a4",
+    "score_link",
+    "search",
+    "section",
+    "sheet",
+    "song_store",
+    "songs",
+]

songleaf-0.0.2/songleaf/__main__.py

@@ -0,0 +1,55 @@
+# PYTHON_ARGCOMPLETE_OK
+"""``python -m songleaf``: the command line, ``cw`` over :data:`songleaf.tools.TOOLS`.
+
+Examples::
+
+    python -m songleaf search "wonderwall oasis"
+    python -m songleaf sheet "wonderwall oasis"     # -> a one-page A4 PDF
+    python -m songleaf sheet kaggle_chords:1234 --output sheet.pdf
+    python -m songleaf songs
+"""
+
+import functools
+import inspect
+
+import cw
+
+from songleaf import tools
+
+#: Dependency-injection parameters: seams for library callers, not CLI options.
+_SEAMS = ("sources", "store", "renderer")
+
+
+def _with_expected_errors(tool):
+    """A failure the user can act on becomes one line on stderr, not a traceback."""
+
+    @functools.wraps(tool)
+    def command(*args, **kwargs):
+        try:
+            return tool(*args, **kwargs)
+        except (LookupError, RuntimeError, ValueError) as error:
+            raise cw.CommandError(str(error)) from error
+
+    return command
+
+
+def main(argv=None):
+    """Run one songleaf command."""
+    config = {
+        tool.__name__: {
+            name: cw.HIDE
+            for name in _SEAMS
+            if name in inspect.signature(tool).parameters
+        }
+        for tool in tools.TOOLS
+    }
+    commands = [_with_expected_errors(tool) for tool in tools.TOOLS]
+    raise SystemExit(
+        cw.dispatch(
+            commands, argv, prog="songleaf", convention=cw.MODERN, config=config
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()