Deprecate Dataset.load_* (#528)

* closes #526

docs/requirements.txt

@@ -5,3 +5,4 @@ chardet
 librosa>=0.7.0
 tqdm
 sphinx==3.4.0
+Deprecated>=1.2.13

docs/source/contributing.rst

@@ -768,13 +768,6 @@ the ``_track metadata`` for ``track_id=track2`` will be:
     }
 
 
-Load methods vs Track properties
---------------------------------
-Track properties and cached properties should be trivial, and directly call a ``load_*`` method.
-There should be no additional logic in a track property/cached property, and instead all logic
-should be done in the load method. We separate these because the track properties are only usable
-when data is available locally - when data is remote, the load methods are used instead.
-
 Missing Data
 ------------
 If a Track has a property, for example a type of annotation, that is present for some tracks and not others,
@@ -800,12 +793,6 @@ This decorator is used for children of the Dataset class, and
 copies the Attributes from the parent class to the docstring of the child.
 This gives us clear and complete docs without a lot of copy-paste.
 
-copy_docs
----------
-This decorator is used mainly for a dataset's ``load_`` functions, which
-are attached to a loader's Dataset class. The attached function is identical,
-and this decorator simply copies the docstring from another function.
-
 coerce_to_bytes_io/coerce_to_string_io
 --------------------------------------
 These are two decorators used to simplify the loading of various ``Track`` members

docs/source/contributing_examples/example.py

@@ -14,15 +14,15 @@
 
 """
 import csv
-import logging
 import json
 import os
 from typing import BinaryIO, Optional, TextIO, Tuple
 
-import librosa
-import numpy as np
 # -- import whatever you need here and remove
 # -- example imports you won't use
+import librosa
+import numpy as np
+from smart_open import open  # if you use the open function, make sure you include this line!
 
 from mirdata import download_utils, jams_utils, core, annotations
 
@@ -94,7 +94,8 @@ class Track(core.Track):
         track_id (str): track id of the track
 
     Attributes:
-        track_id (str): track id
+        audio_path (str): path to audio file
+        annotation_path (str): path to annotation file
         # -- Add any of the dataset specific attributes here
 
     Cached Properties:
@@ -310,17 +311,6 @@ def __init__(self, data_home=None, version="default"):
             license_info=LICENSE_INFO,
         )
 
-    # -- Copy any loaders you wrote that should be part of the Dataset class
-    # -- use this core.copy_docs decorator to copy the docs from the original
-    # -- load_ function
-    @core.copy_docs(load_audio)
-    def load_audio(self, *args, **kwargs):
-        return load_audio(*args, **kwargs)
-
-    @core.copy_docs(load_annotation)
-    def load_annotation(self, *args, **kwargs):
-        return load_annotation(*args, **kwargs)
-
     # -- if your dataset has a top-level metadata file, write a loader for it here
     # -- you do not have to include this function if there is no metadata 
     @core.cached_property

mirdata/annotations.py

@@ -4,6 +4,7 @@
 import re
 from typing import List, Optional, Tuple
 
+from deprecated.sphinx import deprecated
 from jams.schema import namespace
 import librosa
 import numpy as np
@@ -809,8 +810,8 @@ def __init__(
     @property
     def notes(self) -> np.ndarray:
         logging.warning(
-            "Deprecation warning: NoteData.notes will be removed in a future version."
-            + "Use NoteData.pitches"
+            "NoteData.notes is deprecated as of 0.3.4 and will be removed in a future version. Use"
+            " NoteData.pitches."
         )
         return self.pitches
 
@@ -1120,8 +1121,8 @@ def __init__(
     @property
     def pronunciations(self):
         logging.warning(
-            "LyricData.pronunciations will be removed in a future version. "
-            + "Use LyricData.lyrics"
+            "LyricData.pronunciations is deprecated as of 0.3.4 and will be removed in a future"
+            " version. Use LyricData.lyrics."
         )
         return self.lyrics
 
@@ -1169,7 +1170,8 @@ def __init__(
     @property
     def value(self):
         logging.warning(
-            "Deprecation warning: TempoData.value will be removed in future versions. Use TempoData.tempos instead."
+            "TempoData.value is deprecated as of 0.3.4 and will be removed in a future version. Use"
+            " TempoData.tempos."
         )
         return self.tempos
 

mirdata/core.py

@@ -67,18 +67,6 @@ def inherit(obj):
     return inherit
 
 
-def copy_docs(original):
-    """
-    Decorator function to copy docs from one function to another
-    """
-
-    def wrapper(target):
-        target.__doc__ = original.__doc__
-        return target
-
-    return wrapper
-
-
 ##### Core Classes #####
 
 

mirdata/datasets/acousticbrainz_genre.py

@@ -38,9 +38,10 @@
     grant agreement No 688382 AudioCommons.
 
 """
