scoreseek 0.0.2__tar.gz

scoreseek-0.0.2/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+.DS_Store
+*.abc
+*.wav
+scrap/
+.claude/

scoreseek-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.

scoreseek-0.0.2/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: scoreseek
+Version: 0.0.2
+Summary: Find a musical score by metadata across pluggable sources (APIs, datasets, local folders)
+Project-URL: Homepage, https://github.com/thorwhalen/scoreseek
+Project-URL: Repository, https://github.com/thorwhalen/scoreseek
+Project-URL: Documentation, https://thorwhalen.github.io/scoreseek
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: abc,midi,music,musicxml,public-domain,score,search,sheet-music
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+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'
+Provides-Extra: render
+Requires-Dist: audiate; extra == 'render'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# scoreseek
+
+Find a musical **score** by metadata — across many sources, behind one call.
+
+```python
+import scoreseek
+
+hits = scoreseek.search("Cooley's")  # out of the box: The Session (CC-BY-SA)
+ref = hits[0]
+path = ref.fetch()  # -> a local .abc file
+# hand straight to audiate.render(path) to hear it
+```
+
+Every hit is a license-tagged `ScoreRef`, so **public-domain / permissive**
+results stay cleanly separated from **copyrighted / gray** ones — searches are
+copyright-safe by default.
+
+## Install
+
+```bash
+pip install scoreseek                # zero required dependencies
+pip install "scoreseek[render]"      # + audiate, to render hits to audio
+```
+
+## Why
+
+Scores live in many places — public-domain corpora (PDMX, IMSLP, OpenScore),
+downloadable datasets, chord/lyric collections, and your own folders. `scoreseek`
+puts them behind **one pluggable-source interface** and tags every result with a
+license, so you can ask for "only what I can legally build on" or opt into
+copyrighted material explicitly.
+
+## Sources
+
+A *source* answers `search(query) -> [ScoreRef]` and optionally `fetch(ref) -> path`.
+Register any object with that shape.
+
+| Source | What | License | Status |
+|---|---|---|---|
+| `thesession` | thesession.org traditional tunes (ABC) | CC-BY-SA 4.0 | **built in, on by default** |
+| `LocalFolderSource` | a folder of `.mid`/MusicXML/ABC/`kern` files | you set it | built in |
+| PDMX · OpenScore Lieder · IMSLP · MusicBrainz (normalizer) | public-domain / CC0 corpora + APIs | PD/CC0 | planned |
+
+```python
+from scoreseek import register_source, License
+from scoreseek.sources import LocalFolderSource
+
+register_source(LocalFolderSource("~/scores", license=License.PUBLIC_DOMAIN))
+
+hits = scoreseek.search("prelude", sources=["local"])
+hits = scoreseek.search("hey jude", allow_copyrighted=True)  # opt into gray/copyrighted
+```
+
+### Write your own source
+
+```python
+from scoreseek.sources import Source
+from scoreseek.base import License
+
+
+class MySource(Source):
+    name = "mine"
+    license = License.CC0
+
+    def search(self, query="", *, title="", composer="", limit=10):
+        return [self._ref(title="...", id="...", formats=("musicxml",))]
+
+    def fetch(self, ref, *, fmt=None):
+        ...
+        return "/path/to/score.musicxml"
+```
+
+## License tags
+
+`License` classifies each hit: `PUBLIC_DOMAIN`, `CC0`, `PERMISSIVE` (CC-BY/-SA,
+MIT, …), `NONCOMMERCIAL` (CC-BY-NC), `COPYRIGHTED`, `GRAY` (scrapes/unspecified),
+`UNKNOWN`. `search(..., allow_copyrighted=False)` (the default) drops
+`COPYRIGHTED` and `GRAY` hits.
+
+## Where it fits
+
+`scoreseek` is the **search** stage of a larger pipeline:
+**scoreseek** (find a score) → [`audiate`](https://github.com/thorwhalen/audiate)
+(render to audio) → [`arioso`](https://github.com/thorwhalen/arioso)
+(AI-enhance).
+
+## License
+
+MIT

scoreseek-0.0.2/README.md

@@ -0,0 +1,89 @@
+# scoreseek
+
+Find a musical **score** by metadata — across many sources, behind one call.
+
+```python
+import scoreseek
+
+hits = scoreseek.search("Cooley's")  # out of the box: The Session (CC-BY-SA)
+ref = hits[0]
+path = ref.fetch()  # -> a local .abc file
+# hand straight to audiate.render(path) to hear it
+```
+
+Every hit is a license-tagged `ScoreRef`, so **public-domain / permissive**
+results stay cleanly separated from **copyrighted / gray** ones — searches are
+copyright-safe by default.
+
+## Install
+
+```bash
+pip install scoreseek                # zero required dependencies
+pip install "scoreseek[render]"      # + audiate, to render hits to audio
+```
+
+## Why
+
+Scores live in many places — public-domain corpora (PDMX, IMSLP, OpenScore),
+downloadable datasets, chord/lyric collections, and your own folders. `scoreseek`
+puts them behind **one pluggable-source interface** and tags every result with a
+license, so you can ask for "only what I can legally build on" or opt into
+copyrighted material explicitly.
+
+## Sources
+
+A *source* answers `search(query) -> [ScoreRef]` and optionally `fetch(ref) -> path`.
+Register any object with that shape.
+
+| Source | What | License | Status |
+|---|---|---|---|
+| `thesession` | thesession.org traditional tunes (ABC) | CC-BY-SA 4.0 | **built in, on by default** |
+| `LocalFolderSource` | a folder of `.mid`/MusicXML/ABC/`kern` files | you set it | built in |
+| PDMX · OpenScore Lieder · IMSLP · MusicBrainz (normalizer) | public-domain / CC0 corpora + APIs | PD/CC0 | planned |
+
+```python
+from scoreseek import register_source, License
+from scoreseek.sources import LocalFolderSource
+
+register_source(LocalFolderSource("~/scores", license=License.PUBLIC_DOMAIN))
+
+hits = scoreseek.search("prelude", sources=["local"])
+hits = scoreseek.search("hey jude", allow_copyrighted=True)  # opt into gray/copyrighted
+```
+
+### Write your own source
+
+```python
+from scoreseek.sources import Source
+from scoreseek.base import License
+
+
+class MySource(Source):
+    name = "mine"
+    license = License.CC0
+
+    def search(self, query="", *, title="", composer="", limit=10):
+        return [self._ref(title="...", id="...", formats=("musicxml",))]
+
+    def fetch(self, ref, *, fmt=None):
+        ...
+        return "/path/to/score.musicxml"
+```
+
+## License tags
+
+`License` classifies each hit: `PUBLIC_DOMAIN`, `CC0`, `PERMISSIVE` (CC-BY/-SA,
+MIT, …), `NONCOMMERCIAL` (CC-BY-NC), `COPYRIGHTED`, `GRAY` (scrapes/unspecified),
+`UNKNOWN`. `search(..., allow_copyrighted=False)` (the default) drops
+`COPYRIGHTED` and `GRAY` hits.
+
+## Where it fits
+
+`scoreseek` is the **search** stage of a larger pipeline:
+**scoreseek** (find a score) → [`audiate`](https://github.com/thorwhalen/audiate)
+(render to audio) → [`arioso`](https://github.com/thorwhalen/arioso)
+(AI-enhance).
+
+## License
+
+MIT

scoreseek-0.0.2/pyproject.toml

@@ -0,0 +1,173 @@
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "scoreseek"
+version = "0.0.2"
+description = "Find a musical score by metadata across pluggable sources (APIs, datasets, local folders)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = [
+    "music",
+    "score",
+    "sheet-music",
+    "search",
+    "musicxml",
+    "midi",
+    "abc",
+    "public-domain",
+]
+authors = [
+    { name = "Thor Whalen" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/thorwhalen/scoreseek"
+Repository = "https://github.com/thorwhalen/scoreseek"
+Documentation = "https://thorwhalen.github.io/scoreseek"
+
+[project.optional-dependencies]
+render = [
+    "audiate",
+]
+test = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+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 = ["scoreseek"]
+
+[tool.hatch.build]
+include = [
+    "scoreseek/**/*.py",
+]
+
+[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",
+]
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = [
+    "tests",
+]
+
+[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.install]
+extras = "test"
+
+[tool.wads.ci.testing]
+python_versions = [
+    "3.10",
+    "3.12",
+]
+pytest_args = [
+    "-v",
+    "--tb=short",
+    "tests",
+]
+skip_doctests = true
+coverage_enabled = true
+coverage_threshold = 0
+coverage_report_format = [
+    "term",
+    "xml",
+]
+exclude_paths = [
+    "examples",
+    "scrap",
+]
+test_on_windows = false
+
+[tool.wads.ci.build]
+sdist = true
+wheel = true
+
+[tool.wads.ci.publish]
+enabled = true
+
+[tool.wads.ci.docs]
+enabled = false
+builder = "epythet"
+ignore_paths = [
+    "tests/",
+    "scrap/",
+    "examples/",
+]

scoreseek-0.0.2/scoreseek/__init__.py

@@ -0,0 +1,120 @@
+"""scoreseek -- find a musical score by metadata, across pluggable sources.
+
+Search many score sources (APIs, downloadable datasets, local folders) through
+one call and get back license-tagged :class:`~scoreseek.base.ScoreRef` hits you
+can :meth:`~scoreseek.base.ScoreRef.fetch` on demand. Every hit carries a
+:class:`~scoreseek.base.License` tag, so copyright-free / permissive results stay
+cleanly separated from copyrighted-user-upload or gray results.
+
+Simple things simple::
+
+    import scoreseek
+
+    hits = scoreseek.search("Cooley's")          # out-of-the-box: The Session
+    ref = hits[0]
+    path = ref.fetch()                            # -> a local .abc file
+    # -> hand straight to audiate.render(path)
+
+Complex things possible::
+
+    from scoreseek import register_source, License
+    from scoreseek.sources import LocalFolderSource
+
+    register_source(LocalFolderSource("~/my_scores", license=License.PUBLIC_DOMAIN))
+    hits = scoreseek.search("prelude", sources=["local"], allow_copyrighted=False)
+
+This is the **search** stage of a larger song->score->audio->AI-enhanced
+pipeline (render = ``audiate``, AI-enhance = ``arioso``).
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from scoreseek.base import (
+    COMMERCIAL_SAFE,
+    RESTRICTED,
+    License,
+    ScoreRef,
+)
+
+# NOTE: exposed as ``source_registry`` (not ``sources``) on purpose -- the name
+# ``scoreseek.sources`` belongs to the sources *subpackage* (the source classes),
+# so binding the registry there would shadow it.
+from scoreseek.registry import (
+    SourceRegistry,
+    register_source,
+    sources as source_registry,
+)
+
+__all__ = [
+    "search",
+    "list_sources",
+    "register_source",
+    "source_registry",
+    "ScoreRef",
+    "License",
+    "SourceRegistry",
+]
+
+
+def _install_default_sources() -> None:
+    """Register the zero-config out-of-the-box source(s)."""
+    if "thesession" not in source_registry:
+        from scoreseek.sources.thesession import TheSessionSource
+
+        register_source(TheSessionSource())
+
+
+_install_default_sources()
+
+
+def list_sources() -> list:
+    """Return the names of the registered score sources (sorted)."""
+    return sorted(source_registry)
+
+
+def search(
+    query: str = "",
+    *,
+    title: str = "",
+    composer: str = "",
+    sources: Optional[List[str]] = None,
+    allow_copyrighted: bool = False,
+    limit: int = 10,
+) -> List[ScoreRef]:
+    """Search registered sources and return license-filtered, ranked hits.
+
+    Args:
+        query: Free-text query (matched against title/composer per source).
+        title: Restrict to a title (source-dependent).
+        composer: Restrict to a composer/artist (source-dependent).
+        sources: Names of sources to query; ``None`` queries all registered.
+        allow_copyrighted: If ``False`` (default), copyrighted/gray-licensed hits
+            (see :data:`~scoreseek.base.RESTRICTED`) are dropped -- so results are
+            safe to redistribute/build on. Set ``True`` to include them.
+        limit: Max hits per source.
+
+    Returns:
+        A list of :class:`~scoreseek.base.ScoreRef`, best match first.
+    """
+    from scoreseek.registry import sources as _registry
+
+    names = sources if sources is not None else list(_registry)
+    hits: List[ScoreRef] = []
+    for name in names:
+        source = _registry[name]  # raises KeyError with a helpful message
+        try:
+            found = source.search(query, title=title, composer=composer, limit=limit)
+        except Exception as e:  # a flaky source shouldn't sink the whole search
+            import warnings
+
+            warnings.warn(f"source {name!r} failed: {e}", stacklevel=2)
+            continue
+        hits.extend(found)
+
+    if not allow_copyrighted:
+        hits = [h for h in hits if h.license not in RESTRICTED]
+
+    hits.sort(key=lambda h: h.score, reverse=True)
+    return hits

scoreseek-0.0.2/scoreseek/base.py

@@ -0,0 +1,84 @@
+"""Core types for scoreseek: :class:`ScoreRef`, :class:`License`, and the
+license-partitioning constants.
+
+A search returns :class:`ScoreRef` hits -- lightweight, license-tagged pointers
+to a score that can be :meth:`ScoreRef.fetch`-ed on demand. The **license tag on
+every hit** is the load-bearing design choice: it lets the facade keep
+public-domain / permissive results cleanly separated from copyrighted-user-upload
+or gray-licensed results (see :data:`COMMERCIAL_SAFE` / :data:`RESTRICTED`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class License(str, Enum):
+    """A coarse license classification for a score, driving safe filtering."""
+
+    PUBLIC_DOMAIN = "public_domain"
+    CC0 = "cc0"
+    PERMISSIVE = "permissive"  # CC-BY, MIT, BSD, Apache, CC-BY-SA, ...
+    NONCOMMERCIAL = "noncommercial"  # CC-BY-NC(-*)
+    COPYRIGHTED = "copyrighted"  # all rights reserved (e.g. user uploads)
+    GRAY = "gray"  # scraped / unspecified terms
+    UNKNOWN = "unknown"
+
+
+#: License tags safe to build products on (redistribution + commercial, w/ attribution).
+COMMERCIAL_SAFE = frozenset({License.PUBLIC_DOMAIN, License.CC0, License.PERMISSIVE})
+
+#: License tags that are copyrighted or gray -- gated behind ``allow_copyrighted``.
+RESTRICTED = frozenset({License.COPYRIGHTED, License.GRAY})
+
+
+@dataclass
+class ScoreRef:
+    """A license-tagged pointer to a score returned by a search.
+
+    Attributes:
+        title: Score/song title.
+        source: Name of the source that produced this hit.
+        id: Source-specific identifier.
+        composer: Composer or artist.
+        formats: Available formats, e.g. ``("musicxml", "midi")``.
+        license: A :class:`License` classification.
+        url: A human-facing URL for the score, if any.
+        score: Match relevance in ``[0, 1]``.
+        metadata: Source-specific extra fields.
+    """
+
+    title: str
+    source: str
+    id: str = ""
+    composer: str = ""
+    formats: tuple = ()
+    license: License = License.UNKNOWN
+    url: str = ""
+    score: float = 0.0
+    metadata: dict = field(default_factory=dict)
+    _source_obj: Any = field(default=None, repr=False, compare=False)
+
+    @property
+    def is_commercial_safe(self) -> bool:
+        """True if this score's license permits redistribution/commercial use."""
+        return self.license in COMMERCIAL_SAFE
+
+    def fetch(self, *, fmt: Optional[str] = None):
+        """Retrieve the score content (returns a filesystem path).
+
+        Delegates to the originating source. The returned path can be handed
+        straight to ``audiate.render(...)``.
+
+        Raises:
+            NotImplementedError: If the originating source can't fetch (e.g. a
+                metadata-only source, or a bare ``ScoreRef`` with no source).
+        """
+        if self._source_obj is None or not hasattr(self._source_obj, "fetch"):
+            raise NotImplementedError(
+                f"ScoreRef {self.title!r} from source {self.source!r} cannot be "
+                "fetched (no fetch-capable source attached)."
+            )
+        return self._source_obj.fetch(self, fmt=fmt)

scoreseek-0.0.2/scoreseek/registry.py

@@ -0,0 +1,57 @@
+"""Pluggable score-source registry.
+
+A *source* answers ``search(query, ...) -> list[ScoreRef]`` and, optionally,
+``fetch(ref, ...) -> path``. Sources live in a :class:`SourceRegistry` (a
+``MutableMapping`` of ``name -> source``) so the set is open for extension: a
+downloadable-dataset source, an API source, or a local folder are all just
+objects registered here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+
+
+class SourceRegistry(MutableMapping):
+    """A ``MutableMapping`` of source name -> source object."""
+
+    def __init__(self):
+        self._d: dict = {}
+
+    def __getitem__(self, key):
+        try:
+            return self._d[key]
+        except KeyError:
+            raise KeyError(
+                f"Unknown source {key!r}. Registered sources: {sorted(self._d)}"
+            ) from None
+
+    def __setitem__(self, key, value):
+        self._d[key] = value
+
+    def __delitem__(self, key):
+        del self._d[key]
+
+    def __iter__(self):
+        return iter(self._d)
+
+    def __len__(self):
+        return len(self._d)
+
+
+#: The process-wide registry of score sources.
+sources = SourceRegistry()
+
+
+def register_source(source, *, name: str = None):
+    """Register a *source* object (must have a ``.name`` unless ``name`` given).
+
+    Returns the source, so it can be used inline::
+
+        local = register_source(LocalFolderSource("~/scores"))
+    """
+    key = name or getattr(source, "name", None)
+    if not key:
+        raise ValueError("source has no 'name'; pass name=... to register_source")
+    sources[key] = source
+    return source

scoreseek-0.0.2/scoreseek/sources/__init__.py

@@ -0,0 +1,11 @@
+"""Built-in score sources.
+
+Importing this package makes the built-in source classes available and (via
+:mod:`scoreseek`) registers the default out-of-the-box source (The Session).
+"""
+
+from scoreseek.sources.base import Source
+from scoreseek.sources.local import LocalFolderSource
+from scoreseek.sources.thesession import TheSessionSource
+
+__all__ = ["Source", "LocalFolderSource", "TheSessionSource"]

scoreseek-0.0.2/scoreseek/sources/base.py

@@ -0,0 +1,56 @@
+"""The ``Source`` base class that all score sources implement.
+
+A source turns a query into :class:`~scoreseek.base.ScoreRef` hits and can
+optionally fetch a hit's content. Subclass and implement :meth:`search` (and
+:meth:`fetch` if the source hands back real files).
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from scoreseek.base import License, ScoreRef
+
+
+class Source:
+    """Base class for a score source.
+
+    Attributes:
+        name: Unique registry name.
+        license: Default :class:`~scoreseek.base.License` for this source's hits
+            (individual hits may override).
+    """
+
+    name: str = "source"
+    license: License = License.UNKNOWN
+
+    def search(
+        self,
+        query: str = "",
+        *,
+        title: str = "",
+        composer: str = "",
+        limit: int = 10,
+    ) -> List[ScoreRef]:
+        """Return up to ``limit`` :class:`ScoreRef` hits for the query.
+
+        Subclasses must implement this.
+        """
+        raise NotImplementedError
+
+    def fetch(self, ref: ScoreRef, *, fmt: Optional[str] = None) -> str:
+        """Retrieve ``ref``'s content and return a filesystem path.
+
+        Subclasses that can deliver content override this; the default raises.
+        """
+        raise NotImplementedError(
+            f"Source {self.name!r} is metadata-only and cannot fetch content."
+        )
+
+    def _ref(self, **kwargs) -> ScoreRef:
+        """Build a :class:`ScoreRef` for this source (fills in source/license)."""
+        kwargs.setdefault("source", self.name)
+        kwargs.setdefault("license", self.license)
+        ref = ScoreRef(**kwargs)
+        ref._source_obj = self
+        return ref

scoreseek-0.0.2/scoreseek/sources/local.py

@@ -0,0 +1,110 @@
+"""A local-folder score source: index and search a directory of score files.
+
+Zero network, zero external services -- point it at a folder of ``.mid`` /
+MusicXML / ABC / ``kern`` files and search by filename. Fetching returns the
+file path (ready for ``audiate.render``). This is the simplest possible source
+and the reference implementation of the :class:`~scoreseek.sources.base.Source`
+contract.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import List, Optional
+
+from scoreseek.base import License, ScoreRef
+from scoreseek.sources.base import Source
+
+#: File extensions treated as scores, mapped to a format label.
+_SCORE_EXTS = {
+    ".mid": "midi",
+    ".midi": "midi",
+    ".xml": "musicxml",
+    ".musicxml": "musicxml",
+    ".mxl": "musicxml",
+    ".abc": "abc",
+    ".krn": "kern",
+    ".kern": "kern",
+    ".mei": "mei",
+}
+
+
+class LocalFolderSource(Source):
+    """Search a local folder of score files by filename.
+
+    Args:
+        root: Directory to index (searched recursively).
+        name: Registry name (default ``'local'``).
+        license: License tag to attach to every hit (default ``UNKNOWN`` -- set
+            it if you know the folder's provenance, e.g. ``License.PUBLIC_DOMAIN``
+            for a PD corpus).
+    """
+
+    def __init__(
+        self,
+        root,
+        *,
+        name: str = "local",
+        license: License = License.UNKNOWN,
+    ):
+        self.name = name
+        self.license = license
+        self.root = Path(os.path.expanduser(str(root)))
+        self._index: List[dict] = []
+        self.reindex()
+
+    def reindex(self) -> int:
+        """(Re)build the file index. Returns the number of scores found."""
+        self._index = []
+        if not self.root.exists():
+            return 0
+        for dirpath, _dirs, files in os.walk(self.root):
+            for fname in files:
+                ext = os.path.splitext(fname)[1].lower()
+                fmt = _SCORE_EXTS.get(ext)
+                if fmt is None:
+                    continue
+                full = os.path.join(dirpath, fname)
+                self._index.append(
+                    {
+                        "title": os.path.splitext(fname)[0],
+                        "path": full,
+                        "format": fmt,
+                        "rel": os.path.relpath(full, self.root),
+                    }
+                )
+        return len(self._index)
+
+    def search(
+        self,
+        query: str = "",
+        *,
+        title: str = "",
+        composer: str = "",
+        limit: int = 10,
+    ) -> List[ScoreRef]:
+        """Substring-match the query against each file's title and relative path."""
+        needles = [t.lower() for t in (query, title, composer) if t]
+        hits = []
+        for entry in self._index:
+            haystack = (entry["title"] + " " + entry["rel"]).lower()
+            if all(n in haystack for n in needles):
+                hits.append(
+                    self._ref(
+                        title=entry["title"],
+                        id=entry["rel"],
+                        formats=(entry["format"],),
+                        score=1.0 if needles else 0.5,
+                        url=entry["path"],
+                        metadata={"path": entry["path"]},
+                    )
+                )
+        return hits[:limit]
+
+    def fetch(self, ref: ScoreRef, *, fmt: Optional[str] = None) -> str:
+        """Return the score file's path (fetching a local file is a no-op)."""
+        path = ref.metadata.get("path")
+        if not path or not os.path.exists(path):
+            raise FileNotFoundError(f"Score file for {ref.title!r} not found: {path!r}")
+        return path

scoreseek-0.0.2/scoreseek/sources/thesession.py

@@ -0,0 +1,108 @@
+"""The Session (thesession.org) source: Irish/folk traditional tunes in ABC.
+
+A real, zero-config, no-auth source with a clean JSON API and openly-licensed
+content (CC-BY-SA 4.0). Search returns tune references; fetching writes a valid
+ABC file (ready for ``audiate.render``). Networking uses only the standard
+library, so scoreseek's core needs no third-party HTTP dependency.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import urllib.parse
+import urllib.request
+from typing import List, Optional
+
+from scoreseek.base import License, ScoreRef
+from scoreseek.sources.base import Source
+
+_BASE = "https://thesession.org"
+_UA = "scoreseek/0.0.1 (+https://github.com/thorwhalen/scoreseek)"
+
+#: tune "type" -> a sensible default meter (for cleaner ABC rendering).
+_METER = {
+    "reel": "4/4",
+    "jig": "6/8",
+    "slip jig": "9/8",
+    "hornpipe": "4/4",
+    "polka": "2/4",
+    "slide": "12/8",
+    "waltz": "3/4",
+    "march": "4/4",
+    "strathspey": "4/4",
+    "barndance": "4/4",
+    "mazurka": "3/4",
+    "three-two": "3/2",
+}
+
+
+class TheSessionSource(Source):
+    """Search thesession.org's traditional-tune database (ABC, CC-BY-SA 4.0)."""
+
+    name = "thesession"
+    license = License.PERMISSIVE  # CC-BY-SA 4.0
+
+    def __init__(self, *, timeout: float = 15.0):
+        self.timeout = timeout
+
+    def _get_json(self, url: str) -> dict:
+        req = urllib.request.Request(
+            url, headers={"User-Agent": _UA, "Accept": "application/json"}
+        )
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+
+    def search(
+        self,
+        query: str = "",
+        *,
+        title: str = "",
+        composer: str = "",
+        limit: int = 10,
+    ) -> List[ScoreRef]:
+        """Search tunes by name. Returns ABC-format :class:`ScoreRef` hits."""
+        q = query or title or composer
+        if not q:
+            return []
+        url = f"{_BASE}/tunes/search?" + urllib.parse.urlencode(
+            {"q": q, "format": "json", "perpage": limit}
+        )
+        data = self._get_json(url)
+        hits = []
+        for tune in data.get("tunes", [])[:limit]:
+            hits.append(
+                self._ref(
+                    title=tune.get("name", ""),
+                    id=str(tune.get("id", "")),
+                    composer="traditional",
+                    formats=("abc",),
+                    url=tune.get("url", ""),
+                    score=1.0,
+                    metadata={"type": tune.get("type", "")},
+                )
+            )
+        return hits
+
+    def fetch(self, ref: ScoreRef, *, fmt: Optional[str] = None) -> str:
+        """Fetch the tune's first ABC setting and write it to a temp ``.abc`` file."""
+        data = self._get_json(f"{_BASE}/tunes/{ref.id}?format=json")
+        settings = data.get("settings") or []
+        if not settings:
+            raise RuntimeError(f"No ABC settings for tune {ref.id!r} on thesession.org")
+        setting = settings[0]
+        name = data.get("name", ref.title)
+        tune_type = data.get("type", ref.metadata.get("type", ""))
+        header = f"X:1\nT:{name}\n"
+        if tune_type in _METER:
+            header += f"M:{_METER[tune_type]}\n"
+        if setting.get("key"):
+            header += f"K:{setting['key']}\n"
+        abc = header + (setting.get("abc", "") or "").replace("\r\n", "\n")
+
+        fd, path = tempfile.mkstemp(suffix=".abc")
+        os.close(fd)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(abc)
+        return path