-
 import json
 
+from deprecated.sphinx import deprecated
+
 from mirdata import download_utils, core, io
 from mirdata import jams_utils
 
@@ -71,7 +72,9 @@
 REMOTES = {
     "index": download_utils.RemoteFileMetadata(
         filename="acousticbrainz_genre_index.json.zip",
-        url="https://zenodo.org/record/4298580/files/acousticbrainz_genre_index.json.zip?download=1",
+        url=(
+            "https://zenodo.org/record/4298580/files/acousticbrainz_genre_index.json.zip?download=1"
+        ),
         checksum="810f1c003f53cbe58002ba96e6d4d138",
     ),
     "validation-01": download_utils.RemoteFileMetadata(
@@ -412,7 +415,10 @@ def __init__(self, data_home=None, version="default"):
             license_info=LICENSE_INFO,
         )
 
-    @core.copy_docs(load_extractor)
+    @deprecated(
+        reason="Use mirdata.datasets.acousticbrainz_genre.load_extractor",
+        version="0.3.4",
+    )
     def load_extractor(self, *args, **kwargs):
         return load_extractor(*args, **kwargs)
 

mirdata/datasets/beatles.py

@@ -13,6 +13,7 @@
 import os
 from typing import BinaryIO, Optional, TextIO, Tuple
 
+from deprecated.sphinx import deprecated
 import librosa
 import numpy as np
 
@@ -309,18 +310,30 @@ def __init__(self, data_home=None, version="default"):
             license_info=LICENSE_INFO,
         )
 
-    @core.copy_docs(load_audio)
+    @deprecated(
+        reason="Use mirdata.datasets.beatles.load_audio",
+        version="0.3.4",
+    )
     def load_audio(self, *args, **kwargs):
         return load_audio(*args, **kwargs)
 
-    @core.copy_docs(load_beats)
+    @deprecated(
+        reason="Use mirdata.datasets.beatles.load_beats",
+        version="0.3.4",
+    )
     def load_beats(self, *args, **kwargs):
         return load_beats(*args, **kwargs)
 
-    @core.copy_docs(load_chords)
+    @deprecated(
+        reason="Use mirdata.datasets.beatles.load_chords",
+        version="0.3.4",
+    )
     def load_chords(self, *args, **kwargs):
         return load_chords(*args, **kwargs)
 
-    @core.copy_docs(load_sections)
+    @deprecated(
+        reason="Use mirdata.datasets.beatles.load_sections",
+        version="0.3.4",
+    )
     def load_sections(self, *args, **kwargs):
         return load_sections(*args, **kwargs)

mirdata/datasets/beatport_key.py

@@ -27,8 +27,9 @@
 import os
 import fnmatch
 import json
-import librosa
 
+from deprecated.sphinx import deprecated
+import librosa
 from smart_open import open
 
 from mirdata import core, download_utils, jams_utils, io
@@ -269,23 +270,38 @@ def __init__(self, data_home=None, version="default"):
             license_info=LICENSE_INFO,
         )
 
-    @core.copy_docs(load_audio)
+    @deprecated(
+        reason="Use mirdata.datasets.beatport_key.load_audio",
+        version="0.3.4",
+    )
     def load_audio(self, *args, **kwargs):
         return load_audio(*args, **kwargs)
 
-    @core.copy_docs(load_key)
+    @deprecated(
+        reason="Use mirdata.datasets.beatport_key.load_key",
+        version="0.3.4",
+    )
     def load_key(self, *args, **kwargs):
         return load_key(*args, **kwargs)
 
-    @core.copy_docs(load_tempo)
+    @deprecated(
+        reason="Use mirdata.datasets.beatport_key.load_tempo",
+        version="0.3.4",
+    )
     def load_tempo(self, *args, **kwargs):
         return load_tempo(*args, **kwargs)
 
-    @core.copy_docs(load_genre)
+    @deprecated(
+        reason="Use mirdata.datasets.beatport_key.load_genre",
+        version="0.3.4",
+    )
     def load_genre(self, *args, **kwargs):
         return load_genre(*args, **kwargs)
 
-    @core.copy_docs(load_artist)
+    @deprecated(
+        reason="Use mirdata.datasets.beatport_key.load_artist",
+        version="0.3.4",
+    )
     def load_artist(self, *args, **kwargs):
         return load_artist(*args, **kwargs)
 

mirdata/datasets/billboard.py

@@ -13,6 +13,7 @@
 import re
 from typing import BinaryIO, TextIO, Optional, Tuple, Dict, List
 
+from deprecated.sphinx import deprecated
 import librosa
 import numpy as np
 from smart_open import open
@@ -516,18 +517,30 @@ def _metadata(self):
             }
         return metadata_index
 
-    @core.copy_docs(load_audio)
+    @deprecated(
+        reason="Use mirdata.datasets.billboard.load_audio",
+        version="0.3.4",
+    )
     def load_audio(self, *args, **kwargs):
         return load_audio(*args, **kwargs)
 
-    @core.copy_docs(load_sections)
+    @deprecated(
+        reason="Use mirdata.datasets.billboard.load_sections",
+        version="0.3.4",
+    )
     def load_sections(self, *args, **kwargs):
         return load_sections(*args, **kwargs)
 
-    @core.copy_docs(load_named_sections)
+    @deprecated(
+        reason="Use mirdata.datasets.billboard.load_named_sections",
+        version="0.3.4",
+    )
     def load_named_sections(self, *args, **kwargs):
         return load_named_sections(*args, **kwargs)
 
-    @core.copy_docs(load_chords)
+    @deprecated(
+        reason="Use mirdata.datasets.billboard.load_chords",
+        version="0.3.4",
+    )
     def load_chords(self, *args, **kwargs):
         return load_chords(*args, **kwargs)

mirdata/datasets/cante100.py

@@ -49,6 +49,7 @@
 import xml.etree.ElementTree as ET
 from typing import Optional, TextIO, Tuple
 
+from deprecated.sphinx import deprecated
 import librosa
 import numpy as np
 from smart_open import open
@@ -423,18 +424,30 @@ def _metadata(self):
 
         return metadata
 
-    @core.copy_docs(load_audio)
+    @deprecated(
+        reason="Use mirdata.datasets.cante100.load_audio",
+        version="0.3.4",
+    )
     def load_audio(self, *args, **kwargs):
         return load_audio(*args, **kwargs)
 
-    @core.copy_docs(load_spectrogram)
+    @deprecated(
+        reason="Use mirdata.datasets.cante100.load_spectrogram",
+        version="0.3.4",
+    )
     def load_spectrogram(self, *args, **kwargs):
         return load_spectrogram(*args, **kwargs)
 
-    @core.copy_docs(load_melody)
+    @deprecated(
+        reason="Use mirdata.datasets.cante100.load_melody",
+        version="0.3.4",
+    )
     def load_melody(self, *args, **kwargs):
         return load_melody(*args, **kwargs)
 
-    @core.copy_docs(load_notes)
+    @deprecated(
+        reason="Use mirdata.datasets.cante100.load_notes",
+        version="0.3.4",
+    )
     def load_notes(self, *args, **kwargs):
         return load_notes(*args, **kwargs)